1 /************************************************************/
2 /* THIS FILE IS GENERATED DO NOT EDIT */
3 /************************************************************/
8 * #GAction is an opaque data structure and can only be accessed
9 * using the following functions.
16 * If @action is currently enabled.
18 * If the action is disabled then calls to g_action_activate() and
19 * g_action_change_state() have no effect.
28 * The name of the action. This is mostly meaningful for identifying
29 * the action once it has been added to a #GActionGroup. It is immutable.
36 * GAction:parameter-type:
38 * The type of the parameter that must be given when activating the
39 * action. This is immutable, and may be %NULL if no parameter is needed when
40 * activating the action.
49 * The state of the action, or %NULL if the action is stateless.
58 * The #GVariantType of the state that the action has, or %NULL if the
59 * action is stateless. This is immutable.
67 * @name: the name of the action
68 * @activate: the callback to connect to the "activate" signal of the
69 * action. Since GLib 2.40, this can be %NULL for stateful
70 * actions, in which case the default handler is used. For
71 * boolean-stated actions with no parameter, this is a
72 * toggle. For other state types (and parameter type equal
73 * to the state type) this will be a function that
74 * just calls @change_state (which you should provide).
75 * @parameter_type: the type of the parameter that must be passed to the
76 * activate function for this action, given as a single
77 * GVariant type string (or %NULL for no parameter)
78 * @state: the initial state for this action, given in
79 * [GVariant text format][gvariant-text]. The state is parsed
80 * with no extra type information, so type tags must be added to
81 * the string if they are necessary. Stateless actions should
83 * @change_state: the callback to connect to the "change-state" signal
84 * of the action. All stateful actions should provide a
85 * handler here; stateless actions should not.
87 * This struct defines a single action. It is for use with
88 * g_action_map_add_action_entries().
90 * The order of the items in the structure are intended to reflect
91 * frequency of use. It is permissible to use an incomplete initialiser
92 * in order to leave some of the later values as %NULL. All values
93 * after @name are optional. Additional optional fields may be added in
96 * See g_action_map_add_action_entries() for an example.
103 * #GActionGroup is an opaque data structure and can only be accessed
104 * using the following functions.
109 * GActionGroup::action-added:
110 * @action_group: the #GActionGroup that changed
111 * @action_name: the name of the action in @action_group
113 * Signals that a new action was just added to the group.
114 * This signal is emitted after the action has been added
115 * and is now visible.
122 * GActionGroup::action-enabled-changed:
123 * @action_group: the #GActionGroup that changed
124 * @action_name: the name of the action in @action_group
125 * @enabled: whether the action is enabled or not
127 * Signals that the enabled status of the named action has changed.
134 * GActionGroup::action-removed:
135 * @action_group: the #GActionGroup that changed
136 * @action_name: the name of the action in @action_group
138 * Signals that an action is just about to be removed from the group.
139 * This signal is emitted before the action is removed, so the action
140 * is still visible and can be queried from the signal handler.
147 * GActionGroup::action-state-changed:
148 * @action_group: the #GActionGroup that changed
149 * @action_name: the name of the action in @action_group
150 * @value: the new value of the state
152 * Signals that the state of the named action has changed.
159 * GActionGroupInterface:
160 * @has_action: the virtual function pointer for g_action_group_has_action()
161 * @list_actions: the virtual function pointer for g_action_group_list_actions()
162 * @get_action_parameter_type: the virtual function pointer for g_action_group_get_action_parameter_type()
163 * @get_action_state_type: the virtual function pointer for g_action_group_get_action_state_type()
164 * @get_action_state_hint: the virtual function pointer for g_action_group_get_action_state_hint()
165 * @get_action_enabled: the virtual function pointer for g_action_group_get_action_enabled()
166 * @get_action_state: the virtual function pointer for g_action_group_get_action_state()
167 * @change_action_state: the virtual function pointer for g_action_group_change_action_state()
168 * @query_action: the virtual function pointer for g_action_group_query_action()
169 * @activate_action: the virtual function pointer for g_action_group_activate_action()
170 * @action_added: the class closure for the #GActionGroup::action-added signal
171 * @action_removed: the class closure for the #GActionGroup::action-removed signal
172 * @action_enabled_changed: the class closure for the #GActionGroup::action-enabled-changed signal
173 * @action_state_changed: the class closure for the #GActionGroup::action-enabled-changed signal
175 * The virtual function table for #GActionGroup.
183 * @get_name: the virtual function pointer for g_action_get_name()
184 * @get_parameter_type: the virtual function pointer for g_action_get_parameter_type()
185 * @get_state_type: the virtual function pointer for g_action_get_state_type()
186 * @get_state_hint: the virtual function pointer for g_action_get_state_hint()
187 * @get_enabled: the virtual function pointer for g_action_get_enabled()
188 * @get_state: the virtual function pointer for g_action_get_state()
189 * @change_state: the virtual function pointer for g_action_change_state()
190 * @activate: the virtual function pointer for g_action_activate(). Note that #GAction does not have an
191 * 'activate' signal but that implementations of it may have one.
193 * The virtual function table for #GAction.
202 * #GActionMap is an opaque data structure and can only be accessed
203 * using the following functions.
208 * GActionMapInterface:
209 * @lookup_action: the virtual function pointer for g_action_map_lookup_action()
210 * @add_action: the virtual function pointer for g_action_map_add_action()
211 * @remove_action: the virtual function pointer for g_action_map_remove_action()
213 * The virtual function table for #GActionMap.
222 * The only thing you can do with this is to get it via
223 * g_app_info_monitor_get() and connect to the "changed" signal.
230 * GAppInfoMonitor::changed:
232 * Signal emitted when the app info database for changes (ie: newly installed
233 * or removed applications).
238 * GAppLaunchContext::launch-failed:
239 * @context: the object emitting the signal
240 * @startup_notify_id: the startup notification id for the failed launch
242 * The ::launch-failed signal is emitted when a #GAppInfo launch
243 * fails. The startup notification id is provided, so that the launcher
244 * can cancel the startup notification.
251 * GAppLaunchContext::launched:
252 * @context: the object emitting the signal
253 * @info: the #GAppInfo that was just launched
254 * @platform_data: additional platform-specific data for this launch
256 * The ::launched signal is emitted when a #GAppInfo is successfully
257 * launched. The @platform_data is an GVariant dictionary mapping
258 * strings to variants (ie a{sv}), which contains additional,
259 * platform-specific data about this launch. On UNIX, at least the
260 * "pid" and "startup-notification-id" keys will be present.
269 * #GApplication is an opaque data structure and can only be accessed
270 * using the following functions.
277 * GApplication::activate:
278 * @application: the application
280 * The ::activate signal is emitted on the primary instance when an
281 * activation occurs. See g_application_activate().
286 * GApplication::command-line:
287 * @application: the application
288 * @command_line: a #GApplicationCommandLine representing the
291 * The ::command-line signal is emitted on the primary instance when
292 * a commandline is not handled locally. See g_application_run() and
293 * the #GApplicationCommandLine documentation for more information.
295 * Returns: An integer that is set as the exit status for the calling
296 * process. See g_application_command_line_set_exit_status().
301 * GApplication::handle-local-options:
302 * @application: the application
303 * @options: the options dictionary
305 * The ::handle-local-options signal is emitted on the local instance
306 * after the parsing of the commandline options has occurred.
308 * You can add options to be recognised during commandline option
309 * parsing using g_application_add_main_option_entries() and
310 * g_application_add_option_group().
312 * Signal handlers can inspect @options (along with values pointed to
313 * from the @arg_data of an installed #GOptionEntrys) in order to
314 * decide to perform certain actions, including direct local handling
315 * (which may be useful for options like --version).
317 * In the event that the application is marked
318 * %G_APPLICATION_HANDLES_COMMAND_LINE the "normal processing" will
319 * send the @options dictionary to the primary instance where it can be
320 * read with g_application_command_line_get_options_dict(). The signal
321 * handler can modify the dictionary before returning, and the
322 * modified dictionary will be sent.
324 * In the event that %G_APPLICATION_HANDLES_COMMAND_LINE is not set,
325 * "normal processing" will treat the remaining uncollected command
326 * line arguments as filenames or URIs. If there are no arguments,
327 * the application is activated by g_application_activate(). One or
328 * more arguments results in a call to g_application_open().
330 * If you want to handle the local commandline arguments for yourself
331 * by converting them to calls to g_application_open() or
332 * g_action_group_activate_action() then you must be sure to register
333 * the application first. You should probably not call
334 * g_application_activate() for yourself, however: just return -1 and
335 * allow the default handler to do it for you. This will ensure that
336 * the `--gapplication-service` switch works properly (i.e. no activation
339 * Note that this signal is emitted from the default implementation of
340 * local_command_line(). If you override that function and don't
341 * chain up then this signal will never be emitted.
343 * You can override local_command_line() if you need more powerful
344 * capabilities than what is provided here, but this should not
345 * normally be required.
347 * Returns: an exit code. If you have handled your options and want
348 * to exit the process, return a non-negative option, 0 for success,
349 * and a positive value for failure. To continue, return -1 to let
350 * the default option processing continue.
356 * GApplication::open:
357 * @application: the application
358 * @files: (array length=n_files) (element-type GFile): an array of #GFiles
359 * @n_files: the length of @files
360 * @hint: a hint provided by the calling instance
362 * The ::open signal is emitted on the primary instance when there are
363 * files to open. See g_application_open() for more information.
368 * GApplication::shutdown:
369 * @application: the application
371 * The ::shutdown signal is emitted only on the registered primary instance
372 * immediately after the main loop terminates.
377 * GApplication::startup:
378 * @application: the application
380 * The ::startup signal is emitted on the primary instance immediately
381 * after registration. See g_application_register().
386 * GApplication:is-busy:
388 * Whether the application is currently marked as busy through
389 * g_application_mark_busy() or g_application_bind_busy_property().
397 * @startup: invoked on the primary instance immediately after registration
398 * @shutdown: invoked only on the registered primary instance immediately
399 * after the main loop terminates
400 * @activate: invoked on the primary instance when an activation occurs
401 * @open: invoked on the primary instance when there are files to open
402 * @command_line: invoked on the primary instance when a command-line is
403 * not handled locally
404 * @local_command_line: invoked (locally). The virtual function has the chance
405 * to inspect (and possibly replace) command line arguments. See
406 * g_application_run() for more information. Also see the
407 * #GApplication::handle-local-options signal, which is a simpler
408 * alternative to handling some commandline options locally
409 * @before_emit: invoked on the primary instance before 'activate', 'open',
410 * 'command-line' or any action invocation, gets the 'platform data' from
411 * the calling instance
412 * @after_emit: invoked on the primary instance after 'activate', 'open',
413 * 'command-line' or any action invocation, gets the 'platform data' from
414 * the calling instance
415 * @add_platform_data: invoked (locally) to add 'platform data' to be sent to
416 * the primary instance when activating, opening or invoking actions
417 * @quit_mainloop: Used to be invoked on the primary instance when the use
418 * count of the application drops to zero (and after any inactivity
419 * timeout, if requested). Not used anymore since 2.32
420 * @run_mainloop: Used to be invoked on the primary instance from
421 * g_application_run() if the use-count is non-zero. Since 2.32,
422 * GApplication is iterating the main context directly and is not
423 * using @run_mainloop anymore
424 * @dbus_register: invoked locally during registration, if the application is
425 * using its D-Bus backend. You can use this to export extra objects on the
426 * bus, that need to exist before the application tries to own the bus name.
427 * The function is passed the #GDBusConnection to to session bus, and the
428 * object path that #GApplication will use to export is D-Bus API.
429 * If this function returns %TRUE, registration will proceed; otherwise
430 * registration will abort. Since: 2.34
431 * @dbus_unregister: invoked locally during unregistration, if the application
432 * is using its D-Bus backend. Use this to undo anything done by the
433 * @dbus_register vfunc. Since: 2.34
434 * @handle_local_options: invoked locally after the parsing of the commandline
435 * options has occurred. Since: 2.40
437 * Virtual function table for #GApplication.
444 * GApplicationCommandLine:
446 * #GApplicationCommandLine is an opaque data structure and can only be accessed
447 * using the following functions.
452 * GApplicationCommandLineClass:
454 * The #GApplicationCommandLineClass-struct
455 * contains private data only.
464 * The bytes containing the icon.
469 * GCancellable::cancelled:
470 * @cancellable: a #GCancellable.
472 * Emitted when the operation has been cancelled.
474 * Can be used by implementations of cancellable operations. If the
475 * operation is cancelled from another thread, the signal will be
476 * emitted in the thread that cancelled the operation, not the
477 * thread that is running the operation.
479 * Note that disconnecting from this signal (or any signal) in a
480 * multi-threaded program is prone to race conditions. For instance
481 * it is possible that a signal handler may be invoked even after
482 * a call to g_signal_handler_disconnect() for that handler has
485 * There is also a problem when cancellation happens right before
486 * connecting to the signal. If this happens the signal will
487 * unexpectedly not be emitted, and checking before connecting to
488 * the signal leaves a race condition where this is still happening.
490 * In order to make it safe and easy to connect handlers there
491 * are two helper functions: g_cancellable_connect() and
492 * g_cancellable_disconnect() which protect against problems
495 * An example of how to us this:
496 * |[<!-- language="C" -->
497 * // Make sure we don't do unnecessary work if already cancelled
498 * if (g_cancellable_set_error_if_cancelled (cancellable, error))
501 * // Set up all the data needed to be able to handle cancellation
502 * // of the operation
503 * my_data = my_data_new (...);
507 * id = g_cancellable_connect (cancellable,
508 * G_CALLBACK (cancelled_handler)
511 * // cancellable operation here...
513 * g_cancellable_disconnect (cancellable, id);
515 * // cancelled_handler is never called after this, it is now safe
516 * // to free the data
517 * my_data_free (my_data);
520 * Note that the cancelled signal is emitted in the thread that
521 * the user cancelled from, which may be the main thread. So, the
522 * cancellable signal should not do something that can block.
529 * Conversions between character sets.
536 * The #GCredentials structure contains only private data and
537 * should only be accessed using the provided API.
546 * Class structure for #GCredentials.
555 * #GDBusActionGroup is an opaque data structure and can only be accessed
556 * using the following functions.
561 * GDBusAuthMechanism:credentials:
563 * If authenticating as a server, this property contains the
564 * received credentials, if any.
566 * If authenticating as a client, the property contains the
567 * credentials that were sent, if any.
574 * The #GDBusAuthObserver structure contains only private data and
575 * should only be accessed using the provided API.
582 * GDBusAuthObserver::allow-mechanism:
583 * @observer: The #GDBusAuthObserver emitting the signal.
584 * @mechanism: The name of the mechanism, e.g. `DBUS_COOKIE_SHA1`.
586 * Emitted to check if @mechanism is allowed to be used.
588 * Returns: %TRUE if @mechanism can be used to authenticate the other peer, %FALSE if not.
594 * GDBusAuthObserver::authorize-authenticated-peer:
595 * @observer: The #GDBusAuthObserver emitting the signal.
596 * @stream: A #GIOStream for the #GDBusConnection.
597 * @credentials: (allow-none): Credentials received from the peer or %NULL.
599 * Emitted to check if a peer that is successfully authenticated
602 * Returns: %TRUE if the peer is authorized, %FALSE if not.
608 * GDBusAuthObserverClass:
609 * @authorize_authenticated_peer: Signal class handler for the #GDBusAuthObserver::authorize-authenticated-peer signal.
611 * Class structure for #GDBusAuthObserverClass.
620 * The #GDBusConnection structure contains only private data and
621 * should only be accessed using the provided API.
628 * GDBusConnection::closed:
629 * @connection: the #GDBusConnection emitting the signal
630 * @remote_peer_vanished: %TRUE if @connection is closed because the
631 * remote peer closed its end of the connection
632 * @error: (allow-none): a #GError with more details about the event or %NULL
634 * Emitted when the connection is closed.
636 * The cause of this event can be
638 * - If g_dbus_connection_close() is called. In this case
639 * @remote_peer_vanished is set to %FALSE and @error is %NULL.
641 * - If the remote peer closes the connection. In this case
642 * @remote_peer_vanished is set to %TRUE and @error is set.
644 * - If the remote peer sends invalid or malformed data. In this
645 * case @remote_peer_vanished is set to %FALSE and @error is set.
647 * Upon receiving this signal, you should give up your reference to
648 * @connection. You are guaranteed that this signal is emitted only
656 * GDBusConnection:address:
658 * A D-Bus address specifying potential endpoints that can be used
659 * when establishing the connection.
666 * GDBusConnection:authentication-observer:
668 * A #GDBusAuthObserver object to assist in the authentication process or %NULL.
675 * GDBusConnection:capabilities:
677 * Flags from the #GDBusCapabilityFlags enumeration
678 * representing connection features negotiated with the other peer.
685 * GDBusConnection:closed:
687 * A boolean specifying whether the connection has been closed.
694 * GDBusConnection:exit-on-close:
696 * A boolean specifying whether the process will be terminated (by
697 * calling `raise(SIGTERM)`) if the connection is closed by the
700 * Note that #GDBusConnection objects returned by g_bus_get_finish()
701 * and g_bus_get_sync() will (usually) have this property set to %TRUE.
708 * GDBusConnection:flags:
710 * Flags from the #GDBusConnectionFlags enumeration.
717 * GDBusConnection:guid:
719 * The GUID of the peer performing the role of server when
722 * If you are constructing a #GDBusConnection and pass
723 * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER in the
724 * #GDBusConnection:flags property then you MUST also set this
725 * property to a valid guid.
727 * If you are constructing a #GDBusConnection and pass
728 * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_CLIENT in the
729 * #GDBusConnection:flags property you will be able to read the GUID
730 * of the other peer here after the connection has been successfully
738 * GDBusConnection:locked:
740 * A boolean specifying whether the message is locked.
747 * GDBusConnection:stream:
749 * The underlying #GIOStream used for I/O.
751 * If this is passed on construction and is a #GSocketConnection,
752 * then the corresponding #GSocket will be put into non-blocking mode.
754 * While the #GDBusConnection is active, it will interact with this
755 * stream from a worker thread, so it is not safe to interact with
756 * the stream directly.
763 * GDBusConnection:unique-name:
765 * The unique name as assigned by the message bus or %NULL if the
766 * connection is not open or not a message bus connection.
773 * GDBusConnectionClass:
774 * @closed: Signal class handler for the #GDBusConnection::closed signal.
776 * Class structure for #GDBusConnection.
783 * GDBusInterfaceSkeleton::g-authorize-method:
784 * @interface: The #GDBusInterfaceSkeleton emitting the signal.
785 * @invocation: A #GDBusMethodInvocation.
787 * Emitted when a method is invoked by a remote caller and used to
788 * determine if the method call is authorized.
790 * Note that this signal is emitted in a thread dedicated to
791 * handling the method call so handlers are allowed to perform
792 * blocking IO. This means that it is appropriate to call e.g.
793 * [polkit_authority_check_authorization_sync()](http://hal.freedesktop.org/docs/polkit/PolkitAuthority.html#polkit-authority-check-authorization-sync)
795 * [POLKIT_CHECK_AUTHORIZATION_FLAGS_ALLOW_USER_INTERACTION](http://hal.freedesktop.org/docs/polkit/PolkitAuthority.html#POLKIT-CHECK-AUTHORIZATION-FLAGS-ALLOW-USER-INTERACTION:CAPS)
798 * If %FALSE is returned then no further handlers are run and the
799 * signal handler must take a reference to @invocation and finish
800 * handling the call (e.g. return an error via
801 * g_dbus_method_invocation_return_error()).
803 * Otherwise, if %TRUE is returned, signal emission continues. If no
804 * handlers return %FALSE, then the method is dispatched. If
805 * @interface has an enclosing #GDBusObjectSkeleton, then the
806 * #GDBusObjectSkeleton::authorize-method signal handlers run before
807 * the handlers for this signal.
809 * The default class handler just returns %TRUE.
811 * Please note that the common case is optimized: if no signals
812 * handlers are connected and the default class handler isn't
813 * overridden (for both @interface and the enclosing
814 * #GDBusObjectSkeleton, if any) and #GDBusInterfaceSkeleton:g-flags does
816 * %G_DBUS_INTERFACE_SKELETON_FLAGS_HANDLE_METHOD_INVOCATIONS_IN_THREAD
817 * flags set, no dedicated thread is ever used and the call will be
818 * handled in the same thread as the object that @interface belongs
819 * to was exported in.
821 * Returns: %TRUE if the call is authorized, %FALSE otherwise.
827 * GDBusInterfaceSkeleton:g-flags:
829 * Flags from the #GDBusInterfaceSkeletonFlags enumeration.
838 * #GDBusMenuModel is an opaque data structure and can only be accessed
839 * using the following functions.
846 * The #GDBusMessage structure contains only private data and should
847 * only be accessed using the provided API.
856 * Class structure for #GDBusMessage.
863 * GDBusMethodInvocation:
865 * The #GDBusMethodInvocation structure contains only private data and
866 * should only be accessed using the provided API.
873 * GDBusMethodInvocationClass:
875 * Class structure for #GDBusMethodInvocation.
884 * #GDBusObject is an opaque data structure and can only be accessed
885 * using the following functions.
890 * GDBusObject::interface-added:
891 * @object: The #GDBusObject emitting the signal.
892 * @interface: The #GDBusInterface that was added.
894 * Emitted when @interface is added to @object.
901 * GDBusObject::interface-removed:
902 * @object: The #GDBusObject emitting the signal.
903 * @interface: The #GDBusInterface that was removed.
905 * Emitted when @interface is removed from @object.
912 * GDBusObjectManager:
914 * #GDBusObjectManager is an opaque data structure and can only be accessed
915 * using the following functions.
920 * GDBusObjectManager::interface-added:
921 * @manager: The #GDBusObjectManager emitting the signal.
922 * @object: The #GDBusObject on which an interface was added.
923 * @interface: The #GDBusInterface that was added.
925 * Emitted when @interface is added to @object.
927 * This signal exists purely as a convenience to avoid having to
928 * connect signals to all objects managed by @manager.
935 * GDBusObjectManager::interface-removed:
936 * @manager: The #GDBusObjectManager emitting the signal.
937 * @object: The #GDBusObject on which an interface was removed.
938 * @interface: The #GDBusInterface that was removed.
940 * Emitted when @interface has been removed from @object.
942 * This signal exists purely as a convenience to avoid having to
943 * connect signals to all objects managed by @manager.
950 * GDBusObjectManager::object-added:
951 * @manager: The #GDBusObjectManager emitting the signal.
952 * @object: The #GDBusObject that was added.
954 * Emitted when @object is added to @manager.
961 * GDBusObjectManager::object-removed:
962 * @manager: The #GDBusObjectManager emitting the signal.
963 * @object: The #GDBusObject that was removed.
965 * Emitted when @object is removed from @manager.
972 * GDBusObjectManagerClient::interface-proxy-properties-changed:
973 * @manager: The #GDBusObjectManagerClient emitting the signal.
974 * @object_proxy: The #GDBusObjectProxy on which an interface has properties that are changing.
975 * @interface_proxy: The #GDBusProxy that has properties that are changing.
976 * @changed_properties: A #GVariant containing the properties that changed.
977 * @invalidated_properties: A %NULL terminated array of properties that was invalidated.
979 * Emitted when one or more D-Bus properties on proxy changes. The
980 * local cache has already been updated when this signal fires. Note
981 * that both @changed_properties and @invalidated_properties are
982 * guaranteed to never be %NULL (either may be empty though).
984 * This signal exists purely as a convenience to avoid having to
985 * connect signals to all interface proxies managed by @manager.
987 * This signal is emitted in the
988 * [thread-default main context][g-main-context-push-thread-default]
989 * that @manager was constructed in.
996 * GDBusObjectManagerClient::interface-proxy-signal:
997 * @manager: The #GDBusObjectManagerClient emitting the signal.
998 * @object_proxy: The #GDBusObjectProxy on which an interface is emitting a D-Bus signal.
999 * @interface_proxy: The #GDBusProxy that is emitting a D-Bus signal.
1000 * @sender_name: The sender of the signal or NULL if the connection is not a bus connection.
1001 * @signal_name: The signal name.
1002 * @parameters: A #GVariant tuple with parameters for the signal.
1004 * Emitted when a D-Bus signal is received on @interface_proxy.
1006 * This signal exists purely as a convenience to avoid having to
1007 * connect signals to all interface proxies managed by @manager.
1009 * This signal is emitted in the
1010 * [thread-default main context][g-main-context-push-thread-default]
1011 * that @manager was constructed in.
1018 * GDBusObjectManagerClient:bus-type:
1020 * If this property is not %G_BUS_TYPE_NONE, then
1021 * #GDBusObjectManagerClient:connection must be %NULL and will be set to the
1022 * #GDBusConnection obtained by calling g_bus_get() with the value
1030 * GDBusObjectManagerClient:connection:
1032 * The #GDBusConnection to use.
1039 * GDBusObjectManagerClient:flags:
1041 * Flags from the #GDBusObjectManagerClientFlags enumeration.
1048 * GDBusObjectManagerClient:get-proxy-type-destroy-notify:
1050 * A #GDestroyNotify for the #gpointer user_data in #GDBusObjectManagerClient:get-proxy-type-user-data.
1057 * GDBusObjectManagerClient:get-proxy-type-func:
1059 * The #GDBusProxyTypeFunc to use when determining what #GType to
1060 * use for interface proxies or %NULL.
1067 * GDBusObjectManagerClient:get-proxy-type-user-data:
1069 * The #gpointer user_data to pass to #GDBusObjectManagerClient:get-proxy-type-func.
1076 * GDBusObjectManagerClient:name:
1078 * The well-known name or unique name that the manager is for.
1085 * GDBusObjectManagerClient:name-owner:
1087 * The unique name that owns #GDBusObjectManagerClient:name or %NULL if
1088 * no-one is currently owning the name. Connect to the
1089 * #GObject::notify signal to track changes to this property.
1096 * GDBusObjectManagerClient:object-path:
1098 * The object path the manager is for.
1105 * GDBusObjectManagerServer:connection:
1107 * The #GDBusConnection to export objects on.
1114 * GDBusObjectManagerServer:object-path:
1116 * The object path to register the manager object at.
1123 * GDBusObjectProxy:g-connection:
1125 * The connection of the proxy.
1132 * GDBusObjectProxy:g-object-path:
1134 * The object path of the proxy.
1141 * GDBusObjectSkeleton::authorize-method:
1142 * @object: The #GDBusObjectSkeleton emitting the signal.
1143 * @interface: The #GDBusInterfaceSkeleton that @invocation is for.
1144 * @invocation: A #GDBusMethodInvocation.
1146 * Emitted when a method is invoked by a remote caller and used to
1147 * determine if the method call is authorized.
1149 * This signal is like #GDBusInterfaceSkeleton's
1150 * #GDBusInterfaceSkeleton::g-authorize-method signal,
1151 * except that it is for the enclosing object.
1153 * The default class handler just returns %TRUE.
1155 * Returns: %TRUE if the call is authorized, %FALSE otherwise.
1161 * GDBusObjectSkeleton:g-object-path:
1163 * The object path where the object is exported.
1170 * GDBusProxy::g-properties-changed:
1171 * @proxy: The #GDBusProxy emitting the signal.
1172 * @changed_properties: A #GVariant containing the properties that changed
1173 * @invalidated_properties: A %NULL terminated array of properties that was invalidated
1175 * Emitted when one or more D-Bus properties on @proxy changes. The
1176 * local cache has already been updated when this signal fires. Note
1177 * that both @changed_properties and @invalidated_properties are
1178 * guaranteed to never be %NULL (either may be empty though).
1180 * If the proxy has the flag
1181 * %G_DBUS_PROXY_FLAGS_GET_INVALIDATED_PROPERTIES set, then
1182 * @invalidated_properties will always be empty.
1184 * This signal corresponds to the
1185 * `PropertiesChanged` D-Bus signal on the
1186 * `org.freedesktop.DBus.Properties` interface.
1193 * GDBusProxy::g-signal:
1194 * @proxy: The #GDBusProxy emitting the signal.
1195 * @sender_name: (allow-none): The sender of the signal or %NULL if the connection is not a bus connection.
1196 * @signal_name: The name of the signal.
1197 * @parameters: A #GVariant tuple with parameters for the signal.
1199 * Emitted when a signal from the remote object and interface that @proxy is for, has been received.
1206 * GDBusProxy:g-bus-type:
1208 * If this property is not %G_BUS_TYPE_NONE, then
1209 * #GDBusProxy:g-connection must be %NULL and will be set to the
1210 * #GDBusConnection obtained by calling g_bus_get() with the value
1218 * GDBusProxy:g-connection:
1220 * The #GDBusConnection the proxy is for.
1227 * GDBusProxy:g-default-timeout:
1229 * The timeout to use if -1 (specifying default timeout) is passed
1230 * as @timeout_msec in the g_dbus_proxy_call() and
1231 * g_dbus_proxy_call_sync() functions.
1233 * This allows applications to set a proxy-wide timeout for all
1234 * remote method invocations on the proxy. If this property is -1,
1235 * the default timeout (typically 25 seconds) is used. If set to
1236 * %G_MAXINT, then no timeout is used.
1243 * GDBusProxy:g-flags:
1245 * Flags from the #GDBusProxyFlags enumeration.
1252 * GDBusProxy:g-interface-info:
1254 * Ensure that interactions with this proxy conform to the given
1255 * interface. This is mainly to ensure that malformed data received
1256 * from the other peer is ignored. The given #GDBusInterfaceInfo is
1257 * said to be the "expected interface".
1259 * The checks performed are:
1260 * - When completing a method call, if the type signature of
1261 * the reply message isn't what's expected, the reply is
1262 * discarded and the #GError is set to %G_IO_ERROR_INVALID_ARGUMENT.
1264 * - Received signals that have a type signature mismatch are dropped and
1265 * a warning is logged via g_warning().
1267 * - Properties received via the initial `GetAll()` call or via the
1268 * `::PropertiesChanged` signal (on the
1269 * [org.freedesktop.DBus.Properties](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties)
1270 * interface) or set using g_dbus_proxy_set_cached_property()
1271 * with a type signature mismatch are ignored and a warning is
1272 * logged via g_warning().
1274 * Note that these checks are never done on methods, signals and
1275 * properties that are not referenced in the given
1276 * #GDBusInterfaceInfo, since extending a D-Bus interface on the
1277 * service-side is not considered an ABI break.
1284 * GDBusProxy:g-interface-name:
1286 * The D-Bus interface name the proxy is for.
1293 * GDBusProxy:g-name:
1295 * The well-known or unique name that the proxy is for.
1302 * GDBusProxy:g-name-owner:
1304 * The unique name that owns #GDBusProxy:g-name or %NULL if no-one
1305 * currently owns that name. You may connect to #GObject::notify signal to
1306 * track changes to this property.
1313 * GDBusProxy:g-object-path:
1315 * The object path the proxy is for.
1324 * The #GDBusServer structure contains only private data and
1325 * should only be accessed using the provided API.
1332 * GDBusServer::new-connection:
1333 * @server: The #GDBusServer emitting the signal.
1334 * @connection: A #GDBusConnection for the new connection.
1336 * Emitted when a new authenticated connection has been made. Use
1337 * g_dbus_connection_get_peer_credentials() to figure out what
1338 * identity (if any), was authenticated.
1340 * If you want to accept the connection, take a reference to the
1341 * @connection object and return %TRUE. When you are done with the
1342 * connection call g_dbus_connection_close() and give up your
1343 * reference. Note that the other peer may disconnect at any time -
1344 * a typical thing to do when accepting a connection is to listen to
1345 * the #GDBusConnection::closed signal.
1347 * If #GDBusServer:flags contains %G_DBUS_SERVER_FLAGS_RUN_IN_THREAD
1348 * then the signal is emitted in a new thread dedicated to the
1349 * connection. Otherwise the signal is emitted in the
1350 * [thread-default main context][g-main-context-push-thread-default]
1351 * of the thread that @server was constructed in.
1353 * You are guaranteed that signal handlers for this signal runs
1354 * before incoming messages on @connection are processed. This means
1355 * that it's suitable to call g_dbus_connection_register_object() or
1356 * similar from the signal handler.
1358 * Returns: %TRUE to claim @connection, %FALSE to let other handlers
1365 * GDBusServer:active:
1367 * Whether the server is currently active.
1374 * GDBusServer:address:
1376 * The D-Bus address to listen on.
1383 * GDBusServer:authentication-observer:
1385 * A #GDBusAuthObserver object to assist in the authentication process or %NULL.
1392 * GDBusServer:client-address:
1394 * The D-Bus address that clients can use.
1401 * GDBusServer:flags:
1403 * Flags from the #GDBusServerFlags enumeration.
1412 * The guid of the server.
1420 * @new_connection: Signal class handler for the #GDBusServer::new-connection signal.
1422 * Class structure for #GDBusServer.
1429 * GDataOutputStream:byte-order:
1431 * Determines the byte ordering that is used when writing
1432 * multi-byte entities (such as integers) to the stream.
1437 * GDataStream:byte-order:
1439 * The ::byte-order property determines the byte ordering that
1440 * is used when reading multi-byte entities (such as integers)
1446 * GDataStream:newline-type:
1448 * The :newline-type property determines what is considered
1449 * as a line ending when reading complete lines from the stream.
1456 * Information about an installed application from a desktop file.
1461 * GDesktopAppInfo:filename:
1463 * The origin filename of this #GDesktopAppInfo
1468 * GDesktopAppInfoLookup:
1470 * #GDesktopAppInfoLookup is an opaque data structure and can only be accessed
1471 * using the following functions.
1477 * @drive: a #GDrive.
1479 * Emitted when the drive's state has changed.
1484 * GDrive::disconnected:
1485 * @drive: a #GDrive.
1487 * This signal is emitted when the #GDrive have been
1488 * disconnected. If the recipient is holding references to the
1489 * object they should release them so the object can be
1495 * GDrive::eject-button:
1496 * @drive: a #GDrive.
1498 * Emitted when the physical eject button (if any) of a drive has
1504 * GDrive::stop-button:
1505 * @drive: a #GDrive.
1507 * Emitted when the physical stop button (if any) of a drive has
1515 * GDtlsClientConnection:
1517 * Abstract base class for the backend-specific client connection
1525 * GDtlsClientConnection:accepted-cas: (type GLib.List) (element-type GLib.ByteArray)
1527 * A list of the distinguished names of the Certificate Authorities
1528 * that the server will accept client certificates signed by. If the
1529 * server requests a client certificate during the handshake, then
1530 * this property will be set after the handshake completes.
1532 * Each item in the list is a #GByteArray which contains the complete
1533 * subject DN of the certificate authority.
1540 * GDtlsClientConnection:server-identity:
1542 * A #GSocketConnectable describing the identity of the server that
1543 * is expected on the other end of the connection.
1545 * If the %G_TLS_CERTIFICATE_BAD_IDENTITY flag is set in
1546 * #GDtlsClientConnection:validation-flags, this object will be used
1547 * to determine the expected identify of the remote end of the
1548 * connection; if #GDtlsClientConnection:server-identity is not set,
1549 * or does not match the identity presented by the server, then the
1550 * %G_TLS_CERTIFICATE_BAD_IDENTITY validation will fail.
1552 * In addition to its use in verifying the server certificate,
1553 * this is also used to give a hint to the server about what
1554 * certificate we expect, which is useful for servers that serve
1562 * GDtlsClientConnection:validation-flags:
1564 * What steps to perform when validating a certificate received from
1565 * a server. Server certificates that fail to validate in all of the
1566 * ways indicated here will be rejected unless the application
1567 * overrides the default via #GDtlsConnection::accept-certificate.
1576 * Abstract base class for the backend-specific #GDtlsClientConnection
1577 * and #GDtlsServerConnection types.
1584 * GDtlsConnection::accept-certificate:
1585 * @conn: a #GDtlsConnection
1586 * @peer_cert: the peer's #GTlsCertificate
1587 * @errors: the problems with @peer_cert.
1589 * Emitted during the TLS handshake after the peer certificate has
1590 * been received. You can examine @peer_cert's certification path by
1591 * calling g_tls_certificate_get_issuer() on it.
1593 * For a client-side connection, @peer_cert is the server's
1594 * certificate, and the signal will only be emitted if the
1595 * certificate was not acceptable according to @conn's
1596 * #GDtlsClientConnection:validation_flags. If you would like the
1597 * certificate to be accepted despite @errors, return %TRUE from the
1598 * signal handler. Otherwise, if no handler accepts the certificate,
1599 * the handshake will fail with %G_TLS_ERROR_BAD_CERTIFICATE.
1601 * For a server-side connection, @peer_cert is the certificate
1602 * presented by the client, if this was requested via the server's
1603 * #GDtlsServerConnection:authentication_mode. On the server side,
1604 * the signal is always emitted when the client presents a
1605 * certificate, and the certificate will only be accepted if a
1606 * handler returns %TRUE.
1608 * Note that if this signal is emitted as part of asynchronous I/O
1609 * in the main thread, then you should not attempt to interact with
1610 * the user before returning from the signal handler. If you want to
1611 * let the user decide whether or not to accept the certificate, you
1612 * would have to return %FALSE from the signal handler on the first
1613 * attempt, and then after the connection attempt returns a
1614 * %G_TLS_ERROR_HANDSHAKE, you can interact with the user, and if
1615 * the user decides to accept the certificate, remember that fact,
1616 * create a new connection, and return %TRUE from the signal handler
1619 * If you are doing I/O in another thread, you do not
1620 * need to worry about this, and can simply block in the signal
1621 * handler until the UI thread returns an answer.
1623 * Returns: %TRUE to accept @peer_cert (which will also
1624 * immediately end the signal emission). %FALSE to allow the signal
1625 * emission to continue, which will cause the handshake to fail if
1626 * no one else overrides it.
1632 * GDtlsConnection:base-socket:
1634 * The #GDatagramBased that the connection wraps. Note that this may be any
1635 * implementation of #GDatagramBased, not just a #GSocket.
1642 * GDtlsConnection:certificate:
1644 * The connection's certificate; see
1645 * g_dtls_connection_set_certificate().
1652 * GDtlsConnection:database:
1654 * The certificate database to use when verifying this TLS connection.
1655 * If no certificate database is set, then the default database will be
1656 * used. See g_dtls_backend_get_default_database().
1663 * GDtlsConnection:interaction:
1665 * A #GTlsInteraction object to be used when the connection or certificate
1666 * database need to interact with the user. This will be used to prompt the
1667 * user for passwords where necessary.
1674 * GDtlsConnection:peer-certificate:
1676 * The connection's peer's certificate, after the TLS handshake has
1677 * completed and the certificate has been accepted. Note in
1678 * particular that this is not yet set during the emission of
1679 * #GDtlsConnection::accept-certificate.
1681 * (You can watch for a #GObject::notify signal on this property to
1682 * detect when a handshake has occurred.)
1689 * GDtlsConnection:peer-certificate-errors:
1691 * The errors noticed-and-ignored while verifying
1692 * #GDtlsConnection:peer-certificate. Normally this should be 0, but
1693 * it may not be if #GDtlsClientConnection:validation-flags is not
1694 * %G_TLS_CERTIFICATE_VALIDATE_ALL, or if
1695 * #GDtlsConnection::accept-certificate overrode the default
1703 * GDtlsConnection:rehandshake-mode:
1705 * The rehandshaking mode. See
1706 * g_dtls_connection_set_rehandshake_mode().
1713 * GDtlsConnection:require-close-notify:
1715 * Whether or not proper TLS close notification is required.
1716 * See g_dtls_connection_set_require_close_notify().
1723 * GDtlsServerConnection:authentication-mode:
1725 * The #GTlsAuthenticationMode for the server. This can be changed
1726 * before calling g_dtls_connection_handshake() if you want to
1727 * rehandshake with a different mode from the initial handshake.
1736 * The file containing the icon.
1741 * GFileMonitor::changed:
1742 * @monitor: a #GFileMonitor.
1744 * @other_file: (allow-none): a #GFile or #NULL.
1745 * @event_type: a #GFileMonitorEvent.
1747 * Emitted when @file has been changed.
1749 * If using %G_FILE_MONITOR_WATCH_MOVES on a directory monitor, and
1750 * the information is available (and if supported by the backend),
1751 * @event_type may be %G_FILE_MONITOR_EVENT_RENAMED,
1752 * %G_FILE_MONITOR_EVENT_MOVED_IN or %G_FILE_MONITOR_EVENT_MOVED_OUT.
1754 * In all cases @file will be a child of the monitored directory. For
1755 * renames, @file will be the old name and @other_file is the new
1756 * name. For "moved in" events, @file is the name of the file that
1757 * appeared and @other_file is the old name that it was moved from (in
1758 * another directory). For "moved out" events, @file is the name of
1759 * the file that used to be in this directory and @other_file is the
1760 * name of the file at its new location.
1762 * It makes sense to treat %G_FILE_MONITOR_EVENT_MOVED_IN as
1763 * equivalent to %G_FILE_MONITOR_EVENT_CREATED and
1764 * %G_FILE_MONITOR_EVENT_MOVED_OUT as equivalent to
1765 * %G_FILE_MONITOR_EVENT_DELETED, with extra information.
1766 * %G_FILE_MONITOR_EVENT_RENAMED is equivalent to a delete/create
1767 * pair. This is exactly how the events will be reported in the case
1768 * that the %G_FILE_MONITOR_WATCH_MOVES flag is not in use.
1770 * If using the deprecated flag %G_FILE_MONITOR_SEND_MOVED flag and @event_type is
1771 * #G_FILE_MONITOR_EVENT_MOVED, @file will be set to a #GFile containing the
1772 * old path, and @other_file will be set to a #GFile containing the new path.
1774 * In all the other cases, @other_file will be set to #NULL.
1779 * GFilenameCompleter::got-completion-data:
1781 * Emitted when the file name completion information comes available.
1788 * #GIOExtension is an opaque data structure and can only be accessed
1789 * using the following functions.
1794 * GIOExtensionPoint:
1796 * #GIOExtensionPoint is an opaque data structure and can only be accessed
1797 * using the following functions.
1804 * Represents a scope for loading IO modules. A scope can be used for blocking
1805 * duplicate modules, or blocking a module you don't want to load.
1807 * The scope can be used with g_io_modules_load_all_in_directory_with_scope()
1808 * or g_io_modules_scan_all_in_directory_with_scope().
1817 * An IPv4 or IPv6 internet address.
1822 * GInetAddress:is-any:
1824 * Whether this is the "any" address for its family.
1825 * See g_inet_address_get_is_any().
1832 * GInetAddress:is-link-local:
1834 * Whether this is a link-local address.
1835 * See g_inet_address_get_is_link_local().
1842 * GInetAddress:is-loopback:
1844 * Whether this is the loopback address for its family.
1845 * See g_inet_address_get_is_loopback().
1852 * GInetAddress:is-mc-global:
1854 * Whether this is a global multicast address.
1855 * See g_inet_address_get_is_mc_global().
1862 * GInetAddress:is-mc-link-local:
1864 * Whether this is a link-local multicast address.
1865 * See g_inet_address_get_is_mc_link_local().
1872 * GInetAddress:is-mc-node-local:
1874 * Whether this is a node-local multicast address.
1875 * See g_inet_address_get_is_mc_node_local().
1882 * GInetAddress:is-mc-org-local:
1884 * Whether this is an organization-local multicast address.
1885 * See g_inet_address_get_is_mc_org_local().
1892 * GInetAddress:is-mc-site-local:
1894 * Whether this is a site-local multicast address.
1895 * See g_inet_address_get_is_mc_site_local().
1902 * GInetAddress:is-multicast:
1904 * Whether this is a multicast address.
1905 * See g_inet_address_get_is_multicast().
1912 * GInetAddress:is-site-local:
1914 * Whether this is a site-local address.
1915 * See g_inet_address_get_is_loopback().
1924 * A combination of an IPv4 or IPv6 base address and a length,
1925 * representing a range of IP addresses.
1932 * GInetSocketAddress:
1934 * An IPv4 or IPv6 socket address, corresponding to a struct
1935 * sockaddr_in or struct sockaddr_in6.
1940 * GInetSocketAddress:flowinfo:
1942 * The `sin6_flowinfo` field, for IPv6 addresses.
1949 * GInetSocketAddress:scope_id:
1951 * The `sin6_scope_id` field, for IPv6 addresses.
1960 * #GListModel is an opaque data structure and can only be accessed
1961 * using the following functions.
1966 * GListModel::items-changed:
1967 * @list: the #GListModel that changed
1968 * @position: the position at which @list changed
1969 * @removed: the number of items removed
1970 * @added: the number of items added
1972 * This signal is emitted whenever items were added or removed to
1973 * @list. At @position, @removed items were removed and @added items
1974 * were added in their place.
1981 * GListModelInterface:
1982 * @g_iface: parent #GTypeInterface
1983 * @get_item_type: the virtual function pointer for g_list_model_get_item_type()
1984 * @get_n_items: the virtual function pointer for g_list_model_get_n_items()
1985 * @get_item: the virtual function pointer for g_list_model_get_item()
1987 * The virtual function table for #GListModel.
1996 * #GListStore is an opaque data structure and can only be accessed
1997 * using the following functions.
2002 * GListStore:item-type:
2004 * The type of items contained in this list store. Items must be
2005 * subclasses of #GObject.
2012 * GMemoryOutputStream:data:
2014 * Pointer to buffer where data will be written.
2021 * GMemoryOutputStream:data-size:
2023 * Size of data written to the buffer.
2030 * GMemoryOutputStream:destroy-function: (skip)
2032 * Function called with the buffer as argument when the stream is destroyed.
2039 * GMemoryOutputStream:realloc-function: (skip)
2041 * Function with realloc semantics called to enlarge the buffer.
2048 * GMemoryOutputStream:size:
2050 * Current size of the data buffer.
2059 * #GMenu is an opaque structure type. You must access it using the
2067 * GMenuAttributeIter:
2069 * #GMenuAttributeIter is an opaque structure type. You must access it
2070 * using the functions below.
2079 * #GMenuItem is an opaque structure type. You must access it using the
2089 * #GMenuLinkIter is an opaque structure type. You must access it using
2090 * the functions below.
2099 * #GMenuModel is an opaque structure type. You must access it using the
2107 * GMenuModel::items-changed:
2108 * @model: the #GMenuModel that is changing
2109 * @position: the position of the change
2110 * @removed: the number of items removed
2111 * @added: the number of items added
2113 * Emitted when a change has occured to the menu.
2115 * The only changes that can occur to a menu is that items are removed
2116 * or added. Items may not change (except by being removed and added
2117 * back in the same location). This signal is capable of describing
2118 * both of those changes (at the same time).
2120 * The signal means that starting at the index @position, @removed
2121 * items were removed and @added items were added in their place. If
2122 * @removed is zero then only items were added. If @added is zero
2123 * then only items were removed.
2125 * As an example, if the menu contains items a, b, c, d (in that
2126 * order) and the signal (2, 1, 3) occurs then the new composition of
2127 * the menu will be a, b, _, _, _, d (with each _ representing some
2130 * Signal handlers may query the model (particularly the added items)
2131 * and expect to see the results of the modification that is being
2132 * reported. The signal is emitted after the modification.
2138 * @mount: the object on which the signal is emitted
2140 * Emitted when the mount has been changed.
2145 * GMount::pre-unmount:
2146 * @mount: the object on which the signal is emitted
2148 * This signal is emitted when the #GMount is about to be
2156 * GMount::unmounted:
2157 * @mount: the object on which the signal is emitted
2159 * This signal is emitted when the #GMount have been
2160 * unmounted. If the recipient is holding references to the
2161 * object they should release them so the object can be
2167 * GMountOperation::aborted:
2169 * Emitted by the backend when e.g. a device becomes unavailable
2170 * while a mount operation is in progress.
2172 * Implementations of GMountOperation should handle this signal
2173 * by dismissing open password dialogs.
2180 * GMountOperation::ask-password:
2181 * @op: a #GMountOperation requesting a password.
2182 * @message: string containing a message to display to the user.
2183 * @default_user: string containing the default user name.
2184 * @default_domain: string containing the default domain.
2185 * @flags: a set of #GAskPasswordFlags.
2187 * Emitted when a mount operation asks the user for a password.
2189 * If the message contains a line break, the first line should be
2190 * presented as a heading. For example, it may be used as the
2191 * primary text in a #GtkMessageDialog.
2196 * GMountOperation::ask-question:
2197 * @op: a #GMountOperation asking a question.
2198 * @message: string containing a message to display to the user.
2199 * @choices: an array of strings for each possible choice.
2201 * Emitted when asking the user a question and gives a list of
2202 * choices for the user to choose from.
2204 * If the message contains a line break, the first line should be
2205 * presented as a heading. For example, it may be used as the
2206 * primary text in a #GtkMessageDialog.
2211 * GMountOperation::reply:
2212 * @op: a #GMountOperation.
2213 * @result: a #GMountOperationResult indicating how the request was handled
2215 * Emitted when the user has replied to the mount operation.
2220 * GMountOperation::show-processes:
2221 * @op: a #GMountOperation.
2222 * @message: string containing a message to display to the user.
2223 * @processes: (element-type GPid): an array of #GPid for processes
2224 * blocking the operation.
2225 * @choices: an array of strings for each possible choice.
2227 * Emitted when one or more processes are blocking an operation
2228 * e.g. unmounting/ejecting a #GMount or stopping a #GDrive.
2230 * Note that this signal may be emitted several times to update the
2231 * list of blocking processes as processes close files. The
2232 * application should only respond with g_mount_operation_reply() to
2233 * the latest signal (setting #GMountOperation:choice to the choice
2236 * If the message contains a line break, the first line should be
2237 * presented as a heading. For example, it may be used as the
2238 * primary text in a #GtkMessageDialog.
2245 * GMountOperation::show-unmount-progress:
2246 * @op: a #GMountOperation:
2247 * @message: string containing a mesage to display to the user
2248 * @time_left: the estimated time left before the operation completes,
2249 * in microseconds, or -1
2250 * @bytes_left: the amount of bytes to be written before the operation
2251 * completes (or -1 if such amount is not known), or zero if the operation
2254 * Emitted when an unmount operation has been busy for more than some time
2255 * (typically 1.5 seconds).
2257 * When unmounting or ejecting a volume, the kernel might need to flush
2258 * pending data in its buffers to the volume stable storage, and this operation
2259 * can take a considerable amount of time. This signal may be emitted several
2260 * times as long as the unmount operation is outstanding, and then one
2261 * last time when the operation is completed, with @bytes_left set to zero.
2263 * Implementations of GMountOperation should handle this signal by
2264 * showing an UI notification, and then dismiss it, or show another notification
2265 * of completion, when @bytes_left reaches zero.
2267 * If the message contains a line break, the first line should be
2268 * presented as a heading. For example, it may be used as the
2269 * primary text in a #GtkMessageDialog.
2276 * GMountOperation:anonymous:
2278 * Whether to use an anonymous user when authenticating.
2283 * GMountOperation:choice:
2285 * The index of the user's choice when a question is asked during the
2286 * mount operation. See the #GMountOperation::ask-question signal.
2291 * GMountOperation:domain:
2293 * The domain to use for the mount operation.
2298 * GMountOperation:password:
2300 * The password that is used for authentication when carrying out
2301 * the mount operation.
2306 * GMountOperation:password-save:
2308 * Determines if and how the password information should be saved.
2313 * GMountOperation:username:
2315 * The user name that is used for authentication when carrying out
2316 * the mount operation.
2321 * GNativeSocketAddress:
2323 * An socket address, corresponding to a general struct
2324 * sockadd address of a type not otherwise handled by glib.
2331 * A #GSocketConnectable for resolving a hostname and connecting to
2339 * #GNetworkMonitor monitors the status of network connections and
2340 * indicates when a possibly-user-visible change has occurred.
2347 * GNetworkMonitor::network-changed:
2348 * @monitor: a #GNetworkMonitor
2349 * @available: the current value of #GNetworkMonitor:network-available
2351 * Emitted when the network configuration changes. If @available is
2352 * %TRUE, then some hosts may be reachable that were not reachable
2353 * before, while others that were reachable before may no longer be
2354 * reachable. If @available is %FALSE, then no remote hosts are
2362 * GNetworkMonitor:connectivity:
2364 * More detailed information about the host's network connectivity.
2365 * See g_network_monitor_get_connectivity() and
2366 * #GNetworkConnectivity for more details.
2373 * GNetworkMonitor:network-available:
2375 * Whether the network is considered available. That is, whether the
2376 * system has a default route for at least one of IPv4 or IPv6.
2378 * Real-world networks are of course much more complicated than
2379 * this; the machine may be connected to a wifi hotspot that
2380 * requires payment before allowing traffic through, or may be
2381 * connected to a functioning router that has lost its own upstream
2382 * connectivity. Some hosts might only be accessible when a VPN is
2383 * active. Other hosts might only be accessible when the VPN is
2384 * not active. Thus, it is best to use g_network_monitor_can_reach()
2385 * or g_network_monitor_can_reach_async() to test for reachability
2386 * on a host-by-host basis. (On the other hand, when the property is
2387 * %FALSE, the application can reasonably expect that no remote
2388 * hosts at all are reachable, and should indicate this to the user
2391 * See also #GNetworkMonitor::network-changed.
2398 * GNetworkMonitor:network-metered:
2400 * Whether the network is considered metered. That is, whether the
2401 * system has traffic flowing through the default connection that is
2402 * subject to limitations set by service providers. For example, traffic
2403 * might be billed by the amount of data transmitted, or there might be a
2404 * quota on the amount of traffic per month. This is typical with tethered
2405 * connections (3G and 4G) and in such situations, bandwidth intensive
2406 * applications may wish to avoid network activity where possible if it will
2407 * cost the user money or use up their limited quota.
2409 * If more information is required about specific devices then the
2410 * system network management API should be used instead (for example,
2411 * NetworkManager or ConnMan).
2413 * If this information is not available then no networks will be
2414 * marked as metered.
2416 * See also #GNetworkMonitor:network-available.
2423 * GNetworkMonitorInterface:
2424 * @g_iface: The parent interface.
2425 * @network_changed: the virtual function pointer for the
2426 * GNetworkMonitor::network-changed signal.
2427 * @can_reach: the virtual function pointer for g_network_monitor_can_reach()
2428 * @can_reach_async: the virtual function pointer for
2429 * g_network_monitor_can_reach_async()
2430 * @can_reach_finish: the virtual function pointer for
2431 * g_network_monitor_can_reach_finish()
2433 * The virtual function table for #GNetworkMonitor.
2442 * A #GSocketConnectable for resolving a SRV record and connecting to
2450 * This structure type is private and should only be accessed using the
2460 * #GPermission is an opaque data structure and can only be accessed
2461 * using the following functions.
2466 * GPermission:allowed:
2468 * %TRUE if the caller currently has permission to perform the action that
2469 * @permission represents the permission to perform.
2474 * GPermission:can-acquire:
2476 * %TRUE if it is generally possible to acquire the permission by calling
2477 * g_permission_acquire().
2482 * GPermission:can-release:
2484 * %TRUE if it is generally possible to release the permission by calling
2485 * g_permission_release().
2492 * This type is opaque.
2499 * GPropertyAction:enabled:
2501 * If @action is currently enabled.
2503 * If the action is disabled then calls to g_action_activate() and
2504 * g_action_change_state() have no effect.
2511 * GPropertyAction:invert-boolean:
2513 * If %TRUE, the state of the action will be the negation of the
2514 * property value, provided the property is boolean.
2521 * GPropertyAction:name:
2523 * The name of the action. This is mostly meaningful for identifying
2524 * the action once it has been added to a #GActionMap.
2531 * GPropertyAction:object:
2533 * The object to wrap a property on.
2535 * The object must be a non-%NULL #GObject with properties.
2542 * GPropertyAction:parameter-type:
2544 * The type of the parameter that must be given when activating the
2552 * GPropertyAction:property-name:
2554 * The name of the property to wrap on the object.
2556 * The property must exist on the passed-in object and it must be
2557 * readable and writable (and not construct-only).
2564 * GPropertyAction:state:
2566 * The state of the action, or %NULL if the action is stateless.
2573 * GPropertyAction:state-type:
2575 * The #GVariantType of the state that the action has, or %NULL if the
2576 * action is stateless.
2585 * A #GInetSocketAddress representing a connection via a proxy server
2592 * GProxyAddress:destination-protocol:
2594 * The protocol being spoke to the destination host, or %NULL if
2595 * the #GProxyAddress doesn't know.
2602 * GProxyAddress:uri:
2604 * The URI string that the proxy was constructed from (or %NULL
2605 * if the creator didn't specify this).
2612 * GProxyAddressClass:
2614 * Class structure for #GProxyAddress.
2621 * GProxyAddressEnumerator:default-port:
2623 * The default port to use if #GProxyAddressEnumerator:uri does not
2631 * GProxyAddressEnumerator:proxy-resolver:
2633 * The proxy resolver to use.
2640 * GProxyResolverInterface:
2641 * @g_iface: The parent interface.
2642 * @is_supported: the virtual function pointer for g_proxy_resolver_is_supported()
2643 * @lookup: the virtual function pointer for g_proxy_resolver_lookup()
2644 * @lookup_async: the virtual function pointer for
2645 * g_proxy_resolver_lookup_async()
2646 * @lookup_finish: the virtual function pointer for
2647 * g_proxy_resolver_lookup_finish()
2649 * The virtual function table for #GProxyResolver.
2654 * GRemoteActionGroup:
2656 * #GRemoteActionGroup is an opaque data structure and can only be accessed
2657 * using the following functions.
2662 * GRemoteActionGroupInterface:
2663 * @activate_action_full: the virtual function pointer for g_remote_action_group_activate_action_full()
2664 * @change_action_state_full: the virtual function pointer for g_remote_action_group_change_action_state_full()
2666 * The virtual function table for #GRemoteActionGroup.
2675 * The object that handles DNS resolution. Use g_resolver_get_default()
2676 * to get the default resolver.
2681 * GResolver::reload:
2682 * @resolver: a #GResolver
2684 * Emitted when the resolver notices that the system resolver
2685 * configuration has changed.
2692 * #GSettings is an opaque data structure and can only be accessed
2693 * using the following functions.
2698 * GSettings::change-event:
2699 * @settings: the object on which the signal was emitted
2700 * @keys: (array length=n_keys) (element-type GQuark) (allow-none):
2701 * an array of #GQuarks for the changed keys, or %NULL
2702 * @n_keys: the length of the @keys array, or 0
2704 * The "change-event" signal is emitted once per change event that
2705 * affects this settings object. You should connect to this signal
2706 * only if you are interested in viewing groups of changes before they
2707 * are split out into multiple emissions of the "changed" signal.
2708 * For most use cases it is more appropriate to use the "changed" signal.
2710 * In the event that the change event applies to one or more specified
2711 * keys, @keys will be an array of #GQuark of length @n_keys. In the
2712 * event that the change event applies to the #GSettings object as a
2713 * whole (ie: potentially every key has been changed) then @keys will
2714 * be %NULL and @n_keys will be 0.
2716 * The default handler for this signal invokes the "changed" signal
2717 * for each affected key. If any other connected handler returns
2718 * %TRUE then this default functionality will be suppressed.
2720 * Returns: %TRUE to stop other handlers from being invoked for the
2721 * event. FALSE to propagate the event further.
2726 * GSettings::changed:
2727 * @settings: the object on which the signal was emitted
2728 * @key: the name of the key that changed
2730 * The "changed" signal is emitted when a key has potentially changed.
2731 * You should call one of the g_settings_get() calls to check the new
2734 * This signal supports detailed connections. You can connect to the
2735 * detailed signal "changed::x" in order to only receive callbacks
2736 * when key "x" changes.
2738 * Note that @settings only emits this signal if you have read @key at
2739 * least once while a signal handler was already connected for @key.
2744 * GSettings::writable-change-event:
2745 * @settings: the object on which the signal was emitted
2746 * @key: the quark of the key, or 0
2748 * The "writable-change-event" signal is emitted once per writability
2749 * change event that affects this settings object. You should connect
2750 * to this signal if you are interested in viewing groups of changes
2751 * before they are split out into multiple emissions of the
2752 * "writable-changed" signal. For most use cases it is more
2753 * appropriate to use the "writable-changed" signal.
2755 * In the event that the writability change applies only to a single
2756 * key, @key will be set to the #GQuark for that key. In the event
2757 * that the writability change affects the entire settings object,
2760 * The default handler for this signal invokes the "writable-changed"
2761 * and "changed" signals for each affected key. This is done because
2762 * changes in writability might also imply changes in value (if for
2763 * example, a new mandatory setting is introduced). If any other
2764 * connected handler returns %TRUE then this default functionality
2765 * will be suppressed.
2767 * Returns: %TRUE to stop other handlers from being invoked for the
2768 * event. FALSE to propagate the event further.
2773 * GSettings::writable-changed:
2774 * @settings: the object on which the signal was emitted
2777 * The "writable-changed" signal is emitted when the writability of a
2778 * key has potentially changed. You should call
2779 * g_settings_is_writable() in order to determine the new status.
2781 * This signal supports detailed connections. You can connect to the
2782 * detailed signal "writable-changed::x" in order to only receive
2783 * callbacks when the writability of "x" changes.
2788 * GSettings:context:
2790 * The name of the context that the settings are stored in.
2795 * GSettings:delay-apply:
2797 * Whether the #GSettings object is in 'delay-apply' mode. See
2798 * g_settings_delay() for details.
2805 * GSettings:has-unapplied:
2807 * If this property is %TRUE, the #GSettings object has outstanding
2808 * changes that will be applied when g_settings_apply() is called.
2815 * The path within the backend where the settings are stored.
2822 * The name of the schema that describes the types of keys
2823 * for this #GSettings object.
2825 * The type of this property is *not* #GSettingsSchema.
2826 * #GSettingsSchema has only existed since version 2.32 and
2827 * unfortunately this name was used in previous versions to refer to
2828 * the schema ID rather than the schema itself. Take care to use the
2829 * 'settings-schema' property if you wish to pass in a
2832 * Deprecated: 2.32: Use the 'schema-id' property instead. In a future
2833 * version, this property may instead refer to a #GSettingsSchema.
2838 * GSettings:schema-id:
2840 * The name of the schema that describes the types of keys
2841 * for this #GSettings object.
2846 * GSettings:settings-schema:
2848 * The #GSettingsSchema describing the types of keys for this
2849 * #GSettings object.
2851 * Ideally, this property would be called 'schema'. #GSettingsSchema
2852 * has only existed since version 2.32, however, and before then the
2853 * 'schema' property was used to refer to the ID of the schema rather
2854 * than the schema itself. Take care.
2861 * This is an opaque structure type. You may not access it directly.
2868 * GSettingsSchemaKey:
2870 * #GSettingsSchemaKey is an opaque data structure and can only be accessed
2871 * using the following functions.
2876 * GSettingsSchemaSource:
2878 * This is an opaque structure type. You may not access it directly.
2887 * #GSimpleAction is an opaque data structure and can only be accessed
2888 * using the following functions.
2893 * GSimpleAction::activate:
2894 * @simple: the #GSimpleAction
2895 * @parameter: (allow-none): the parameter to the activation
2897 * Indicates that the action was just activated.
2899 * @parameter will always be of the expected type. In the event that
2900 * an incorrect type was given, no signal will be emitted.
2902 * Since GLib 2.40, if no handler is connected to this signal then the
2903 * default behaviour for boolean-stated actions with a %NULL parameter
2904 * type is to toggle them via the #GSimpleAction::change-state signal.
2905 * For stateful actions where the state type is equal to the parameter
2906 * type, the default is to forward them directly to
2907 * #GSimpleAction::change-state. This should allow almost all users
2908 * of #GSimpleAction to connect only one handler or the other.
2915 * GSimpleAction::change-state:
2916 * @simple: the #GSimpleAction
2917 * @value: (allow-none): the requested value for the state
2919 * Indicates that the action just received a request to change its
2922 * @value will always be of the correct state type. In the event that
2923 * an incorrect type was given, no signal will be emitted.
2925 * If no handler is connected to this signal then the default
2926 * behaviour is to call g_simple_action_set_state() to set the state
2927 * to the requested value. If you connect a signal handler then no
2928 * default action is taken. If the state should change then you must
2929 * call g_simple_action_set_state() from the handler.
2931 * An example of a 'change-state' handler:
2932 * |[<!-- language="C" -->
2934 * change_volume_state (GSimpleAction *action,
2936 * gpointer user_data)
2940 * requested = g_variant_get_int32 (value);
2942 * // Volume only goes from 0 to 10
2943 * if (0 <= requested && requested <= 10)
2944 * g_simple_action_set_state (action, value);
2948 * The handler need not set the state to the requested value.
2949 * It could set it to any value at all, or take some other action.
2956 * GSimpleAction:enabled:
2958 * If @action is currently enabled.
2960 * If the action is disabled then calls to g_action_activate() and
2961 * g_action_change_state() have no effect.
2968 * GSimpleAction:name:
2970 * The name of the action. This is mostly meaningful for identifying
2971 * the action once it has been added to a #GSimpleActionGroup.
2978 * GSimpleAction:parameter-type:
2980 * The type of the parameter that must be given when activating the
2988 * GSimpleAction:state:
2990 * The state of the action, or %NULL if the action is stateless.
2997 * GSimpleAction:state-type:
2999 * The #GVariantType of the state that the action has, or %NULL if the
3000 * action is stateless.
3009 * A wrapper around a #GInputStream and a #GOutputStream.
3016 * GSimpleIOStream:input-stream:
3023 * GSimpleIOStream:output-stream:
3030 * GSimplePermission:
3032 * #GSimplePermission is an opaque data structure. There are no methods
3033 * except for those defined by #GPermission.
3038 * GSimpleProxyResolver:default-proxy:
3040 * The default proxy URI that will be used for any URI that doesn't
3041 * match #GSimpleProxyResolver:ignore-hosts, and doesn't match any
3042 * of the schemes set with g_simple_proxy_resolver_set_uri_proxy().
3044 * Note that as a special case, if this URI starts with
3045 * "socks://", #GSimpleProxyResolver will treat it as referring
3046 * to all three of the socks5, socks4a, and socks4 proxy types.
3051 * GSimpleProxyResolver:ignore-hosts:
3053 * A list of hostnames and IP addresses that the resolver should
3054 * allow direct connections to.
3056 * Entries can be in one of 4 formats:
3058 * - A hostname, such as "example.com", ".example.com", or
3059 * "*.example.com", any of which match "example.com" or
3060 * any subdomain of it.
3062 * - An IPv4 or IPv6 address, such as "192.168.1.1",
3063 * which matches only that address.
3065 * - A hostname or IP address followed by a port, such as
3066 * "example.com:80", which matches whatever the hostname or IP
3067 * address would match, but only for URLs with the (explicitly)
3068 * indicated port. In the case of an IPv6 address, the address
3069 * part must appear in brackets: "[::1]:443"
3071 * - An IP address range, given by a base address and prefix length,
3072 * such as "fe80::/10", which matches any address in that range.
3074 * Note that when dealing with Unicode hostnames, the matching is
3075 * done against the ASCII form of the name.
3077 * Also note that hostname exclusions apply only to connections made
3078 * to hosts identified by name, and IP address exclusions apply only
3079 * to connections made to hosts identified by address. That is, if
3080 * example.com has an address of 192.168.1.1, and the :ignore-hosts list
3081 * contains only "192.168.1.1", then a connection to "example.com"
3082 * (eg, via a #GNetworkAddress) will use the proxy, and a connection to
3083 * "192.168.1.1" (eg, via a #GInetSocketAddress) will not.
3085 * These rules match the "ignore-hosts"/"noproxy" rules most
3086 * commonly used by other applications.
3091 * GSocket:broadcast:
3093 * Whether the socket should allow sending to broadcast addresses.
3100 * GSocket:multicast-loopback:
3102 * Whether outgoing multicast packets loop back to the local host.
3109 * GSocket:multicast-ttl:
3111 * Time-to-live out outgoing multicast packets
3120 * The timeout in seconds on socket I/O
3129 * Time-to-live for outgoing unicast packets
3138 * A socket endpoint address, corresponding to struct sockaddr
3139 * or one of its subtypes.
3144 * GSocketClient::event:
3145 * @client: the #GSocketClient
3146 * @event: the event that is occurring
3147 * @connectable: the #GSocketConnectable that @event is occurring on
3148 * @connection: (nullable): the current representation of the connection
3150 * Emitted when @client's activity on @connectable changes state.
3151 * Among other things, this can be used to provide progress
3152 * information about a network connection in the UI. The meanings of
3153 * the different @event values are as follows:
3155 * - %G_SOCKET_CLIENT_RESOLVING: @client is about to look up @connectable
3156 * in DNS. @connection will be %NULL.
3158 * - %G_SOCKET_CLIENT_RESOLVED: @client has successfully resolved
3159 * @connectable in DNS. @connection will be %NULL.
3161 * - %G_SOCKET_CLIENT_CONNECTING: @client is about to make a connection
3162 * to a remote host; either a proxy server or the destination server
3163 * itself. @connection is the #GSocketConnection, which is not yet
3164 * connected. Since GLib 2.40, you can access the remote
3165 * address via g_socket_connection_get_remote_address().
3167 * - %G_SOCKET_CLIENT_CONNECTED: @client has successfully connected
3168 * to a remote host. @connection is the connected #GSocketConnection.
3170 * - %G_SOCKET_CLIENT_PROXY_NEGOTIATING: @client is about to negotiate
3171 * with a proxy to get it to connect to @connectable. @connection is
3172 * the #GSocketConnection to the proxy server.
3174 * - %G_SOCKET_CLIENT_PROXY_NEGOTIATED: @client has negotiated a
3175 * connection to @connectable through a proxy server. @connection is
3176 * the stream returned from g_proxy_connect(), which may or may not
3177 * be a #GSocketConnection.
3179 * - %G_SOCKET_CLIENT_TLS_HANDSHAKING: @client is about to begin a TLS
3180 * handshake. @connection is a #GTlsClientConnection.
3182 * - %G_SOCKET_CLIENT_TLS_HANDSHAKED: @client has successfully completed
3183 * the TLS handshake. @connection is a #GTlsClientConnection.
3185 * - %G_SOCKET_CLIENT_COMPLETE: @client has either successfully connected
3186 * to @connectable (in which case @connection is the #GSocketConnection
3187 * that it will be returning to the caller) or has failed (in which
3188 * case @connection is %NULL and the client is about to return an error).
3190 * Each event except %G_SOCKET_CLIENT_COMPLETE may be emitted
3191 * multiple times (or not at all) for a given connectable (in
3192 * particular, if @client ends up attempting to connect to more than
3193 * one address). However, if @client emits the #GSocketClient::event
3194 * signal at all for a given connectable, that it will always emit
3195 * it with %G_SOCKET_CLIENT_COMPLETE when it is done.
3197 * Note that there may be additional #GSocketClientEvent values in
3198 * the future; unrecognized @event values should be ignored.
3205 * GSocketClient:proxy-resolver:
3207 * The proxy resolver to use
3214 * GSocketListener::event:
3215 * @listener: the #GSocketListener
3216 * @event: the event that is occurring
3217 * @socket: the #GSocket the event is occurring on
3219 * Emitted when @listener's activity on @socket changes state.
3220 * Note that when @listener is used to listen on both IPv4 and
3221 * IPv6, a separate set of signals will be emitted for each, and
3222 * the order they happen in is undefined.
3229 * GSocketService::incoming:
3230 * @service: the #GSocketService
3231 * @connection: a new #GSocketConnection object
3232 * @source_object: (allow-none): the source_object passed to
3233 * g_socket_listener_add_address()
3235 * The ::incoming signal is emitted when a new incoming connection
3236 * to @service needs to be handled. The handler must initiate the
3237 * handling of @connection, but may not block; in essence,
3238 * asynchronous operations must be used.
3240 * @connection will be unreffed once the signal handler returns,
3241 * so you need to ref it yourself if you are planning to use it.
3243 * Returns: %TRUE to stop other handlers from being called
3249 * GSocketService:active:
3251 * Whether the service is currently accepting connections.
3260 * A single target host/port that a network service is running on.
3267 * #GStaticResource is an opaque data structure and can only be accessed
3268 * using the following functions.
3275 * The opaque object representing a synchronous or asynchronous task
3283 * Whether the task has completed, meaning its callback (if set) has been
3284 * invoked. This can only happen after g_task_return_pointer(),
3285 * g_task_return_error() or one of the other return functions have been called
3288 * This property is guaranteed to change from %FALSE to %TRUE exactly once.
3290 * The #GObject::notify signal for this change is emitted in the same main
3291 * context as the task’s callback, immediately after that callback is invoked.
3300 * @source_object: (type GObject): @task's source object
3301 * @task_data: @task's task data
3302 * @cancellable: @task's #GCancellable, or %NULL
3304 * The prototype for a task function to be run in a thread via
3305 * g_task_run_in_thread() or g_task_run_in_thread_sync().
3307 * If the return-on-cancel flag is set on @task, and @cancellable gets
3308 * cancelled, then the #GTask will be completed immediately (as though
3309 * g_task_return_error_if_cancelled() had been called), without
3310 * waiting for the task function to complete. However, the task
3311 * function will continue running in its thread in the background. The
3312 * function therefore needs to be careful about how it uses
3313 * externally-visible state in this case. See
3314 * g_task_set_return_on_cancel() for more details.
3316 * Other than in that case, @task will be completed when the
3317 * #GTaskThreadFunc returns, not when it calls a
3318 * `g_task_return_` function.
3325 * GTcpWrapperConnection:
3327 * #GTcpWrapperConnection is an opaque data structure and can only be accessed
3328 * using the following functions.
3335 * The #GTestDBus structure contains only private data and
3336 * should only be accessed using the provided API.
3345 * #GTestDBusFlags specifying the behaviour of the D-Bus session.
3359 * GThemedIcon:names:
3361 * A %NULL-terminated array of icon names.
3366 * GThemedIcon:use-default-fallbacks:
3368 * Whether to use the default fallbacks found by shortening the icon name
3369 * at '-' characters. If the "names" array has more than one element,
3370 * ignores any past the first.
3372 * For example, if the icon name was "gnome-dev-cdrom-audio", the array
3374 * |[<!-- language="C" -->
3376 * "gnome-dev-cdrom-audio",
3377 * "gnome-dev-cdrom",
3387 * GThreadedSocketService::run:
3388 * @service: the #GThreadedSocketService.
3389 * @connection: a new #GSocketConnection object.
3390 * @source_object: the source_object passed to g_socket_listener_add_address().
3392 * The ::run signal is emitted in a worker thread in response to an
3393 * incoming connection. This thread is dedicated to handling
3394 * @connection and may perform blocking IO. The signal handler need
3395 * not return until the connection is closed.
3397 * Returns: %TRUE to stop further signal handlers from being called
3404 * TLS (Transport Layer Security, aka SSL) and DTLS backend. This is an
3405 * internal type used to coordinate the different classes implemented
3415 * Abstract base class for TLS certificate types.
3422 * GTlsCertificate:certificate:
3424 * The DER (binary) encoded representation of the certificate.
3425 * This property and the #GTlsCertificate:certificate-pem property
3426 * represent the same data, just in different forms.
3433 * GTlsCertificate:certificate-pem:
3435 * The PEM (ASCII) encoded representation of the certificate.
3436 * This property and the #GTlsCertificate:certificate
3437 * property represent the same data, just in different forms.
3444 * GTlsCertificate:issuer:
3446 * A #GTlsCertificate representing the entity that issued this
3447 * certificate. If %NULL, this means that the certificate is either
3448 * self-signed, or else the certificate of the issuer is not
3456 * GTlsCertificate:private-key:
3458 * The DER (binary) encoded representation of the certificate's
3459 * private key, in either PKCS#1 format or unencrypted PKCS#8
3460 * format. This property (or the #GTlsCertificate:private-key-pem
3461 * property) can be set when constructing a key (eg, from a file),
3462 * but cannot be read.
3464 * PKCS#8 format is supported since 2.32; earlier releases only
3465 * support PKCS#1. You can use the `openssl rsa`
3466 * tool to convert PKCS#8 keys to PKCS#1.
3473 * GTlsCertificate:private-key-pem:
3475 * The PEM (ASCII) encoded representation of the certificate's
3476 * private key in either PKCS#1 format ("`BEGIN RSA PRIVATE
3477 * KEY`") or unencrypted PKCS#8 format ("`BEGIN
3478 * PRIVATE KEY`"). This property (or the
3479 * #GTlsCertificate:private-key property) can be set when
3480 * constructing a key (eg, from a file), but cannot be read.
3482 * PKCS#8 format is supported since 2.32; earlier releases only
3483 * support PKCS#1. You can use the `openssl rsa`
3484 * tool to convert PKCS#8 keys to PKCS#1.
3491 * GTlsClientConnection:
3493 * Abstract base class for the backend-specific client connection
3501 * GTlsClientConnection:accepted-cas: (type GLib.List) (element-type GLib.ByteArray)
3503 * A list of the distinguished names of the Certificate Authorities
3504 * that the server will accept client certificates signed by. If the
3505 * server requests a client certificate during the handshake, then
3506 * this property will be set after the handshake completes.
3508 * Each item in the list is a #GByteArray which contains the complete
3509 * subject DN of the certificate authority.
3516 * GTlsClientConnection:server-identity:
3518 * A #GSocketConnectable describing the identity of the server that
3519 * is expected on the other end of the connection.
3521 * If the %G_TLS_CERTIFICATE_BAD_IDENTITY flag is set in
3522 * #GTlsClientConnection:validation-flags, this object will be used
3523 * to determine the expected identify of the remote end of the
3524 * connection; if #GTlsClientConnection:server-identity is not set,
3525 * or does not match the identity presented by the server, then the
3526 * %G_TLS_CERTIFICATE_BAD_IDENTITY validation will fail.
3528 * In addition to its use in verifying the server certificate,
3529 * this is also used to give a hint to the server about what
3530 * certificate we expect, which is useful for servers that serve
3538 * GTlsClientConnection:use-ssl3:
3540 * If %TRUE, tells the connection to use a fallback version of TLS
3541 * or SSL, rather than trying to negotiate the best version of TLS
3542 * to use. This can be used when talking to servers that don't
3543 * implement version negotiation correctly and therefore refuse to
3544 * handshake at all with a "modern" TLS handshake.
3546 * Despite the property name, the fallback version is not
3547 * necessarily SSL 3.0; if SSL 3.0 has been disabled, the
3548 * #GTlsClientConnection will use the next highest available version
3549 * (normally TLS 1.0) as the fallback version.
3556 * GTlsClientConnection:validation-flags:
3558 * What steps to perform when validating a certificate received from
3559 * a server. Server certificates that fail to validate in all of the
3560 * ways indicated here will be rejected unless the application
3561 * overrides the default via #GTlsConnection::accept-certificate.
3570 * Abstract base class for the backend-specific #GTlsClientConnection
3571 * and #GTlsServerConnection types.
3578 * GTlsConnection::accept-certificate:
3579 * @conn: a #GTlsConnection
3580 * @peer_cert: the peer's #GTlsCertificate
3581 * @errors: the problems with @peer_cert.
3583 * Emitted during the TLS handshake after the peer certificate has
3584 * been received. You can examine @peer_cert's certification path by
3585 * calling g_tls_certificate_get_issuer() on it.
3587 * For a client-side connection, @peer_cert is the server's
3588 * certificate, and the signal will only be emitted if the
3589 * certificate was not acceptable according to @conn's
3590 * #GTlsClientConnection:validation_flags. If you would like the
3591 * certificate to be accepted despite @errors, return %TRUE from the
3592 * signal handler. Otherwise, if no handler accepts the certificate,
3593 * the handshake will fail with %G_TLS_ERROR_BAD_CERTIFICATE.
3595 * For a server-side connection, @peer_cert is the certificate
3596 * presented by the client, if this was requested via the server's
3597 * #GTlsServerConnection:authentication_mode. On the server side,
3598 * the signal is always emitted when the client presents a
3599 * certificate, and the certificate will only be accepted if a
3600 * handler returns %TRUE.
3602 * Note that if this signal is emitted as part of asynchronous I/O
3603 * in the main thread, then you should not attempt to interact with
3604 * the user before returning from the signal handler. If you want to
3605 * let the user decide whether or not to accept the certificate, you
3606 * would have to return %FALSE from the signal handler on the first
3607 * attempt, and then after the connection attempt returns a
3608 * %G_TLS_ERROR_HANDSHAKE, you can interact with the user, and if
3609 * the user decides to accept the certificate, remember that fact,
3610 * create a new connection, and return %TRUE from the signal handler
3613 * If you are doing I/O in another thread, you do not
3614 * need to worry about this, and can simply block in the signal
3615 * handler until the UI thread returns an answer.
3617 * Returns: %TRUE to accept @peer_cert (which will also
3618 * immediately end the signal emission). %FALSE to allow the signal
3619 * emission to continue, which will cause the handshake to fail if
3620 * no one else overrides it.
3626 * GTlsConnection:base-io-stream:
3628 * The #GIOStream that the connection wraps. The connection holds a reference
3629 * to this stream, and may run operations on the stream from other threads
3630 * throughout its lifetime. Consequently, after the #GIOStream has been
3631 * constructed, application code may only run its own operations on this
3632 * stream when no #GIOStream operations are running.
3639 * GTlsConnection:certificate:
3641 * The connection's certificate; see
3642 * g_tls_connection_set_certificate().
3649 * GTlsConnection:database:
3651 * The certificate database to use when verifying this TLS connection.
3652 * If no certificate database is set, then the default database will be
3653 * used. See g_tls_backend_get_default_database().
3660 * GTlsConnection:interaction:
3662 * A #GTlsInteraction object to be used when the connection or certificate
3663 * database need to interact with the user. This will be used to prompt the
3664 * user for passwords where necessary.
3671 * GTlsConnection:peer-certificate:
3673 * The connection's peer's certificate, after the TLS handshake has
3674 * completed and the certificate has been accepted. Note in
3675 * particular that this is not yet set during the emission of
3676 * #GTlsConnection::accept-certificate.
3678 * (You can watch for a #GObject::notify signal on this property to
3679 * detect when a handshake has occurred.)
3686 * GTlsConnection:peer-certificate-errors:
3688 * The errors noticed-and-ignored while verifying
3689 * #GTlsConnection:peer-certificate. Normally this should be 0, but
3690 * it may not be if #GTlsClientConnection:validation-flags is not
3691 * %G_TLS_CERTIFICATE_VALIDATE_ALL, or if
3692 * #GTlsConnection::accept-certificate overrode the default
3700 * GTlsConnection:rehandshake-mode:
3702 * The rehandshaking mode. See
3703 * g_tls_connection_set_rehandshake_mode().
3710 * GTlsConnection:require-close-notify:
3712 * Whether or not proper TLS close notification is required.
3713 * See g_tls_connection_set_require_close_notify().
3720 * GTlsConnection:use-system-certdb:
3722 * Whether or not the system certificate database will be used to
3723 * verify peer certificates. See
3724 * g_tls_connection_set_use_system_certdb().
3726 * Deprecated: 2.30: Use GTlsConnection:database instead
3733 * Abstract base class for the backend-specific database types.
3740 * GTlsDatabaseClass:
3741 * @verify_chain: Virtual method implementing
3742 * g_tls_database_verify_chain().
3743 * @verify_chain_async: Virtual method implementing
3744 * g_tls_database_verify_chain_async().
3745 * @verify_chain_finish: Virtual method implementing
3746 * g_tls_database_verify_chain_finish().
3747 * @create_certificate_handle: Virtual method implementing
3748 * g_tls_database_create_certificate_handle().
3749 * @lookup_certificate_for_handle: Virtual method implementing
3750 * g_tls_database_lookup_certificate_for_handle().
3751 * @lookup_certificate_for_handle_async: Virtual method implementing
3752 * g_tls_database_lookup_certificate_for_handle_async().
3753 * @lookup_certificate_for_handle_finish: Virtual method implementing
3754 * g_tls_database_lookup_certificate_for_handle_finish().
3755 * @lookup_certificate_issuer: Virtual method implementing
3756 * g_tls_database_lookup_certificate_issuer().
3757 * @lookup_certificate_issuer_async: Virtual method implementing
3758 * g_tls_database_lookup_certificate_issuer_async().
3759 * @lookup_certificate_issuer_finish: Virtual method implementing
3760 * g_tls_database_lookup_certificate_issuer_finish().
3761 * @lookup_certificates_issued_by: Virtual method implementing
3762 * g_tls_database_lookup_certificates_issued_by().
3763 * @lookup_certificates_issued_by_async: Virtual method implementing
3764 * g_tls_database_lookup_certificates_issued_by_async().
3765 * @lookup_certificates_issued_by_finish: Virtual method implementing
3766 * g_tls_database_lookup_certificates_issued_by_finish().
3768 * The class for #GTlsDatabase. Derived classes should implement the various
3769 * virtual methods. _async and _finish methods have a default
3770 * implementation that runs the corresponding sync method in a thread.
3779 * Implemented by a #GTlsDatabase which allows you to load certificates
3787 * GTlsFileDatabase:anchors:
3789 * The path to a file containing PEM encoded certificate authority
3790 * root anchors. The certificates in this file will be treated as
3791 * root authorities for the purpose of verifying other certificates
3792 * via the g_tls_database_verify_chain() operation.
3801 * An object representing interaction that the TLS connection and database
3802 * might have with the user.
3809 * GTlsInteractionClass:
3810 * @ask_password: ask for a password synchronously. If the implementation
3811 * returns %G_TLS_INTERACTION_HANDLED, then the password argument should
3812 * have been filled in by using g_tls_password_set_value() or a similar
3814 * @ask_password_async: ask for a password asynchronously.
3815 * @ask_password_finish: complete operation to ask for a password asynchronously.
3816 * If the implementation returns %G_TLS_INTERACTION_HANDLED, then the
3817 * password argument of the async method should have been filled in by using
3818 * g_tls_password_set_value() or a similar function.
3819 * @request_certificate: ask for a certificate synchronously. If the
3820 * implementation returns %G_TLS_INTERACTION_HANDLED, then the connection
3821 * argument should have been filled in by using
3822 * g_tls_connection_set_certificate().
3823 * @request_certificate_async: ask for a certificate asyncronously.
3824 * @request_certificate_finish: complete operation to ask for a certificate
3825 * asynchronously. If the implementation returns %G_TLS_INTERACTION_HANDLED,
3826 * then the connection argument of the async method should have been
3827 * filled in by using g_tls_connection_set_certificate().
3829 * The class for #GTlsInteraction. Derived classes implement the various
3830 * virtual interaction methods to handle TLS interactions.
3832 * Derived classes can choose to implement whichever interactions methods they'd
3833 * like to support by overriding those virtual methods in their class
3834 * initialization function. If a derived class implements an async method,
3835 * it must also implement the corresponding finish method.
3837 * The synchronous interaction methods should implement to display modal dialogs,
3838 * and the asynchronous methods to display modeless dialogs.
3840 * If the user cancels an interaction, then the result should be
3841 * %G_TLS_INTERACTION_FAILED and the error should be set with a domain of
3842 * %G_IO_ERROR and code of %G_IO_ERROR_CANCELLED.
3851 * An abstract interface representing a password used in TLS. Often used in
3852 * user interaction such as unlocking a key storage token.
3859 * GTlsServerConnection:authentication-mode:
3861 * The #GTlsAuthenticationMode for the server. This can be changed
3862 * before calling g_tls_connection_handshake() if you want to
3863 * rehandshake with a different mode from the initial handshake.
3872 * #GUnixConnection is an opaque data structure and can only be accessed
3873 * using the following functions.
3878 * GUnixCredentialsMessage:credentials:
3880 * The credentials stored in the message.
3889 * #GUnixFDList is an opaque data structure and can only be accessed
3890 * using the following functions.
3897 * #GUnixFDMessage is an opaque data structure and can only be accessed
3898 * using the following functions.
3903 * GUnixInputStream:close-fd:
3905 * Whether to close the file descriptor when the stream is closed.
3912 * GUnixInputStream:fd:
3914 * The file descriptor that the stream reads from.
3921 * GUnixMountMonitor::mountpoints-changed:
3922 * @monitor: the object on which the signal is emitted
3924 * Emitted when the unix mount points have changed.
3929 * GUnixMountMonitor::mounts-changed:
3930 * @monitor: the object on which the signal is emitted
3932 * Emitted when the unix mounts have changed.
3938 * @G_UNIX_MOUNT_TYPE_UNKNOWN: Unknown UNIX mount type.
3939 * @G_UNIX_MOUNT_TYPE_FLOPPY: Floppy disk UNIX mount type.
3940 * @G_UNIX_MOUNT_TYPE_CDROM: CDROM UNIX mount type.
3941 * @G_UNIX_MOUNT_TYPE_NFS: Network File System (NFS) UNIX mount type.
3942 * @G_UNIX_MOUNT_TYPE_ZIP: ZIP UNIX mount type.
3943 * @G_UNIX_MOUNT_TYPE_JAZ: JAZZ UNIX mount type.
3944 * @G_UNIX_MOUNT_TYPE_MEMSTICK: Memory Stick UNIX mount type.
3945 * @G_UNIX_MOUNT_TYPE_CF: Compact Flash UNIX mount type.
3946 * @G_UNIX_MOUNT_TYPE_SM: Smart Media UNIX mount type.
3947 * @G_UNIX_MOUNT_TYPE_SDMMC: SD/MMC UNIX mount type.
3948 * @G_UNIX_MOUNT_TYPE_IPOD: iPod UNIX mount type.
3949 * @G_UNIX_MOUNT_TYPE_CAMERA: Digital camera UNIX mount type.
3950 * @G_UNIX_MOUNT_TYPE_HD: Hard drive UNIX mount type.
3952 * Types of UNIX mounts.
3957 * GUnixOutputStream:close-fd:
3959 * Whether to close the file descriptor when the stream is closed.
3966 * GUnixOutputStream:fd:
3968 * The file descriptor that the stream writes to.
3975 * GUnixSocketAddress:
3977 * A UNIX-domain (local) socket address, corresponding to a
3978 * struct sockaddr_un.
3983 * GUnixSocketAddress:abstract:
3985 * Whether or not this is an abstract address
3987 * Deprecated: Use #GUnixSocketAddress:address-type, which
3988 * distinguishes between zero-padded and non-zero-padded
3989 * abstract addresses.
3996 * Emitted when the volume has been changed.
4003 * This signal is emitted when the #GVolume have been removed. If
4004 * the recipient is holding references to the object they should
4005 * release them so the object can be finalized.
4010 * GVolumeMonitor::drive-changed:
4011 * @volume_monitor: The volume monitor emitting the signal.
4012 * @drive: the drive that changed
4014 * Emitted when a drive changes.
4019 * GVolumeMonitor::drive-connected:
4020 * @volume_monitor: The volume monitor emitting the signal.
4021 * @drive: a #GDrive that was connected.
4023 * Emitted when a drive is connected to the system.
4028 * GVolumeMonitor::drive-disconnected:
4029 * @volume_monitor: The volume monitor emitting the signal.
4030 * @drive: a #GDrive that was disconnected.
4032 * Emitted when a drive is disconnected from the system.
4037 * GVolumeMonitor::drive-eject-button:
4038 * @volume_monitor: The volume monitor emitting the signal.
4039 * @drive: the drive where the eject button was pressed
4041 * Emitted when the eject button is pressed on @drive.
4048 * GVolumeMonitor::drive-stop-button:
4049 * @volume_monitor: The volume monitor emitting the signal.
4050 * @drive: the drive where the stop button was pressed
4052 * Emitted when the stop button is pressed on @drive.
4059 * GVolumeMonitor::mount-added:
4060 * @volume_monitor: The volume monitor emitting the signal.
4061 * @mount: a #GMount that was added.
4063 * Emitted when a mount is added.
4068 * GVolumeMonitor::mount-changed:
4069 * @volume_monitor: The volume monitor emitting the signal.
4070 * @mount: a #GMount that changed.
4072 * Emitted when a mount changes.
4077 * GVolumeMonitor::mount-pre-unmount:
4078 * @volume_monitor: The volume monitor emitting the signal.
4079 * @mount: a #GMount that is being unmounted.
4081 * Emitted when a mount is about to be removed.
4086 * GVolumeMonitor::mount-removed:
4087 * @volume_monitor: The volume monitor emitting the signal.
4088 * @mount: a #GMount that was removed.
4090 * Emitted when a mount is removed.
4095 * GVolumeMonitor::volume-added:
4096 * @volume_monitor: The volume monitor emitting the signal.
4097 * @volume: a #GVolume that was added.
4099 * Emitted when a mountable volume is added to the system.
4104 * GVolumeMonitor::volume-changed:
4105 * @volume_monitor: The volume monitor emitting the signal.
4106 * @volume: a #GVolume that changed.
4108 * Emitted when mountable volume is changed.
4113 * GVolumeMonitor::volume-removed:
4114 * @volume_monitor: The volume monitor emitting the signal.
4115 * @volume: a #GVolume that was removed.
4117 * Emitted when a mountable volume is removed from the system.
4122 * GWin32InputStream:close-handle:
4124 * Whether to close the file handle when the stream is closed.
4131 * GWin32InputStream:handle:
4133 * The handle that the stream reads from.
4140 * GWin32OutputStream:close-handle:
4142 * Whether to close the file handle when the stream is closed.
4149 * GWin32OutputStream:handle:
4151 * The file handle that the stream writes to.
4158 * GWin32RegistryKey:path:
4160 * A path to the key in the registry, in UTF-8.
4167 * GWin32RegistryKey:path-utf16:
4169 * A path to the key in the registry, in UTF-16.
4178 * Abstract interface type for the D-Bus interface <link linkend="gdbus-interface-org-freedesktop-portal-Documents.top_of_page">org.freedesktop.portal.Documents</link>.
4183 * GXdpDocuments::handle-add:
4184 * @object: A #GXdpDocuments.
4185 * @invocation: A #GDBusMethodInvocation.
4186 * @fd_list: (allow-none): A #GUnixFDList or %NULL.
4187 * @arg_o_path_fd: Argument passed by remote caller.
4188 * @arg_reuse_existing: Argument passed by remote caller.
4189 * @arg_persistent: Argument passed by remote caller.
4191 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-portal-Documents.Add">Add()</link> D-Bus method.
4193 * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call gxdp_documents_complete_add() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
4195 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
4200 * GXdpDocuments::handle-add-named:
4201 * @object: A #GXdpDocuments.
4202 * @invocation: A #GDBusMethodInvocation.
4203 * @fd_list: (allow-none): A #GUnixFDList or %NULL.
4204 * @arg_o_path_parent_fd: Argument passed by remote caller.
4205 * @arg_filename: Argument passed by remote caller.
4206 * @arg_reuse_existing: Argument passed by remote caller.
4207 * @arg_persistent: Argument passed by remote caller.
4209 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-portal-Documents.AddNamed">AddNamed()</link> D-Bus method.
4211 * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call gxdp_documents_complete_add_named() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
4213 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
4218 * GXdpDocuments::handle-delete:
4219 * @object: A #GXdpDocuments.
4220 * @invocation: A #GDBusMethodInvocation.
4221 * @arg_doc_id: Argument passed by remote caller.
4223 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-portal-Documents.Delete">Delete()</link> D-Bus method.
4225 * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call gxdp_documents_complete_delete() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
4227 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
4232 * GXdpDocuments::handle-get-mount-point:
4233 * @object: A #GXdpDocuments.
4234 * @invocation: A #GDBusMethodInvocation.
4236 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-portal-Documents.GetMountPoint">GetMountPoint()</link> D-Bus method.
4238 * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call gxdp_documents_complete_get_mount_point() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
4240 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
4245 * GXdpDocuments::handle-grant-permissions:
4246 * @object: A #GXdpDocuments.
4247 * @invocation: A #GDBusMethodInvocation.
4248 * @arg_doc_id: Argument passed by remote caller.
4249 * @arg_app_id: Argument passed by remote caller.
4250 * @arg_permissions: Argument passed by remote caller.
4252 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-portal-Documents.GrantPermissions">GrantPermissions()</link> D-Bus method.
4254 * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call gxdp_documents_complete_grant_permissions() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
4256 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
4261 * GXdpDocuments::handle-info:
4262 * @object: A #GXdpDocuments.
4263 * @invocation: A #GDBusMethodInvocation.
4264 * @arg_doc_id: Argument passed by remote caller.
4266 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-portal-Documents.Info">Info()</link> D-Bus method.
4268 * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call gxdp_documents_complete_info() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
4270 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
4275 * GXdpDocuments::handle-list:
4276 * @object: A #GXdpDocuments.
4277 * @invocation: A #GDBusMethodInvocation.
4278 * @arg_app_id: Argument passed by remote caller.
4280 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-portal-Documents.List">List()</link> D-Bus method.
4282 * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call gxdp_documents_complete_list() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
4284 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
4289 * GXdpDocuments::handle-lookup:
4290 * @object: A #GXdpDocuments.
4291 * @invocation: A #GDBusMethodInvocation.
4292 * @arg_filename: Argument passed by remote caller.
4294 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-portal-Documents.Lookup">Lookup()</link> D-Bus method.
4296 * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call gxdp_documents_complete_lookup() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
4298 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
4303 * GXdpDocuments::handle-revoke-permissions:
4304 * @object: A #GXdpDocuments.
4305 * @invocation: A #GDBusMethodInvocation.
4306 * @arg_doc_id: Argument passed by remote caller.
4307 * @arg_app_id: Argument passed by remote caller.
4308 * @arg_permissions: Argument passed by remote caller.
4310 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-portal-Documents.RevokePermissions">RevokePermissions()</link> D-Bus method.
4312 * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call gxdp_documents_complete_revoke_permissions() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
4314 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
4319 * GXdpDocumentsIface:
4320 * @parent_iface: The parent interface.
4321 * @handle_add: Handler for the #GXdpDocuments::handle-add signal.
4322 * @handle_add_named: Handler for the #GXdpDocuments::handle-add-named signal.
4323 * @handle_delete: Handler for the #GXdpDocuments::handle-delete signal.
4324 * @handle_get_mount_point: Handler for the #GXdpDocuments::handle-get-mount-point signal.
4325 * @handle_grant_permissions: Handler for the #GXdpDocuments::handle-grant-permissions signal.
4326 * @handle_info: Handler for the #GXdpDocuments::handle-info signal.
4327 * @handle_list: Handler for the #GXdpDocuments::handle-list signal.
4328 * @handle_lookup: Handler for the #GXdpDocuments::handle-lookup signal.
4329 * @handle_revoke_permissions: Handler for the #GXdpDocuments::handle-revoke-permissions signal.
4331 * Virtual table for the D-Bus interface <link linkend="gdbus-interface-org-freedesktop-portal-Documents.top_of_page">org.freedesktop.portal.Documents</link>.
4336 * GXdpDocumentsProxy:
4338 * The #GXdpDocumentsProxy structure contains only private data and should only be accessed using the provided API.
4343 * GXdpDocumentsProxyClass:
4344 * @parent_class: The parent class.
4346 * Class structure for #GXdpDocumentsProxy.
4351 * GXdpDocumentsSkeleton:
4353 * The #GXdpDocumentsSkeleton structure contains only private data and should only be accessed using the provided API.
4358 * GXdpDocumentsSkeletonClass:
4359 * @parent_class: The parent class.
4361 * Class structure for #GXdpDocumentsSkeleton.
4366 * GXdpNetworkMonitor:
4368 * Abstract interface type for the D-Bus interface <link linkend="gdbus-interface-org-freedesktop-portal-NetworkMonitor.top_of_page">org.freedesktop.portal.NetworkMonitor</link>.
4373 * GXdpNetworkMonitor::changed:
4374 * @object: A #GXdpNetworkMonitor.
4375 * @arg_available: Argument.
4377 * On the client-side, this signal is emitted whenever the D-Bus signal <link linkend="gdbus-signal-org-freedesktop-portal-NetworkMonitor.changed">"changed"</link> is received.
4379 * On the service-side, this signal can be used with e.g. g_signal_emit_by_name() to make the object emit the D-Bus signal.
4384 * GXdpNetworkMonitor:available:
4386 * Represents the D-Bus property <link linkend="gdbus-property-org-freedesktop-portal-NetworkMonitor.available">"available"</link>.
4388 * Since the D-Bus property for this #GObject property is readable but not writable, it is meaningful to read from it on both the client- and service-side. It is only meaningful, however, to write to it on the service-side.
4393 * GXdpNetworkMonitor:connectivity:
4395 * Represents the D-Bus property <link linkend="gdbus-property-org-freedesktop-portal-NetworkMonitor.connectivity">"connectivity"</link>.
4397 * Since the D-Bus property for this #GObject property is readable but not writable, it is meaningful to read from it on both the client- and service-side. It is only meaningful, however, to write to it on the service-side.
4402 * GXdpNetworkMonitor:metered:
4404 * Represents the D-Bus property <link linkend="gdbus-property-org-freedesktop-portal-NetworkMonitor.metered">"metered"</link>.
4406 * Since the D-Bus property for this #GObject property is readable but not writable, it is meaningful to read from it on both the client- and service-side. It is only meaningful, however, to write to it on the service-side.
4411 * GXdpNetworkMonitorIface:
4412 * @parent_iface: The parent interface.
4413 * @get_available: Getter for the #GXdpNetworkMonitor:available property.
4414 * @get_connectivity: Getter for the #GXdpNetworkMonitor:connectivity property.
4415 * @get_metered: Getter for the #GXdpNetworkMonitor:metered property.
4416 * @changed: Handler for the #GXdpNetworkMonitor::changed signal.
4418 * Virtual table for the D-Bus interface <link linkend="gdbus-interface-org-freedesktop-portal-NetworkMonitor.top_of_page">org.freedesktop.portal.NetworkMonitor</link>.
4423 * GXdpNetworkMonitorProxy:
4425 * The #GXdpNetworkMonitorProxy structure contains only private data and should only be accessed using the provided API.
4430 * GXdpNetworkMonitorProxyClass:
4431 * @parent_class: The parent class.
4433 * Class structure for #GXdpNetworkMonitorProxy.
4438 * GXdpNetworkMonitorSkeleton:
4440 * The #GXdpNetworkMonitorSkeleton structure contains only private data and should only be accessed using the provided API.
4445 * GXdpNetworkMonitorSkeletonClass:
4446 * @parent_class: The parent class.
4448 * Class structure for #GXdpNetworkMonitorSkeleton.
4453 * GXdpProxyResolver:
4455 * Abstract interface type for the D-Bus interface <link linkend="gdbus-interface-org-freedesktop-portal-ProxyResolver.top_of_page">org.freedesktop.portal.ProxyResolver</link>.
4460 * GXdpProxyResolver::handle-lookup:
4461 * @object: A #GXdpProxyResolver.
4462 * @invocation: A #GDBusMethodInvocation.
4463 * @arg_uri: Argument passed by remote caller.
4465 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-portal-ProxyResolver.Lookup">Lookup()</link> D-Bus method.
4467 * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call gxdp_proxy_resolver_complete_lookup() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
4469 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
4474 * GXdpProxyResolverIface:
4475 * @parent_iface: The parent interface.
4476 * @handle_lookup: Handler for the #GXdpProxyResolver::handle-lookup signal.
4478 * Virtual table for the D-Bus interface <link linkend="gdbus-interface-org-freedesktop-portal-ProxyResolver.top_of_page">org.freedesktop.portal.ProxyResolver</link>.
4483 * GXdpProxyResolverProxy:
4485 * The #GXdpProxyResolverProxy structure contains only private data and should only be accessed using the provided API.
4490 * GXdpProxyResolverProxyClass:
4491 * @parent_class: The parent class.
4493 * Class structure for #GXdpProxyResolverProxy.
4498 * GXdpProxyResolverSkeleton:
4500 * The #GXdpProxyResolverSkeleton structure contains only private data and should only be accessed using the provided API.
4505 * GXdpProxyResolverSkeletonClass:
4506 * @parent_class: The parent class.
4508 * Class structure for #GXdpProxyResolverSkeleton.
4515 * Zlib decompression
4520 * GZlibCompressor:file-info:
4522 * If set to a non-%NULL #GFileInfo object, and #GZlibCompressor:format is
4523 * %G_ZLIB_COMPRESSOR_FORMAT_GZIP, the compressor will write the file name
4524 * and modification time from the file info to the GZIP header.
4531 * GZlibDecompressor:
4533 * Zlib decompression
4538 * GZlibDecompressor:file-info:
4540 * A #GFileInfo containing the information found in the GZIP header
4541 * of the data stream processed, or %NULL if the header was not yet
4542 * fully processed, is not present at all, or the compressor's
4543 * #GZlibDecompressor:format property is not %G_ZLIB_COMPRESSOR_FORMAT_GZIP.
4550 * G_TLS_DATABASE_PURPOSE_AUTHENTICATE_CLIENT:
4552 * The purpose used to verify the client certificate in a TLS connection.
4553 * Used by TLS servers.
4558 * G_TLS_DATABASE_PURPOSE_AUTHENTICATE_SERVER:
4560 * The purpose used to verify the server certificate in a TLS connection. This
4561 * is the most common purpose in use. Used by TLS clients.
4566 * G_TYPE_SETTINGS_SCHEMA:
4568 * A boxed #GType corresponding to #GSettingsSchema.
4575 * G_TYPE_SETTINGS_SCHEMA_SOURCE:
4577 * A boxed #GType corresponding to #GSettingsSchemaSource.
4584 * SECTION:GXdpDocuments
4585 * @title: GXdpDocuments
4586 * @short_description: Generated C code for the org.freedesktop.portal.Documents D-Bus interface
4588 * This section contains code for working with the <link linkend="gdbus-interface-org-freedesktop-portal-Documents.top_of_page">org.freedesktop.portal.Documents</link> D-Bus interface in C.
4593 * SECTION:GXdpNetworkMonitor
4594 * @title: GXdpNetworkMonitor
4595 * @short_description: Generated C code for the org.freedesktop.portal.NetworkMonitor D-Bus interface
4597 * This section contains code for working with the <link linkend="gdbus-interface-org-freedesktop-portal-NetworkMonitor.top_of_page">org.freedesktop.portal.NetworkMonitor</link> D-Bus interface in C.
4602 * SECTION:GXdpProxyResolver
4603 * @title: GXdpProxyResolver
4604 * @short_description: Generated C code for the org.freedesktop.portal.ProxyResolver D-Bus interface
4606 * This section contains code for working with the <link linkend="gdbus-interface-org-freedesktop-portal-ProxyResolver.top_of_page">org.freedesktop.portal.ProxyResolver</link> D-Bus interface in C.
4611 * SECTION:_GFreedesktopDBus
4612 * @title: _GFreedesktopDBus
4613 * @short_description: Generated C code for the org.freedesktop.DBus D-Bus interface
4615 * This section contains code for working with the <link linkend="gdbus-interface-org-freedesktop-DBus.top_of_page">org.freedesktop.DBus</link> D-Bus interface in C.
4620 * SECTION:extensionpoints
4621 * @short_description: Extension Points
4623 * @see_also: [Extending GIO][extending-gio]
4625 * #GIOExtensionPoint provides a mechanism for modules to extend the
4626 * functionality of the library or application that loaded it in an
4627 * organized fashion.
4629 * An extension point is identified by a name, and it may optionally
4630 * require that any implementation must be of a certain type (or derived
4631 * thereof). Use g_io_extension_point_register() to register an
4632 * extension point, and g_io_extension_point_set_required_type() to
4633 * set a required type.
4635 * A module can implement an extension point by specifying the #GType
4636 * that implements the functionality. Additionally, each implementation
4637 * of an extension point has a name, and a priority. Use
4638 * g_io_extension_point_implement() to implement an extension point.
4640 * |[<!-- language="C" -->
4641 * GIOExtensionPoint *ep;
4643 * // Register an extension point
4644 * ep = g_io_extension_point_register ("my-extension-point");
4645 * g_io_extension_point_set_required_type (ep, MY_TYPE_EXAMPLE);
4648 * |[<!-- language="C" -->
4649 * // Implement an extension point
4650 * G_DEFINE_TYPE (MyExampleImpl, my_example_impl, MY_TYPE_EXAMPLE);
4651 * g_io_extension_point_implement ("my-extension-point",
4652 * my_example_impl_get_type (),
4657 * It is up to the code that registered the extension point how
4658 * it uses the implementations that have been associated with it.
4659 * Depending on the use case, it may use all implementations, or
4660 * only the one with the highest priority, or pick a specific
4663 * To avoid opening all modules just to find out what extension
4664 * points they implement, GIO makes use of a caching mechanism,
4665 * see [gio-querymodules][gio-querymodules].
4666 * You are expected to run this command after installing a
4669 * The `GIO_EXTRA_MODULES` environment variable can be used to
4670 * specify additional directories to automatically load modules
4671 * from. This environment variable has the same syntax as the
4672 * `PATH`. If two modules have the same base name in different
4673 * directories, then the latter one will be ignored. If additional
4674 * directories are specified GIO will load modules from the built-in
4682 * @short_description: An action interface
4683 * @include: gio/gio.h
4685 * #GAction represents a single named action.
4687 * The main interface to an action is that it can be activated with
4688 * g_action_activate(). This results in the 'activate' signal being
4689 * emitted. An activation has a #GVariant parameter (which may be
4690 * %NULL). The correct type for the parameter is determined by a static
4691 * parameter type (which is given at construction time).
4693 * An action may optionally have a state, in which case the state may be
4694 * set with g_action_change_state(). This call takes a #GVariant. The
4695 * correct type for the state is determined by a static state type
4696 * (which is given at construction time).
4698 * The state may have a hint associated with it, specifying its valid
4701 * #GAction is merely the interface to the concept of an action, as
4702 * described above. Various implementations of actions exist, including
4705 * In all cases, the implementing class is responsible for storing the
4706 * name of the action, the parameter type, the enabled state, the
4707 * optional state type and the state and emitting the appropriate
4708 * signals when these change. The implementor is responsible for filtering
4709 * calls to g_action_activate() and g_action_change_state() for type
4710 * safety and for the state being enabled.
4712 * Probably the only useful thing to do with a #GAction is to put it
4713 * inside of a #GSimpleActionGroup.
4718 * SECTION:gactiongroup
4719 * @title: GActionGroup
4720 * @short_description: A group of actions
4721 * @include: gio/gio.h
4722 * @see_also: #GAction
4724 * #GActionGroup represents a group of actions. Actions can be used to
4725 * expose functionality in a structured way, either from one part of a
4726 * program to another, or to the outside world. Action groups are often
4727 * used together with a #GMenuModel that provides additional
4728 * representation data for displaying the actions to the user, e.g. in
4731 * The main way to interact with the actions in a GActionGroup is to
4732 * activate them with g_action_group_activate_action(). Activating an
4733 * action may require a #GVariant parameter. The required type of the
4734 * parameter can be inquired with g_action_group_get_action_parameter_type().
4735 * Actions may be disabled, see g_action_group_get_action_enabled().
4736 * Activating a disabled action has no effect.
4738 * Actions may optionally have a state in the form of a #GVariant. The
4739 * current state of an action can be inquired with
4740 * g_action_group_get_action_state(). Activating a stateful action may
4741 * change its state, but it is also possible to set the state by calling
4742 * g_action_group_change_action_state().
4744 * As typical example, consider a text editing application which has an
4745 * option to change the current font to 'bold'. A good way to represent
4746 * this would be a stateful action, with a boolean state. Activating the
4747 * action would toggle the state.
4749 * Each action in the group has a unique name (which is a string). All
4750 * method calls, except g_action_group_list_actions() take the name of
4751 * an action as an argument.
4753 * The #GActionGroup API is meant to be the 'public' API to the action
4754 * group. The calls here are exactly the interaction that 'external
4755 * forces' (eg: UI, incoming D-Bus messages, etc.) are supposed to have
4756 * with actions. 'Internal' APIs (ie: ones meant only to be accessed by
4757 * the action group implementation) are found on subclasses. This is
4758 * why you will find - for example - g_action_group_get_action_enabled()
4759 * but not an equivalent set() call.
4761 * Signals are emitted on the action group in response to state changes
4762 * on individual actions.
4764 * Implementations of #GActionGroup should provide implementations for
4765 * the virtual functions g_action_group_list_actions() and
4766 * g_action_group_query_action(). The other virtual functions should
4767 * not be implemented - their "wrappers" are actually implemented with
4768 * calls to g_action_group_query_action().
4773 * SECTION:gactiongroupexporter
4774 * @title: GActionGroup exporter
4775 * @include: gio/gio.h
4776 * @short_description: Export GActionGroups on D-Bus
4777 * @see_also: #GActionGroup, #GDBusActionGroup
4779 * These functions support exporting a #GActionGroup on D-Bus.
4780 * The D-Bus interface that is used is a private implementation
4783 * To access an exported #GActionGroup remotely, use
4784 * g_dbus_action_group_get() to obtain a #GDBusActionGroup.
4789 * SECTION:gactionmap
4790 * @title: GActionMap
4791 * @include: gio/gio.h
4792 * @short_description: Interface for action containers
4794 * The GActionMap interface is implemented by #GActionGroup
4795 * implementations that operate by containing a number of
4796 * named #GAction instances, such as #GSimpleActionGroup.
4798 * One useful application of this interface is to map the
4799 * names of actions from various action groups to unique,
4800 * prefixed names (e.g. by prepending "app." or "win.").
4801 * This is the motivation for the 'Map' part of the interface
4810 * @short_description: Application information and launch contexts
4811 * @include: gio/gio.h
4812 * @see_also: #GAppInfoMonitor
4814 * #GAppInfo and #GAppLaunchContext are used for describing and launching
4815 * applications installed on the system.
4817 * As of GLib 2.20, URIs will always be converted to POSIX paths
4818 * (using g_file_get_path()) when using g_app_info_launch() even if
4819 * the application requested an URI and not a POSIX path. For example
4820 * for an desktop-file based application with Exec key `totem
4821 * %U` and a single URI, `sftp://foo/file.avi`, then
4822 * `/home/user/.gvfs/sftp on foo/file.avi` will be passed. This will
4823 * only work if a set of suitable GIO extensions (such as gvfs 2.26
4824 * compiled with FUSE support), is available and operational; if this
4825 * is not the case, the URI will be passed unmodified to the application.
4826 * Some URIs, such as `mailto:`, of course cannot be mapped to a POSIX
4827 * path (in gvfs there's no FUSE mount for it); such URIs will be
4828 * passed unmodified to the application.
4830 * Specifically for gvfs 2.26 and later, the POSIX URI will be mapped
4831 * back to the GIO URI in the #GFile constructors (since gvfs
4832 * implements the #GVfs extension point). As such, if the application
4833 * needs to examine the URI, it needs to use g_file_get_uri() or
4834 * similar on #GFile. In other words, an application cannot assume
4835 * that the URI passed to e.g. g_file_new_for_commandline_arg() is
4836 * equal to the result of g_file_get_uri(). The following snippet
4843 * file = g_file_new_for_commandline_arg (uri_from_commandline);
4845 * uri = g_file_get_uri (file);
4846 * strcmp (uri, uri_from_commandline) == 0;
4849 * if (g_file_has_uri_scheme (file, "cdda"))
4851 * // do something special with uri
4853 * g_object_unref (file);
4856 * This code will work when both `cdda://sr0/Track 1.wav` and
4857 * `/home/user/.gvfs/cdda on sr0/Track 1.wav` is passed to the
4858 * application. It should be noted that it's generally not safe
4859 * for applications to rely on the format of a particular URIs.
4860 * Different launcher applications (e.g. file managers) may have
4861 * different ideas of what a given URI means.
4866 * SECTION:gappinfomonitor
4867 * @short_description: Monitor application information for changes
4869 * #GAppInfoMonitor is a very simple object used for monitoring the app
4870 * info database for changes (ie: newly installed or removed
4873 * Call g_app_info_monitor_get() to get a #GAppInfoMonitor and connect
4874 * to the "changed" signal.
4876 * In the usual case, applications should try to make note of the change
4877 * (doing things like invalidating caches) but not act on it. In
4878 * particular, applications should avoid making calls to #GAppInfo APIs
4879 * in response to the change signal, deferring these until the time that
4880 * the data is actually required. The exception to this case is when
4881 * application information is actually being displayed on the screen
4882 * (eg: during a search or when the list of all applications is shown).
4883 * The reason for this is that changes to the list of installed
4884 * applications often come in groups (like during system updates) and
4885 * rescanning the list on every change is pointless and expensive.
4892 * SECTION:gapplication
4893 * @title: GApplication
4894 * @short_description: Core application class
4895 * @include: gio/gio.h
4897 * A #GApplication is the foundation of an application. It wraps some
4898 * low-level platform-specific services and is intended to act as the
4899 * foundation for higher-level application classes such as
4900 * #GtkApplication or #MxApplication. In general, you should not use
4901 * this class outside of a higher level framework.
4903 * GApplication provides convenient life cycle management by maintaining
4904 * a "use count" for the primary application instance. The use count can
4905 * be changed using g_application_hold() and g_application_release(). If
4906 * it drops to zero, the application exits. Higher-level classes such as
4907 * #GtkApplication employ the use count to ensure that the application
4908 * stays alive as long as it has any opened windows.
4910 * Another feature that GApplication (optionally) provides is process
4911 * uniqueness. Applications can make use of this functionality by
4912 * providing a unique application ID. If given, only one application
4913 * with this ID can be running at a time per session. The session
4914 * concept is platform-dependent, but corresponds roughly to a graphical
4915 * desktop login. When your application is launched again, its
4916 * arguments are passed through platform communication to the already
4917 * running program. The already running instance of the program is
4918 * called the "primary instance"; for non-unique applications this is
4919 * the always the current instance. On Linux, the D-Bus session bus
4920 * is used for communication.
4922 * The use of #GApplication differs from some other commonly-used
4923 * uniqueness libraries (such as libunique) in important ways. The
4924 * application is not expected to manually register itself and check
4925 * if it is the primary instance. Instead, the main() function of a
4926 * #GApplication should do very little more than instantiating the
4927 * application instance, possibly connecting signal handlers, then
4928 * calling g_application_run(). All checks for uniqueness are done
4929 * internally. If the application is the primary instance then the
4930 * startup signal is emitted and the mainloop runs. If the application
4931 * is not the primary instance then a signal is sent to the primary
4932 * instance and g_application_run() promptly returns. See the code
4935 * If used, the expected form of an application identifier is very close
4937 * [DBus bus name](http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-interface).
4938 * Examples include: "com.example.MyApp", "org.example.internal-apps.Calculator".
4939 * For details on valid application identifiers, see g_application_id_is_valid().
4941 * On Linux, the application identifier is claimed as a well-known bus name
4942 * on the user's session bus. This means that the uniqueness of your
4943 * application is scoped to the current session. It also means that your
4944 * application may provide additional services (through registration of other
4945 * object paths) at that bus name. The registration of these object paths
4946 * should be done with the shared GDBus session bus. Note that due to the
4947 * internal architecture of GDBus, method calls can be dispatched at any time
4948 * (even if a main loop is not running). For this reason, you must ensure that
4949 * any object paths that you wish to register are registered before #GApplication
4950 * attempts to acquire the bus name of your application (which happens in
4951 * g_application_register()). Unfortunately, this means that you cannot use
4952 * g_application_get_is_remote() to decide if you want to register object paths.
4954 * GApplication also implements the #GActionGroup and #GActionMap
4955 * interfaces and lets you easily export actions by adding them with
4956 * g_action_map_add_action(). When invoking an action by calling
4957 * g_action_group_activate_action() on the application, it is always
4958 * invoked in the primary instance. The actions are also exported on
4959 * the session bus, and GIO provides the #GDBusActionGroup wrapper to
4960 * conveniently access them remotely. GIO provides a #GDBusMenuModel wrapper
4961 * for remote access to exported #GMenuModels.
4963 * There is a number of different entry points into a GApplication:
4965 * - via 'Activate' (i.e. just starting the application)
4967 * - via 'Open' (i.e. opening some files)
4969 * - by handling a command-line
4971 * - via activating an action
4973 * The #GApplication::startup signal lets you handle the application
4974 * initialization for all of these in a single place.
4976 * Regardless of which of these entry points is used to start the
4977 * application, GApplication passes some "platform data from the
4978 * launching instance to the primary instance, in the form of a
4979 * #GVariant dictionary mapping strings to variants. To use platform
4980 * data, override the @before_emit or @after_emit virtual functions
4981 * in your #GApplication subclass. When dealing with
4982 * #GApplicationCommandLine objects, the platform data is
4983 * directly available via g_application_command_line_get_cwd(),
4984 * g_application_command_line_get_environ() and
4985 * g_application_command_line_get_platform_data().
4987 * As the name indicates, the platform data may vary depending on the
4988 * operating system, but it always includes the current directory (key
4989 * "cwd"), and optionally the environment (ie the set of environment
4990 * variables and their values) of the calling process (key "environ").
4991 * The environment is only added to the platform data if the
4992 * %G_APPLICATION_SEND_ENVIRONMENT flag is set. #GApplication subclasses
4993 * can add their own platform data by overriding the @add_platform_data
4994 * virtual function. For instance, #GtkApplication adds startup notification
4997 * To parse commandline arguments you may handle the
4998 * #GApplication::command-line signal or override the local_command_line()
4999 * vfunc, to parse them in either the primary instance or the local instance,
5002 * For an example of opening files with a GApplication, see
5003 * [gapplication-example-open.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-open.c).
5005 * For an example of using actions with GApplication, see
5006 * [gapplication-example-actions.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-actions.c).
5008 * For an example of using extra D-Bus hooks with GApplication, see
5009 * [gapplication-example-dbushooks.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-dbushooks.c).
5014 * SECTION:gapplicationcommandline
5015 * @title: GApplicationCommandLine
5016 * @short_description: A command-line invocation of an application
5017 * @include: gio/gio.h
5018 * @see_also: #GApplication
5020 * #GApplicationCommandLine represents a command-line invocation of
5021 * an application. It is created by #GApplication and emitted
5022 * in the #GApplication::command-line signal and virtual function.
5024 * The class contains the list of arguments that the program was invoked
5025 * with. It is also possible to query if the commandline invocation was
5026 * local (ie: the current process is running in direct response to the
5027 * invocation) or remote (ie: some other process forwarded the
5028 * commandline to this process).
5030 * The GApplicationCommandLine object can provide the @argc and @argv
5031 * parameters for use with the #GOptionContext command-line parsing API,
5032 * with the g_application_command_line_get_arguments() function. See
5033 * [gapplication-example-cmdline3.c][gapplication-example-cmdline3]
5036 * The exit status of the originally-invoked process may be set and
5037 * messages can be printed to stdout or stderr of that process. The
5038 * lifecycle of the originally-invoked process is tied to the lifecycle
5039 * of this object (ie: the process exits when the last reference is
5042 * The main use for #GApplicationCommandLine (and the
5043 * #GApplication::command-line signal) is 'Emacs server' like use cases:
5044 * You can set the `EDITOR` environment variable to have e.g. git use
5045 * your favourite editor to edit commit messages, and if you already
5046 * have an instance of the editor running, the editing will happen
5047 * in the running instance, instead of opening a new one. An important
5048 * aspect of this use case is that the process that gets started by git
5049 * does not return until the editing is done.
5051 * Normally, the commandline is completely handled in the
5052 * #GApplication::command-line handler. The launching instance exits
5053 * once the signal handler in the primary instance has returned, and
5054 * the return value of the signal handler becomes the exit status
5055 * of the launching instance.
5056 * |[<!-- language="C" -->
5058 * command_line (GApplication *application,
5059 * GApplicationCommandLine *cmdline)
5065 * argv = g_application_command_line_get_arguments (cmdline, &argc);
5067 * g_application_command_line_print (cmdline,
5068 * "This text is written back\n"
5069 * "to stdout of the caller\n");
5071 * for (i = 0; i < argc; i++)
5072 * g_print ("argument %d: %s\n", i, argv[i]);
5074 * g_strfreev (argv);
5079 * The complete example can be found here:
5080 * [gapplication-example-cmdline.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-cmdline.c)
5082 * In more complicated cases, the handling of the comandline can be
5083 * split between the launcher and the primary instance.
5084 * |[<!-- language="C" -->
5086 * test_local_cmdline (GApplication *application,
5087 * gchar ***arguments,
5088 * gint *exit_status)
5093 * argv = *arguments;
5098 * if (g_str_has_prefix (argv[i], "--local-"))
5100 * g_print ("handling argument %s locally\n", argv[i]);
5102 * for (j = i; argv[j]; j++)
5103 * argv[j] = argv[j + 1];
5107 * g_print ("not handling argument %s locally\n", argv[i]);
5118 * test_application_class_init (TestApplicationClass *class)
5120 * G_APPLICATION_CLASS (class)->local_command_line = test_local_cmdline;
5125 * In this example of split commandline handling, options that start
5126 * with `--local-` are handled locally, all other options are passed
5127 * to the #GApplication::command-line handler which runs in the primary
5130 * The complete example can be found here:
5131 * [gapplication-example-cmdline2.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-cmdline2.c)
5133 * If handling the commandline requires a lot of work, it may
5134 * be better to defer it.
5135 * |[<!-- language="C" -->
5137 * my_cmdline_handler (gpointer data)
5139 * GApplicationCommandLine *cmdline = data;
5141 * // do the heavy lifting in an idle
5143 * g_application_command_line_set_exit_status (cmdline, 0);
5144 * g_object_unref (cmdline); // this releases the application
5146 * return G_SOURCE_REMOVE;
5150 * command_line (GApplication *application,
5151 * GApplicationCommandLine *cmdline)
5153 * // keep the application running until we are done with this commandline
5154 * g_application_hold (application);
5156 * g_object_set_data_full (G_OBJECT (cmdline),
5157 * "application", application,
5158 * (GDestroyNotify)g_application_release);
5160 * g_object_ref (cmdline);
5161 * g_idle_add (my_cmdline_handler, cmdline);
5166 * In this example the commandline is not completely handled before
5167 * the #GApplication::command-line handler returns. Instead, we keep
5168 * a reference to the #GApplicationCommandLine object and handle it
5169 * later (in this example, in an idle). Note that it is necessary to
5170 * hold the application until you are done with the commandline.
5172 * The complete example can be found here:
5173 * [gapplication-example-cmdline3.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-cmdline3.c)
5178 * SECTION:gasyncinitable
5179 * @short_description: Asynchronously failable object initialization interface
5180 * @include: gio/gio.h
5181 * @see_also: #GInitable
5183 * This is the asynchronous version of #GInitable; it behaves the same
5184 * in all ways except that initialization is asynchronous. For more details
5185 * see the descriptions on #GInitable.
5187 * A class may implement both the #GInitable and #GAsyncInitable interfaces.
5189 * Users of objects implementing this are not intended to use the interface
5190 * method directly; instead it will be used automatically in various ways.
5191 * For C applications you generally just call g_async_initable_new_async()
5192 * directly, or indirectly via a foo_thing_new_async() wrapper. This will call
5193 * g_async_initable_init_async() under the cover, calling back with %NULL and
5194 * a set %GError on failure.
5196 * A typical implementation might look something like this:
5198 * |[<!-- language="C" -->
5206 * _foo_ready_cb (Foo *self)
5210 * self->priv->state = INITIALIZED;
5212 * for (l = self->priv->init_results; l != NULL; l = l->next)
5214 * GTask *task = l->data;
5216 * if (self->priv->success)
5217 * g_task_return_boolean (task, TRUE);
5219 * g_task_return_new_error (task, ...);
5220 * g_object_unref (task);
5223 * g_list_free (self->priv->init_results);
5224 * self->priv->init_results = NULL;
5228 * foo_init_async (GAsyncInitable *initable,
5230 * GCancellable *cancellable,
5231 * GAsyncReadyCallback callback,
5232 * gpointer user_data)
5234 * Foo *self = FOO (initable);
5237 * task = g_task_new (initable, cancellable, callback, user_data);
5239 * switch (self->priv->state)
5241 * case NOT_INITIALIZED:
5242 * _foo_get_ready (self);
5243 * self->priv->init_results = g_list_append (self->priv->init_results,
5245 * self->priv->state = INITIALIZING;
5247 * case INITIALIZING:
5248 * self->priv->init_results = g_list_append (self->priv->init_results,
5252 * if (!self->priv->success)
5253 * g_task_return_new_error (task, ...);
5255 * g_task_return_boolean (task, TRUE);
5256 * g_object_unref (task);
5262 * foo_init_finish (GAsyncInitable *initable,
5263 * GAsyncResult *result,
5266 * g_return_val_if_fail (g_task_is_valid (result, initable), FALSE);
5268 * return g_task_propagate_boolean (G_TASK (result), error);
5272 * foo_async_initable_iface_init (gpointer g_iface,
5275 * GAsyncInitableIface *iface = g_iface;
5277 * iface->init_async = foo_init_async;
5278 * iface->init_finish = foo_init_finish;
5285 * SECTION:gasyncresult
5286 * @short_description: Asynchronous Function Results
5287 * @include: gio/gio.h
5290 * Provides a base class for implementing asynchronous function results.
5292 * Asynchronous operations are broken up into two separate operations
5293 * which are chained together by a #GAsyncReadyCallback. To begin
5294 * an asynchronous operation, provide a #GAsyncReadyCallback to the
5295 * asynchronous function. This callback will be triggered when the
5296 * operation has completed, and will be passed a #GAsyncResult instance
5297 * filled with the details of the operation's success or failure, the
5298 * object the asynchronous function was started for and any error codes
5299 * returned. The asynchronous callback function is then expected to call
5300 * the corresponding "_finish()" function, passing the object the
5301 * function was called for, the #GAsyncResult instance, and (optionally)
5302 * an @error to grab any error conditions that may have occurred.
5304 * The "_finish()" function for an operation takes the generic result
5305 * (of type #GAsyncResult) and returns the specific result that the
5306 * operation in question yields (e.g. a #GFileEnumerator for a
5307 * "enumerate children" operation). If the result or error status of the
5308 * operation is not needed, there is no need to call the "_finish()"
5309 * function; GIO will take care of cleaning up the result and error
5310 * information after the #GAsyncReadyCallback returns. You can pass
5311 * %NULL for the #GAsyncReadyCallback if you don't need to take any
5312 * action at all after the operation completes. Applications may also
5313 * take a reference to the #GAsyncResult and call "_finish()" later;
5314 * however, the "_finish()" function may be called at most once.
5316 * Example of a typical asynchronous operation flow:
5317 * |[<!-- language="C" -->
5318 * void _theoretical_frobnitz_async (Theoretical *t,
5320 * GAsyncReadyCallback cb,
5323 * gboolean _theoretical_frobnitz_finish (Theoretical *t,
5324 * GAsyncResult *res,
5328 * frobnitz_result_func (GObject *source_object,
5329 * GAsyncResult *res,
5330 * gpointer user_data)
5332 * gboolean success = FALSE;
5334 * success = _theoretical_frobnitz_finish (source_object, res, NULL);
5337 * g_printf ("Hurray!\n");
5339 * g_printf ("Uh oh!\n");
5345 * int main (int argc, void *argv[])
5349 * _theoretical_frobnitz_async (theoretical_data,
5351 * frobnitz_result_func,
5358 * The callback for an asynchronous operation is called only once, and is
5359 * always called, even in the case of a cancelled operation. On cancellation
5360 * the result is a %G_IO_ERROR_CANCELLED error.
5362 * ## I/O Priority # {#io-priority}
5364 * Many I/O-related asynchronous operations have a priority parameter,
5365 * which is used in certain cases to determine the order in which
5366 * operations are executed. They are not used to determine system-wide
5367 * I/O scheduling. Priorities are integers, with lower numbers indicating
5368 * higher priority. It is recommended to choose priorities between
5369 * %G_PRIORITY_LOW and %G_PRIORITY_HIGH, with %G_PRIORITY_DEFAULT
5375 * SECTION:gbufferedinputstream
5376 * @short_description: Buffered Input Stream
5377 * @include: gio/gio.h
5378 * @see_also: #GFilterInputStream, #GInputStream
5380 * Buffered input stream implements #GFilterInputStream and provides
5381 * for buffered reads.
5383 * By default, #GBufferedInputStream's buffer size is set at 4 kilobytes.
5385 * To create a buffered input stream, use g_buffered_input_stream_new(),
5386 * or g_buffered_input_stream_new_sized() to specify the buffer's size at
5389 * To get the size of a buffer within a buffered input stream, use
5390 * g_buffered_input_stream_get_buffer_size(). To change the size of a
5391 * buffered input stream's buffer, use
5392 * g_buffered_input_stream_set_buffer_size(). Note that the buffer's size
5393 * cannot be reduced below the size of the data within the buffer.
5398 * SECTION:gbufferedoutputstream
5399 * @short_description: Buffered Output Stream
5400 * @include: gio/gio.h
5401 * @see_also: #GFilterOutputStream, #GOutputStream
5403 * Buffered output stream implements #GFilterOutputStream and provides
5404 * for buffered writes.
5406 * By default, #GBufferedOutputStream's buffer size is set at 4 kilobytes.
5408 * To create a buffered output stream, use g_buffered_output_stream_new(),
5409 * or g_buffered_output_stream_new_sized() to specify the buffer's size
5412 * To get the size of a buffer within a buffered input stream, use
5413 * g_buffered_output_stream_get_buffer_size(). To change the size of a
5414 * buffered output stream's buffer, use
5415 * g_buffered_output_stream_set_buffer_size(). Note that the buffer's
5416 * size cannot be reduced below the size of the data within the buffer.
5421 * SECTION:gbytesicon
5422 * @short_description: An icon stored in memory as a GBytes
5423 * @include: gio/gio.h
5424 * @see_also: #GIcon, #GLoadableIcon, #GBytes
5426 * #GBytesIcon specifies an image held in memory in a common format (usually
5427 * png) to be used as icon.
5434 * SECTION:gcancellable
5435 * @short_description: Thread-safe Operation Cancellation Stack
5436 * @include: gio/gio.h
5438 * GCancellable is a thread-safe operation cancellation stack used
5439 * throughout GIO to allow for cancellation of synchronous and
5440 * asynchronous operations.
5445 * SECTION:gcharsetconverter
5446 * @short_description: Convert between charsets
5447 * @include: gio/gio.h
5449 * #GCharsetConverter is an implementation of #GConverter based on
5455 * SECTION:gcontenttype
5456 * @short_description: Platform-specific content typing
5457 * @include: gio/gio.h
5459 * A content type is a platform specific string that defines the type
5460 * of a file. On UNIX it is a
5461 * [mime type](http://www.wikipedia.org/wiki/Internet_media_type)
5462 * like "text/plain" or "image/png".
5463 * On Win32 it is an extension string like ".doc", ".txt" or a perceived
5464 * string like "audio". Such strings can be looked up in the registry at
5465 * HKEY_CLASSES_ROOT.
5470 * SECTION:gconverter
5471 * @short_description: Data conversion interface
5472 * @include: gio/gio.h
5473 * @see_also: #GInputStream, #GOutputStream
5475 * #GConverter is implemented by objects that convert
5476 * binary data in various ways. The conversion can be
5477 * stateful and may fail at any place.
5479 * Some example conversions are: character set conversion,
5480 * compression, decompression and regular expression
5488 * SECTION:gconverterinputstream
5489 * @short_description: Converter Input Stream
5490 * @include: gio/gio.h
5491 * @see_also: #GInputStream, #GConverter
5493 * Converter input stream implements #GInputStream and allows
5494 * conversion of data of various types during reading.
5496 * As of GLib 2.34, #GConverterInputStream implements
5497 * #GPollableInputStream.
5502 * SECTION:gconverteroutputstream
5503 * @short_description: Converter Output Stream
5504 * @include: gio/gio.h
5505 * @see_also: #GOutputStream, #GConverter
5507 * Converter output stream implements #GOutputStream and allows
5508 * conversion of data of various types during reading.
5510 * As of GLib 2.34, #GConverterOutputStream implements
5511 * #GPollableOutputStream.
5516 * SECTION:gcredentials
5517 * @short_description: An object containing credentials
5518 * @include: gio/gio.h
5520 * The #GCredentials type is a reference-counted wrapper for native
5521 * credentials. This information is typically used for identifying,
5522 * authenticating and authorizing other processes.
5524 * Some operating systems supports looking up the credentials of the
5525 * remote peer of a communication endpoint - see e.g.
5526 * g_socket_get_credentials().
5528 * Some operating systems supports securely sending and receiving
5529 * credentials over a Unix Domain Socket, see
5530 * #GUnixCredentialsMessage, g_unix_connection_send_credentials() and
5531 * g_unix_connection_receive_credentials() for details.
5533 * On Linux, the native credential type is a struct ucred - see the
5534 * unix(7) man page for details. This corresponds to
5535 * %G_CREDENTIALS_TYPE_LINUX_UCRED.
5537 * On FreeBSD, Debian GNU/kFreeBSD, and GNU/Hurd, the native
5538 * credential type is a struct cmsgcred. This corresponds
5539 * to %G_CREDENTIALS_TYPE_FREEBSD_CMSGCRED.
5541 * On NetBSD, the native credential type is a struct unpcbid.
5542 * This corresponds to %G_CREDENTIALS_TYPE_NETBSD_UNPCBID.
5544 * On OpenBSD, the native credential type is a struct sockpeercred.
5545 * This corresponds to %G_CREDENTIALS_TYPE_OPENBSD_SOCKPEERCRED.
5547 * On Solaris (including OpenSolaris and its derivatives), the native
5548 * credential type is a ucred_t. This corresponds to
5549 * %G_CREDENTIALS_TYPE_SOLARIS_UCRED.
5554 * SECTION:gdatagrambased
5555 * @short_description: Low-level datagram communications interface
5556 * @include: gio/gio.h
5557 * @see_also: #GSocket, [<gnetworking.h>][gio-gnetworking.h]
5559 * A #GDatagramBased is a networking interface for representing datagram-based
5560 * communications. It is a more or less direct mapping of the core parts of the
5561 * BSD socket API in a portable GObject interface. It is implemented by
5562 * #GSocket, which wraps the UNIX socket API on UNIX and winsock2 on Windows.
5564 * #GDatagramBased is entirely platform independent, and is intended to be used
5565 * alongside higher-level networking APIs such as #GIOStream.
5567 * It uses vectored scatter/gather I/O by default, allowing for many messages
5568 * to be sent or received in a single call. Where possible, implementations of
5569 * the interface should take advantage of vectored I/O to minimise processing
5570 * or system calls. For example, #GSocket uses recvmmsg() and sendmmsg() where
5571 * possible. Callers should take advantage of scatter/gather I/O (the use of
5572 * multiple buffers per message) to avoid unnecessary copying of data to
5573 * assemble or disassemble a message.
5575 * Each #GDatagramBased operation has a timeout parameter which may be negative
5576 * for blocking behaviour, zero for non-blocking behaviour, or positive for
5577 * timeout behaviour. A blocking operation blocks until finished or there is an
5578 * error. A non-blocking operation will return immediately with a
5579 * %G_IO_ERROR_WOULD_BLOCK error if it cannot make progress. A timeout operation
5580 * will block until the operation is complete or the timeout expires; if the
5581 * timeout expires it will return what progress it made, or
5582 * %G_IO_ERROR_TIMED_OUT if no progress was made. To know when a call would
5583 * successfully run you can call g_datagram_based_condition_check() or
5584 * g_datagram_based_condition_wait(). You can also use
5585 * g_datagram_based_create_source() and attach it to a #GMainContext to get
5586 * callbacks when I/O is possible.
5588 * When running a non-blocking operation applications should always be able to
5589 * handle getting a %G_IO_ERROR_WOULD_BLOCK error even when some other function
5590 * said that I/O was possible. This can easily happen in case of a race
5591 * condition in the application, but it can also happen for other reasons. For
5592 * instance, on Windows a socket is always seen as writable until a write
5593 * returns %G_IO_ERROR_WOULD_BLOCK.
5595 * As with #GSocket, #GDatagramBaseds can be either connection oriented or
5596 * connectionless. The interface does not cover connection establishment — use
5597 * methods on the underlying type to establish a connection before sending and
5598 * receiving data through the #GDatagramBased API. For connectionless socket
5599 * types the target/source address is specified or received in each I/O
5602 * Like most other APIs in GLib, #GDatagramBased is not inherently thread safe.
5603 * To use a #GDatagramBased concurrently from multiple threads, you must
5604 * implement your own locking.
5611 * SECTION:gdatainputstream
5612 * @short_description: Data Input Stream
5613 * @include: gio/gio.h
5614 * @see_also: #GInputStream
5616 * Data input stream implements #GInputStream and includes functions for
5617 * reading structured data directly from a binary input stream.
5622 * SECTION:gdataoutputstream
5623 * @short_description: Data Output Stream
5624 * @include: gio/gio.h
5625 * @see_also: #GOutputStream
5627 * Data output stream implements #GOutputStream and includes functions for
5628 * writing data directly to an output stream.
5633 * SECTION:gdbusactiongroup
5634 * @title: GDBusActionGroup
5635 * @short_description: A D-Bus GActionGroup implementation
5636 * @include: gio/gio.h
5637 * @see_also: [GActionGroup exporter][gio-GActionGroup-exporter]
5639 * #GDBusActionGroup is an implementation of the #GActionGroup
5640 * interface that can be used as a proxy for an action group
5641 * that is exported over D-Bus with g_dbus_connection_export_action_group().
5646 * SECTION:gdbusaddress
5647 * @title: D-Bus Addresses
5648 * @short_description: D-Bus connection endpoints
5649 * @include: gio/gio.h
5651 * Routines for working with D-Bus addresses. A D-Bus address is a string
5652 * like "unix:tmpdir=/tmp/my-app-name". The exact format of addresses
5653 * is explained in detail in the [D-Bus specification](http://dbus.freedesktop.org/doc/dbus-specification.html\#addresses).
5658 * SECTION:gdbusauthobserver
5659 * @short_description: Object used for authenticating connections
5660 * @include: gio/gio.h
5662 * The #GDBusAuthObserver type provides a mechanism for participating
5663 * in how a #GDBusServer (or a #GDBusConnection) authenticates remote
5664 * peers. Simply instantiate a #GDBusAuthObserver and connect to the
5665 * signals you are interested in. Note that new signals may be added
5668 * ## Controlling Authentication # {#auth-observer}
5670 * For example, if you only want to allow D-Bus connections from
5671 * processes owned by the same uid as the server, you would use a
5672 * signal handler like the following:
5674 * |[<!-- language="C" -->
5676 * on_authorize_authenticated_peer (GDBusAuthObserver *observer,
5677 * GIOStream *stream,
5678 * GCredentials *credentials,
5679 * gpointer user_data)
5681 * gboolean authorized;
5683 * authorized = FALSE;
5684 * if (credentials != NULL)
5686 * GCredentials *own_credentials;
5687 * own_credentials = g_credentials_new ();
5688 * if (g_credentials_is_same_user (credentials, own_credentials, NULL))
5689 * authorized = TRUE;
5690 * g_object_unref (own_credentials);
5693 * return authorized;
5700 * SECTION:gdbusconnection
5701 * @short_description: D-Bus Connections
5702 * @include: gio/gio.h
5704 * The #GDBusConnection type is used for D-Bus connections to remote
5705 * peers such as a message buses. It is a low-level API that offers a
5706 * lot of flexibility. For instance, it lets you establish a connection
5707 * over any transport that can by represented as an #GIOStream.
5709 * This class is rarely used directly in D-Bus clients. If you are writing
5710 * a D-Bus client, it is often easier to use the g_bus_own_name(),
5711 * g_bus_watch_name() or g_dbus_proxy_new_for_bus() APIs.
5713 * As an exception to the usual GLib rule that a particular object must not
5714 * be used by two threads at the same time, #GDBusConnection's methods may be
5715 * called from any thread. This is so that g_bus_get() and g_bus_get_sync()
5716 * can safely return the same #GDBusConnection when called from any thread.
5718 * Most of the ways to obtain a #GDBusConnection automatically initialize it
5719 * (i.e. connect to D-Bus): for instance, g_dbus_connection_new() and
5720 * g_bus_get(), and the synchronous versions of those methods, give you an
5721 * initialized connection. Language bindings for GIO should use
5722 * g_initable_new() or g_async_initable_new_async(), which also initialize the
5725 * If you construct an uninitialized #GDBusConnection, such as via
5726 * g_object_new(), you must initialize it via g_initable_init() or
5727 * g_async_initable_init_async() before using its methods or properties.
5728 * Calling methods or accessing properties on a #GDBusConnection that has not
5729 * completed initialization successfully is considered to be invalid, and leads
5730 * to undefined behaviour. In particular, if initialization fails with a
5731 * #GError, the only valid thing you can do with that #GDBusConnection is to
5732 * free it with g_object_unref().
5734 * ## An example D-Bus server # {#gdbus-server}
5736 * Here is an example for a D-Bus server:
5737 * [gdbus-example-server.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-server.c)
5739 * ## An example for exporting a subtree # {#gdbus-subtree-server}
5741 * Here is an example for exporting a subtree:
5742 * [gdbus-example-subtree.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-subtree.c)
5744 * ## An example for file descriptor passing # {#gdbus-unix-fd-client}
5746 * Here is an example for passing UNIX file descriptors:
5747 * [gdbus-unix-fd-client.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-unix-fd-client.c)
5749 * ## An example for exporting a GObject # {#gdbus-export}
5751 * Here is an example for exporting a #GObject:
5752 * [gdbus-example-export.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-export.c)
5757 * SECTION:gdbuserror
5758 * @title: GDBusError
5759 * @short_description: Mapping D-Bus errors to and from GError
5760 * @include: gio/gio.h
5762 * All facilities that return errors from remote methods (such as
5763 * g_dbus_connection_call_sync()) use #GError to represent both D-Bus
5764 * errors (e.g. errors returned from the other peer) and locally
5765 * in-process generated errors.
5767 * To check if a returned #GError is an error from a remote peer, use
5768 * g_dbus_error_is_remote_error(). To get the actual D-Bus error name,
5769 * use g_dbus_error_get_remote_error(). Before presenting an error,
5770 * always use g_dbus_error_strip_remote_error().
5772 * In addition, facilities used to return errors to a remote peer also
5773 * use #GError. See g_dbus_method_invocation_return_error() for
5774 * discussion about how the D-Bus error name is set.
5776 * Applications can associate a #GError error domain with a set of D-Bus errors in order to
5777 * automatically map from D-Bus errors to #GError and back. This
5778 * is typically done in the function returning the #GQuark for the
5780 * |[<!-- language="C" -->
5781 * // foo-bar-error.h:
5783 * #define FOO_BAR_ERROR (foo_bar_error_quark ())
5784 * GQuark foo_bar_error_quark (void);
5788 * FOO_BAR_ERROR_FAILED,
5789 * FOO_BAR_ERROR_ANOTHER_ERROR,
5790 * FOO_BAR_ERROR_SOME_THIRD_ERROR,
5791 * FOO_BAR_N_ERRORS / *< skip >* /
5794 * // foo-bar-error.c:
5796 * static const GDBusErrorEntry foo_bar_error_entries[] =
5798 * {FOO_BAR_ERROR_FAILED, "org.project.Foo.Bar.Error.Failed"},
5799 * {FOO_BAR_ERROR_ANOTHER_ERROR, "org.project.Foo.Bar.Error.AnotherError"},
5800 * {FOO_BAR_ERROR_SOME_THIRD_ERROR, "org.project.Foo.Bar.Error.SomeThirdError"},
5803 * // Ensure that every error code has an associated D-Bus error name
5804 * G_STATIC_ASSERT (G_N_ELEMENTS (foo_bar_error_entries) == FOO_BAR_N_ERRORS);
5807 * foo_bar_error_quark (void)
5809 * static volatile gsize quark_volatile = 0;
5810 * g_dbus_error_register_error_domain ("foo-bar-error-quark",
5812 * foo_bar_error_entries,
5813 * G_N_ELEMENTS (foo_bar_error_entries));
5814 * return (GQuark) quark_volatile;
5817 * With this setup, a D-Bus peer can transparently pass e.g. %FOO_BAR_ERROR_ANOTHER_ERROR and
5818 * other peers will see the D-Bus error name org.project.Foo.Bar.Error.AnotherError.
5820 * If the other peer is using GDBus, and has registered the association with
5821 * g_dbus_error_register_error_domain() in advance (e.g. by invoking the %FOO_BAR_ERROR quark
5822 * generation itself in the previous example) the peer will see also %FOO_BAR_ERROR_ANOTHER_ERROR instead
5823 * of %G_IO_ERROR_DBUS_ERROR. Note that GDBus clients can still recover
5824 * org.project.Foo.Bar.Error.AnotherError using g_dbus_error_get_remote_error().
5826 * Note that errors in the %G_DBUS_ERROR error domain is intended only
5827 * for returning errors from a remote message bus process. Errors
5828 * generated locally in-process by e.g. #GDBusConnection is from the
5829 * %G_IO_ERROR domain.
5834 * SECTION:gdbusinterface
5835 * @short_description: Base type for D-Bus interfaces
5836 * @include: gio/gio.h
5838 * The #GDBusInterface type is the base type for D-Bus interfaces both
5839 * on the service side (see #GDBusInterfaceSkeleton) and client side
5840 * (see #GDBusProxy).
5845 * SECTION:gdbusinterfaceskeleton
5846 * @short_description: Service-side D-Bus interface
5847 * @include: gio/gio.h
5849 * Abstract base class for D-Bus interfaces on the service side.
5854 * SECTION:gdbusintrospection
5855 * @title: D-Bus Introspection Data
5856 * @short_description: Node and interface description data structures
5857 * @include: gio/gio.h
5859 * Various data structures and convenience routines to parse and
5860 * generate D-Bus introspection XML. Introspection information is
5861 * used when registering objects with g_dbus_connection_register_object().
5863 * The format of D-Bus introspection XML is specified in the
5864 * [D-Bus specification](http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format)
5869 * SECTION:gdbusmenumodel
5870 * @title: GDBusMenuModel
5871 * @short_description: A D-Bus GMenuModel implementation
5872 * @include: gio/gio.h
5873 * @see_also: [GMenuModel Exporter][gio-GMenuModel-exporter]
5875 * #GDBusMenuModel is an implementation of #GMenuModel that can be used
5876 * as a proxy for a menu model that is exported over D-Bus with
5877 * g_dbus_connection_export_menu_model().
5882 * SECTION:gdbusmessage
5883 * @short_description: D-Bus Message
5884 * @include: gio/gio.h
5886 * A type for representing D-Bus messages that can be sent or received
5887 * on a #GDBusConnection.
5892 * SECTION:gdbusmethodinvocation
5893 * @short_description: Object for handling remote calls
5894 * @include: gio/gio.h
5896 * Instances of the #GDBusMethodInvocation class are used when
5897 * handling D-Bus method calls. It provides a way to asynchronously
5898 * return results and errors.
5900 * The normal way to obtain a #GDBusMethodInvocation object is to receive
5901 * it as an argument to the handle_method_call() function in a
5902 * #GDBusInterfaceVTable that was passed to g_dbus_connection_register_object().
5907 * SECTION:gdbusnameowning
5908 * @title: Owning Bus Names
5909 * @short_description: Simple API for owning bus names
5910 * @include: gio/gio.h
5912 * Convenience API for owning bus names.
5914 * A simple example for owning a name can be found in
5915 * [gdbus-example-own-name.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-own-name.c)
5920 * SECTION:gdbusnamewatching
5921 * @title: Watching Bus Names
5922 * @short_description: Simple API for watching bus names
5923 * @include: gio/gio.h
5925 * Convenience API for watching bus names.
5927 * A simple example for watching a name can be found in
5928 * [gdbus-example-watch-name.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-watch-name.c)
5933 * SECTION:gdbusobject
5934 * @short_description: Base type for D-Bus objects
5935 * @include: gio/gio.h
5937 * The #GDBusObject type is the base type for D-Bus objects on both
5938 * the service side (see #GDBusObjectSkeleton) and the client side
5939 * (see #GDBusObjectProxy). It is essentially just a container of
5945 * SECTION:gdbusobjectmanager
5946 * @short_description: Base type for D-Bus object managers
5947 * @include: gio/gio.h
5949 * The #GDBusObjectManager type is the base type for service- and
5950 * client-side implementations of the standardized
5951 * [org.freedesktop.DBus.ObjectManager](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager)
5954 * See #GDBusObjectManagerClient for the client-side implementation
5955 * and #GDBusObjectManagerServer for the service-side implementation.
5960 * SECTION:gdbusobjectmanagerclient
5961 * @short_description: Client-side object manager
5962 * @include: gio/gio.h
5964 * #GDBusObjectManagerClient is used to create, monitor and delete object
5965 * proxies for remote objects exported by a #GDBusObjectManagerServer (or any
5966 * code implementing the
5967 * [org.freedesktop.DBus.ObjectManager](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager)
5970 * Once an instance of this type has been created, you can connect to
5971 * the #GDBusObjectManager::object-added and
5972 * #GDBusObjectManager::object-removed signals and inspect the
5973 * #GDBusObjectProxy objects returned by
5974 * g_dbus_object_manager_get_objects().
5976 * If the name for a #GDBusObjectManagerClient is not owned by anyone at
5977 * object construction time, the default behavior is to request the
5978 * message bus to launch an owner for the name. This behavior can be
5979 * disabled using the %G_DBUS_OBJECT_MANAGER_CLIENT_FLAGS_DO_NOT_AUTO_START
5980 * flag. It's also worth noting that this only works if the name of
5981 * interest is activatable in the first place. E.g. in some cases it
5982 * is not possible to launch an owner for the requested name. In this
5983 * case, #GDBusObjectManagerClient object construction still succeeds but
5984 * there will be no object proxies
5985 * (e.g. g_dbus_object_manager_get_objects() returns the empty list) and
5986 * the #GDBusObjectManagerClient:name-owner property is %NULL.
5988 * The owner of the requested name can come and go (for example
5989 * consider a system service being restarted) – #GDBusObjectManagerClient
5990 * handles this case too; simply connect to the #GObject::notify
5991 * signal to watch for changes on the #GDBusObjectManagerClient:name-owner
5992 * property. When the name owner vanishes, the behavior is that
5993 * #GDBusObjectManagerClient:name-owner is set to %NULL (this includes
5994 * emission of the #GObject::notify signal) and then
5995 * #GDBusObjectManager::object-removed signals are synthesized
5996 * for all currently existing object proxies. Since
5997 * #GDBusObjectManagerClient:name-owner is %NULL when this happens, you can
5998 * use this information to disambiguate a synthesized signal from a
5999 * genuine signal caused by object removal on the remote
6000 * #GDBusObjectManager. Similarly, when a new name owner appears,
6001 * #GDBusObjectManager::object-added signals are synthesized
6002 * while #GDBusObjectManagerClient:name-owner is still %NULL. Only when all
6003 * object proxies have been added, the #GDBusObjectManagerClient:name-owner
6004 * is set to the new name owner (this includes emission of the
6005 * #GObject::notify signal). Furthermore, you are guaranteed that
6006 * #GDBusObjectManagerClient:name-owner will alternate between a name owner
6007 * (e.g. `:1.42`) and %NULL even in the case where
6008 * the name of interest is atomically replaced
6010 * Ultimately, #GDBusObjectManagerClient is used to obtain #GDBusProxy
6011 * instances. All signals (including the
6012 * org.freedesktop.DBus.Properties::PropertiesChanged signal)
6013 * delivered to #GDBusProxy instances are guaranteed to originate
6014 * from the name owner. This guarantee along with the behavior
6015 * described above, means that certain race conditions including the
6016 * "half the proxy is from the old owner and the other half is from
6017 * the new owner" problem cannot happen.
6019 * To avoid having the application connect to signals on the returned
6020 * #GDBusObjectProxy and #GDBusProxy objects, the
6021 * #GDBusObject::interface-added,
6022 * #GDBusObject::interface-removed,
6023 * #GDBusProxy::g-properties-changed and
6024 * #GDBusProxy::g-signal signals
6025 * are also emitted on the #GDBusObjectManagerClient instance managing these
6026 * objects. The signals emitted are
6027 * #GDBusObjectManager::interface-added,
6028 * #GDBusObjectManager::interface-removed,
6029 * #GDBusObjectManagerClient::interface-proxy-properties-changed and
6030 * #GDBusObjectManagerClient::interface-proxy-signal.
6032 * Note that all callbacks and signals are emitted in the
6033 * [thread-default main context][g-main-context-push-thread-default]
6034 * that the #GDBusObjectManagerClient object was constructed
6035 * in. Additionally, the #GDBusObjectProxy and #GDBusProxy objects
6036 * originating from the #GDBusObjectManagerClient object will be created in
6037 * the same context and, consequently, will deliver signals in the
6043 * SECTION:gdbusobjectmanagerserver
6044 * @short_description: Service-side object manager
6045 * @include: gio/gio.h
6047 * #GDBusObjectManagerServer is used to export #GDBusObject instances using
6049 * [org.freedesktop.DBus.ObjectManager](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager)
6050 * interface. For example, remote D-Bus clients can get all objects
6051 * and properties in a single call. Additionally, any change in the
6052 * object hierarchy is broadcast using signals. This means that D-Bus
6053 * clients can keep caches up to date by only listening to D-Bus
6056 * The recommended path to export an object manager at is the path form of the
6057 * well-known name of a D-Bus service, or below. For example, if a D-Bus service
6058 * is available at the well-known name `net.example.ExampleService1`, the object
6059 * manager should typically be exported at `/net/example/ExampleService1`, or
6060 * below (to allow for multiple object managers in a service).
6062 * It is supported, but not recommended, to export an object manager at the root
6065 * See #GDBusObjectManagerClient for the client-side code that is
6066 * intended to be used with #GDBusObjectManagerServer or any D-Bus
6067 * object implementing the org.freedesktop.DBus.ObjectManager
6073 * SECTION:gdbusobjectproxy
6074 * @short_description: Client-side D-Bus object
6075 * @include: gio/gio.h
6077 * A #GDBusObjectProxy is an object used to represent a remote object
6078 * with one or more D-Bus interfaces. Normally, you don't instantiate
6079 * a #GDBusObjectProxy yourself - typically #GDBusObjectManagerClient
6080 * is used to obtain it.
6087 * SECTION:gdbusobjectskeleton
6088 * @short_description: Service-side D-Bus object
6089 * @include: gio/gio.h
6091 * A #GDBusObjectSkeleton instance is essentially a group of D-Bus
6092 * interfaces. The set of exported interfaces on the object may be
6093 * dynamic and change at runtime.
6095 * This type is intended to be used with #GDBusObjectManager.
6100 * SECTION:gdbusproxy
6101 * @short_description: Client-side D-Bus interface proxy
6102 * @include: gio/gio.h
6104 * #GDBusProxy is a base class used for proxies to access a D-Bus
6105 * interface on a remote object. A #GDBusProxy can be constructed for
6106 * both well-known and unique names.
6108 * By default, #GDBusProxy will cache all properties (and listen to
6109 * changes) of the remote object, and proxy all signals that gets
6110 * emitted. This behaviour can be changed by passing suitable
6111 * #GDBusProxyFlags when the proxy is created. If the proxy is for a
6112 * well-known name, the property cache is flushed when the name owner
6113 * vanishes and reloaded when a name owner appears.
6115 * If a #GDBusProxy is used for a well-known name, the owner of the
6116 * name is tracked and can be read from
6117 * #GDBusProxy:g-name-owner. Connect to the #GObject::notify signal to
6118 * get notified of changes. Additionally, only signals and property
6119 * changes emitted from the current name owner are considered and
6120 * calls are always sent to the current name owner. This avoids a
6121 * number of race conditions when the name is lost by one owner and
6122 * claimed by another. However, if no name owner currently exists,
6123 * then calls will be sent to the well-known name which may result in
6124 * the message bus launching an owner (unless
6125 * %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START is set).
6127 * The generic #GDBusProxy::g-properties-changed and
6128 * #GDBusProxy::g-signal signals are not very convenient to work with.
6129 * Therefore, the recommended way of working with proxies is to subclass
6130 * #GDBusProxy, and have more natural properties and signals in your derived
6131 * class. This [example][gdbus-example-gdbus-codegen] shows how this can
6132 * easily be done using the [gdbus-codegen][gdbus-codegen] tool.
6134 * A #GDBusProxy instance can be used from multiple threads but note
6135 * that all signals (e.g. #GDBusProxy::g-signal, #GDBusProxy::g-properties-changed
6136 * and #GObject::notify) are emitted in the
6137 * [thread-default main context][g-main-context-push-thread-default]
6138 * of the thread where the instance was constructed.
6140 * An example using a proxy for a well-known name can be found in
6141 * [gdbus-example-watch-proxy.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-watch-proxy.c)
6146 * SECTION:gdbusserver
6147 * @short_description: Helper for accepting connections
6148 * @include: gio/gio.h
6150 * #GDBusServer is a helper for listening to and accepting D-Bus
6151 * connections. This can be used to create a new D-Bus server, allowing two
6152 * peers to use the D-Bus protocol for their own specialized communication.
6153 * A server instance provided in this way will not perform message routing or
6154 * implement the org.freedesktop.DBus interface.
6156 * To just export an object on a well-known name on a message bus, such as the
6157 * session or system bus, you should instead use g_bus_own_name().
6159 * An example of peer-to-peer communication with G-DBus can be found
6160 * in [gdbus-example-peer.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-peer.c).
6165 * SECTION:gdbusutils
6166 * @title: D-Bus Utilities
6167 * @short_description: Various utilities related to D-Bus
6168 * @include: gio/gio.h
6170 * Various utility routines related to D-Bus.
6175 * SECTION:gdesktopappinfo
6176 * @title: GDesktopAppInfo
6177 * @short_description: Application information from desktop files
6178 * @include: gio/gdesktopappinfo.h
6180 * #GDesktopAppInfo is an implementation of #GAppInfo based on
6183 * Note that `<gio/gdesktopappinfo.h>` belongs to the UNIX-specific
6184 * GIO interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config
6185 * file when using it.
6191 * @short_description: Drive management
6192 * @include: gio/gio.h
6194 * #GDrive - this represent a piece of hardware connected to the machine.
6195 * It's generally only created for removable hardware or hardware with
6198 * #GDrive is a container class for #GVolume objects that stem from
6199 * the same piece of media. As such, #GDrive abstracts a drive with
6200 * (or without) removable media and provides operations for querying
6201 * whether media is available, determining whether media change is
6202 * automatically detected and ejecting the media.
6204 * If the #GDrive reports that media isn't automatically detected, one
6205 * can poll for media; typically one should not do this periodically
6206 * as a poll for media operation is potententially expensive and may
6207 * spin up the drive creating noise.
6209 * #GDrive supports starting and stopping drives with authentication
6210 * support for the former. This can be used to support a diverse set
6211 * of use cases including connecting/disconnecting iSCSI devices,
6212 * powering down external disk enclosures and starting/stopping
6213 * multi-disk devices such as RAID devices. Note that the actual
6214 * semantics and side-effects of starting/stopping a #GDrive may vary
6215 * according to implementation. To choose the correct verbs in e.g. a
6216 * file manager, use g_drive_get_start_stop_type().
6218 * For porting from GnomeVFS note that there is no equivalent of
6219 * #GDrive in that API.
6224 * SECTION:gdtlsclientconnection
6225 * @short_description: DTLS client-side connection
6226 * @include: gio/gio.h
6228 * #GDtlsClientConnection is the client-side subclass of
6229 * #GDtlsConnection, representing a client-side DTLS connection.
6236 * SECTION:gdtlsconnection
6237 * @short_description: DTLS connection type
6238 * @include: gio/gio.h
6240 * #GDtlsConnection is the base DTLS connection class type, which wraps
6241 * a #GDatagramBased and provides DTLS encryption on top of it. Its
6242 * subclasses, #GDtlsClientConnection and #GDtlsServerConnection,
6243 * implement client-side and server-side DTLS, respectively.
6245 * For TLS support, see #GTlsConnection.
6247 * As DTLS is datagram based, #GDtlsConnection implements #GDatagramBased,
6248 * presenting a datagram-socket-like API for the encrypted connection. This
6249 * operates over a base datagram connection, which is also a #GDatagramBased
6250 * (#GDtlsConnection:base-socket).
6252 * To close a DTLS connection, use g_dtls_connection_close().
6254 * Neither #GDtlsServerConnection or #GDtlsClientConnection set the peer address
6255 * on their base #GDatagramBased if it is a #GSocket — it is up to the caller to
6256 * do that if they wish. If they do not, and g_socket_close() is called on the
6257 * base socket, the #GDtlsConnection will not raise a %G_IO_ERROR_NOT_CONNECTED
6258 * error on further I/O.
6265 * SECTION:gdtlsserverconnection
6266 * @short_description: DTLS server-side connection
6267 * @include: gio/gio.h
6269 * #GDtlsServerConnection is the server-side subclass of #GDtlsConnection,
6270 * representing a server-side DTLS connection.
6278 * @short_description: An object for emblems
6279 * @include: gio/gio.h
6280 * @see_also: #GIcon, #GEmblemedIcon, #GLoadableIcon, #GThemedIcon
6282 * #GEmblem is an implementation of #GIcon that supports
6283 * having an emblem, which is an icon with additional properties.
6284 * It can than be added to a #GEmblemedIcon.
6286 * Currently, only metainformation about the emblem's origin is
6287 * supported. More may be added in the future.
6292 * SECTION:gemblemedicon
6293 * @short_description: Icon with emblems
6294 * @include: gio/gio.h
6295 * @see_also: #GIcon, #GLoadableIcon, #GThemedIcon, #GEmblem
6297 * #GEmblemedIcon is an implementation of #GIcon that supports
6298 * adding an emblem to an icon. Adding multiple emblems to an
6299 * icon is ensured via g_emblemed_icon_add_emblem().
6301 * Note that #GEmblemedIcon allows no control over the position
6302 * of the emblems. See also #GEmblem for more information.
6308 * @short_description: File and Directory Handling
6309 * @include: gio/gio.h
6310 * @see_also: #GFileInfo, #GFileEnumerator
6312 * #GFile is a high level abstraction for manipulating files on a
6313 * virtual file system. #GFiles are lightweight, immutable objects
6314 * that do no I/O upon creation. It is necessary to understand that
6315 * #GFile objects do not represent files, merely an identifier for a
6316 * file. All file content I/O is implemented as streaming operations
6317 * (see #GInputStream and #GOutputStream).
6319 * To construct a #GFile, you can use:
6320 * - g_file_new_for_path() if you have a path.
6321 * - g_file_new_for_uri() if you have a URI.
6322 * - g_file_new_for_commandline_arg() for a command line argument.
6323 * - g_file_new_tmp() to create a temporary file from a template.
6324 * - g_file_parse_name() from a UTF-8 string gotten from g_file_get_parse_name().
6326 * One way to think of a #GFile is as an abstraction of a pathname. For
6327 * normal files the system pathname is what is stored internally, but as
6328 * #GFiles are extensible it could also be something else that corresponds
6329 * to a pathname in a userspace implementation of a filesystem.
6331 * #GFiles make up hierarchies of directories and files that correspond to
6332 * the files on a filesystem. You can move through the file system with
6333 * #GFile using g_file_get_parent() to get an identifier for the parent
6334 * directory, g_file_get_child() to get a child within a directory,
6335 * g_file_resolve_relative_path() to resolve a relative path between two
6336 * #GFiles. There can be multiple hierarchies, so you may not end up at
6337 * the same root if you repeatedly call g_file_get_parent() on two different
6340 * All #GFiles have a basename (get with g_file_get_basename()). These names
6341 * are byte strings that are used to identify the file on the filesystem
6342 * (relative to its parent directory) and there is no guarantees that they
6343 * have any particular charset encoding or even make any sense at all. If
6344 * you want to use filenames in a user interface you should use the display
6345 * name that you can get by requesting the
6346 * %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME attribute with g_file_query_info().
6347 * This is guaranteed to be in UTF-8 and can be used in a user interface.
6348 * But always store the real basename or the #GFile to use to actually
6349 * access the file, because there is no way to go from a display name to
6352 * Using #GFile as an identifier has the same weaknesses as using a path
6353 * in that there may be multiple aliases for the same file. For instance,
6354 * hard or soft links may cause two different #GFiles to refer to the same
6355 * file. Other possible causes for aliases are: case insensitive filesystems,
6356 * short and long names on FAT/NTFS, or bind mounts in Linux. If you want to
6357 * check if two #GFiles point to the same file you can query for the
6358 * %G_FILE_ATTRIBUTE_ID_FILE attribute. Note that #GFile does some trivial
6359 * canonicalization of pathnames passed in, so that trivial differences in
6360 * the path string used at creation (duplicated slashes, slash at end of
6361 * path, "." or ".." path segments, etc) does not create different #GFiles.
6363 * Many #GFile operations have both synchronous and asynchronous versions
6364 * to suit your application. Asynchronous versions of synchronous functions
6365 * simply have _async() appended to their function names. The asynchronous
6366 * I/O functions call a #GAsyncReadyCallback which is then used to finalize
6367 * the operation, producing a GAsyncResult which is then passed to the
6368 * function's matching _finish() operation.
6370 * It is highly recommended to use asynchronous calls when running within a
6371 * shared main loop, such as in the main thread of an application. This avoids
6372 * I/O operations blocking other sources on the main loop from being dispatched.
6373 * Synchronous I/O operations should be performed from worker threads. See the
6374 * [introduction to asynchronous programming section][async-programming] for
6377 * Some #GFile operations almost always take a noticeable amount of time, and
6378 * so do not have synchronous analogs. Notable cases include:
6379 * - g_file_mount_mountable() to mount a mountable file.
6380 * - g_file_unmount_mountable_with_operation() to unmount a mountable file.
6381 * - g_file_eject_mountable_with_operation() to eject a mountable file.
6383 * ## Entity Tags # {#gfile-etag}
6385 * One notable feature of #GFiles are entity tags, or "etags" for
6386 * short. Entity tags are somewhat like a more abstract version of the
6387 * traditional mtime, and can be used to quickly determine if the file
6388 * has been modified from the version on the file system. See the
6390 * [specification](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html)
6391 * for HTTP Etag headers, which are a very similar concept.
6396 * SECTION:gfileattribute
6397 * @short_description: Key-Value Paired File Attributes
6398 * @include: gio/gio.h
6399 * @see_also: #GFile, #GFileInfo
6401 * File attributes in GIO consist of a list of key-value pairs.
6403 * Keys are strings that contain a key namespace and a key name, separated
6404 * by a colon, e.g. "namespace::keyname". Namespaces are included to sort
6405 * key-value pairs by namespaces for relevance. Keys can be retrived
6406 * using wildcards, e.g. "standard::*" will return all of the keys in the
6407 * "standard" namespace.
6409 * The list of possible attributes for a filesystem (pointed to by a #GFile) is
6410 * available as a #GFileAttributeInfoList. This list is queryable by key names
6411 * as indicated earlier.
6413 * Information is stored within the list in #GFileAttributeInfo structures.
6414 * The info structure can store different types, listed in the enum
6415 * #GFileAttributeType. Upon creation of a #GFileAttributeInfo, the type will
6416 * be set to %G_FILE_ATTRIBUTE_TYPE_INVALID.
6418 * Classes that implement #GFileIface will create a #GFileAttributeInfoList and
6419 * install default keys and values for their given file system, architecture,
6420 * and other possible implementation details (e.g., on a UNIX system, a file
6421 * attribute key will be registered for the user id for a given file).
6423 * ## Default Namespaces
6425 * - `"standard"`: The "Standard" namespace. General file information that
6426 * any application may need should be put in this namespace. Examples
6427 * include the file's name, type, and size.
6428 * - `"etag`: The [Entity Tag][gfile-etag] namespace. Currently, the only key
6429 * in this namespace is "value", which contains the value of the current
6431 * - `"id"`: The "Identification" namespace. This namespace is used by file
6432 * managers and applications that list directories to check for loops and
6433 * to uniquely identify files.
6434 * - `"access"`: The "Access" namespace. Used to check if a user has the
6435 * proper privileges to access files and perform file operations. Keys in
6436 * this namespace are made to be generic and easily understood, e.g. the
6437 * "can_read" key is %TRUE if the current user has permission to read the
6438 * file. UNIX permissions and NTFS ACLs in Windows should be mapped to
6440 * - `"mountable"`: The "Mountable" namespace. Includes simple boolean keys
6441 * for checking if a file or path supports mount operations, e.g. mount,
6442 * unmount, eject. These are used for files of type %G_FILE_TYPE_MOUNTABLE.
6443 * - `"time"`: The "Time" namespace. Includes file access, changed, created
6445 * - `"unix"`: The "Unix" namespace. Includes UNIX-specific information and
6446 * may not be available for all files. Examples include the UNIX "UID",
6448 * - `"dos"`: The "DOS" namespace. Includes DOS-specific information and may
6449 * not be available for all files. Examples include "is_system" for checking
6450 * if a file is marked as a system file, and "is_archive" for checking if a
6451 * file is marked as an archive file.
6452 * - `"owner"`: The "Owner" namespace. Includes information about who owns a
6453 * file. May not be available for all file systems. Examples include "user"
6454 * for getting the user name of the file owner. This information is often
6455 * mapped from some backend specific data such as a UNIX UID.
6456 * - `"thumbnail"`: The "Thumbnail" namespace. Includes information about file
6457 * thumbnails and their location within the file system. Examples of keys in
6458 * this namespace include "path" to get the location of a thumbnail, "failed"
6459 * to check if thumbnailing of the file failed, and "is-valid" to check if
6460 * the thumbnail is outdated.
6461 * - `"filesystem"`: The "Filesystem" namespace. Gets information about the
6462 * file system where a file is located, such as its type, how much space is
6463 * left available, and the overall size of the file system.
6464 * - `"gvfs"`: The "GVFS" namespace. Keys in this namespace contain information
6465 * about the current GVFS backend in use.
6466 * - `"xattr"`: The "xattr" namespace. Gets information about extended
6467 * user attributes. See attr(5). The "user." prefix of the extended user
6468 * attribute name is stripped away when constructing keys in this namespace,
6469 * e.g. "xattr::mime_type" for the extended attribute with the name
6470 * "user.mime_type". Note that this information is only available if
6471 * GLib has been built with extended attribute support.
6472 * - `"xattr-sys"`: The "xattr-sys" namespace. Gets information about
6473 * extended attributes which are not user-specific. See attr(5). Note
6474 * that this information is only available if GLib has been built with
6475 * extended attribute support.
6476 * - `"selinux"`: The "SELinux" namespace. Includes information about the
6477 * SELinux context of files. Note that this information is only available
6478 * if GLib has been built with SELinux support.
6480 * Please note that these are not all of the possible namespaces.
6481 * More namespaces can be added from GIO modules or by individual applications.
6482 * For more information about writing GIO modules, see #GIOModule.
6484 * <!-- TODO: Implementation note about using extended attributes on supported
6489 * For a list of the built-in keys and their types, see the
6490 * [GFileInfo][GFileInfo] documentation.
6492 * Note that there are no predefined keys in the "xattr" and "xattr-sys"
6493 * namespaces. Keys for the "xattr" namespace are constructed by stripping
6494 * away the "user." prefix from the extended user attribute, and prepending
6495 * "xattr::". Keys for the "xattr-sys" namespace are constructed by
6496 * concatenating "xattr-sys::" with the extended attribute name. All extended
6497 * attribute values are returned as hex-encoded strings in which bytes outside
6498 * the ASCII range are encoded as escape sequences of the form \x`nn`
6499 * where `nn` is a 2-digit hexadecimal number.
6504 * SECTION:gfiledescriptorbased
6505 * @short_description: Interface for file descriptor based IO
6506 * @include: gio/gfiledescriptorbased.h
6507 * @see_also: #GInputStream, #GOutputStream
6509 * #GFileDescriptorBased is implemented by streams (implementations of
6510 * #GInputStream or #GOutputStream) that are based on file descriptors.
6512 * Note that `<gio/gfiledescriptorbased.h>` belongs to the UNIX-specific
6513 * GIO interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config
6514 * file when using it.
6521 * SECTION:gfileenumerator
6522 * @short_description: Enumerated Files Routines
6523 * @include: gio/gio.h
6525 * #GFileEnumerator allows you to operate on a set of #GFiles,
6526 * returning a #GFileInfo structure for each file enumerated (e.g.
6527 * g_file_enumerate_children() will return a #GFileEnumerator for each
6528 * of the children within a directory).
6530 * To get the next file's information from a #GFileEnumerator, use
6531 * g_file_enumerator_next_file() or its asynchronous version,
6532 * g_file_enumerator_next_files_async(). Note that the asynchronous
6533 * version will return a list of #GFileInfos, whereas the
6534 * synchronous will only return the next file in the enumerator.
6536 * The ordering of returned files is unspecified for non-Unix
6537 * platforms; for more information, see g_dir_read_name(). On Unix,
6538 * when operating on local files, returned files will be sorted by
6539 * inode number. Effectively you can assume that the ordering of
6540 * returned files will be stable between successive calls (and
6541 * applications) assuming the directory is unchanged.
6543 * If your application needs a specific ordering, such as by name or
6544 * modification time, you will have to implement that in your
6547 * To close a #GFileEnumerator, use g_file_enumerator_close(), or
6548 * its asynchronous version, g_file_enumerator_close_async(). Once
6549 * a #GFileEnumerator is closed, no further actions may be performed
6550 * on it, and it should be freed with g_object_unref().
6556 * @short_description: Icons pointing to an image file
6557 * @include: gio/gio.h
6558 * @see_also: #GIcon, #GLoadableIcon
6560 * #GFileIcon specifies an icon by pointing to an image file
6561 * to be used as icon.
6567 * @short_description: File Information and Attributes
6568 * @include: gio/gio.h
6569 * @see_also: #GFile, [GFileAttribute][gio-GFileAttribute]
6571 * Functionality for manipulating basic metadata for files. #GFileInfo
6572 * implements methods for getting information that all files should
6573 * contain, and allows for manipulation of extended attributes.
6575 * See [GFileAttribute][gio-GFileAttribute] for more information on how
6576 * GIO handles file attributes.
6578 * To obtain a #GFileInfo for a #GFile, use g_file_query_info() (or its
6579 * async variant). To obtain a #GFileInfo for a file input or output
6580 * stream, use g_file_input_stream_query_info() or
6581 * g_file_output_stream_query_info() (or their async variants).
6583 * To change the actual attributes of a file, you should then set the
6584 * attribute in the #GFileInfo and call g_file_set_attributes_from_info()
6585 * or g_file_set_attributes_async() on a GFile.
6587 * However, not all attributes can be changed in the file. For instance,
6588 * the actual size of a file cannot be changed via g_file_info_set_size().
6589 * You may call g_file_query_settable_attributes() and
6590 * g_file_query_writable_namespaces() to discover the settable attributes
6591 * of a particular file at runtime.
6593 * #GFileAttributeMatcher allows for searching through a #GFileInfo for
6599 * SECTION:gfileinputstream
6600 * @short_description: File input streaming operations
6601 * @include: gio/gio.h
6602 * @see_also: #GInputStream, #GDataInputStream, #GSeekable
6604 * GFileInputStream provides input streams that take their
6605 * content from a file.
6607 * GFileInputStream implements #GSeekable, which allows the input
6608 * stream to jump to arbitrary positions in the file, provided the
6609 * filesystem of the file allows it. To find the position of a file
6610 * input stream, use g_seekable_tell(). To find out if a file input
6611 * stream supports seeking, use g_seekable_can_seek().
6612 * To position a file input stream, use g_seekable_seek().
6617 * SECTION:gfileiostream
6618 * @short_description: File read and write streaming operations
6619 * @include: gio/gio.h
6620 * @see_also: #GIOStream, #GFileInputStream, #GFileOutputStream, #GSeekable
6622 * GFileIOStream provides io streams that both read and write to the same
6625 * GFileIOStream implements #GSeekable, which allows the io
6626 * stream to jump to arbitrary positions in the file and to truncate
6627 * the file, provided the filesystem of the file supports these
6630 * To find the position of a file io stream, use
6631 * g_seekable_tell().
6633 * To find out if a file io stream supports seeking, use g_seekable_can_seek().
6634 * To position a file io stream, use g_seekable_seek().
6635 * To find out if a file io stream supports truncating, use
6636 * g_seekable_can_truncate(). To truncate a file io
6637 * stream, use g_seekable_truncate().
6639 * The default implementation of all the #GFileIOStream operations
6640 * and the implementation of #GSeekable just call into the same operations
6641 * on the output stream.
6648 * SECTION:gfilemonitor
6649 * @short_description: File Monitor
6650 * @include: gio/gio.h
6652 * Monitors a file or directory for changes.
6654 * To obtain a #GFileMonitor for a file or directory, use
6655 * g_file_monitor(), g_file_monitor_file(), or
6656 * g_file_monitor_directory().
6658 * To get informed about changes to the file or directory you are
6659 * monitoring, connect to the #GFileMonitor::changed signal. The
6660 * signal will be emitted in the
6661 * [thread-default main context][g-main-context-push-thread-default]
6662 * of the thread that the monitor was created in
6663 * (though if the global default main context is blocked, this may
6664 * cause notifications to be blocked even if the thread-default
6665 * context is still running).
6670 * SECTION:gfilenamecompleter
6671 * @short_description: Filename Completer
6672 * @include: gio/gio.h
6674 * Completes partial file and directory names given a partial string by
6675 * looking in the file system for clues. Can return a list of possible
6676 * completion strings for widget implementations.
6681 * SECTION:gfileoutputstream
6682 * @short_description: File output streaming operations
6683 * @include: gio/gio.h
6684 * @see_also: #GOutputStream, #GDataOutputStream, #GSeekable
6686 * GFileOutputStream provides output streams that write their
6687 * content to a file.
6689 * GFileOutputStream implements #GSeekable, which allows the output
6690 * stream to jump to arbitrary positions in the file and to truncate
6691 * the file, provided the filesystem of the file supports these
6694 * To find the position of a file output stream, use g_seekable_tell().
6695 * To find out if a file output stream supports seeking, use
6696 * g_seekable_can_seek().To position a file output stream, use
6697 * g_seekable_seek(). To find out if a file output stream supports
6698 * truncating, use g_seekable_can_truncate(). To truncate a file output
6699 * stream, use g_seekable_truncate().
6704 * SECTION:gfilterinputstream
6705 * @short_description: Filter Input Stream
6706 * @include: gio/gio.h
6708 * Base class for input stream implementations that perform some
6709 * kind of filtering operation on a base stream. Typical examples
6710 * of filtering operations are character set conversion, compression
6711 * and byte order flipping.
6716 * SECTION:gfilteroutputstream
6717 * @short_description: Filter Output Stream
6718 * @include: gio/gio.h
6720 * Base class for output stream implementations that perform some
6721 * kind of filtering operation on a base stream. Typical examples
6722 * of filtering operations are character set conversion, compression
6723 * and byte order flipping.
6729 * @short_description: Interface for icons
6730 * @include: gio/gio.h
6732 * #GIcon is a very minimal interface for icons. It provides functions
6733 * for checking the equality of two icons, hashing of icons and
6734 * serializing an icon to and from strings.
6736 * #GIcon does not provide the actual pixmap for the icon as this is out
6737 * of GIO's scope, however implementations of #GIcon may contain the name
6738 * of an icon (see #GThemedIcon), or the path to an icon (see #GLoadableIcon).
6740 * To obtain a hash of a #GIcon, see g_icon_hash().
6742 * To check if two #GIcons are equal, see g_icon_equal().
6744 * For serializing a #GIcon, use g_icon_serialize() and
6745 * g_icon_deserialize().
6747 * If you want to consume #GIcon (for example, in a toolkit) you must
6748 * be prepared to handle at least the three following cases:
6749 * #GLoadableIcon, #GThemedIcon and #GEmblemedIcon. It may also make
6750 * sense to have fast-paths for other cases (like handling #GdkPixbuf
6751 * directly, for example) but all compliant #GIcon implementations
6752 * outside of GIO must implement #GLoadableIcon.
6754 * If your application or library provides one or more #GIcon
6755 * implementations you need to ensure that your new implementation also
6756 * implements #GLoadableIcon. Additionally, you must provide an
6757 * implementation of g_icon_serialize() that gives a result that is
6758 * understood by g_icon_deserialize(), yielding one of the built-in icon
6764 * SECTION:ginetaddress
6765 * @short_description: An IPv4/IPv6 address
6766 * @include: gio/gio.h
6768 * #GInetAddress represents an IPv4 or IPv6 internet address. Use
6769 * g_resolver_lookup_by_name() or g_resolver_lookup_by_name_async() to
6770 * look up the #GInetAddress for a hostname. Use
6771 * g_resolver_lookup_by_address() or
6772 * g_resolver_lookup_by_address_async() to look up the hostname for a
6775 * To actually connect to a remote host, you will need a
6776 * #GInetSocketAddress (which includes a #GInetAddress as well as a
6782 * SECTION:ginetaddressmask
6783 * @short_description: An IPv4/IPv6 address mask
6784 * @include: gio/gio.h
6786 * #GInetAddressMask represents a range of IPv4 or IPv6 addresses
6787 * described by a base address and a length indicating how many bits
6788 * of the base address are relevant for matching purposes. These are
6789 * often given in string form. Eg, "10.0.0.0/8", or "fe80::/10".
6794 * SECTION:ginetsocketaddress
6795 * @short_description: Internet GSocketAddress
6796 * @include: gio/gio.h
6798 * An IPv4 or IPv6 socket address; that is, the combination of a
6799 * #GInetAddress and a port number.
6805 * @short_description: Failable object initialization interface
6806 * @include: gio/gio.h
6807 * @see_also: #GAsyncInitable
6809 * #GInitable is implemented by objects that can fail during
6810 * initialization. If an object implements this interface then
6811 * it must be initialized as the first thing after construction,
6812 * either via g_initable_init() or g_async_initable_init_async()
6813 * (the latter is only available if it also implements #GAsyncInitable).
6815 * If the object is not initialized, or initialization returns with an
6816 * error, then all operations on the object except g_object_ref() and
6817 * g_object_unref() are considered to be invalid, and have undefined
6818 * behaviour. They will often fail with g_critical() or g_warning(), but
6819 * this must not be relied on.
6821 * Users of objects implementing this are not intended to use
6822 * the interface method directly, instead it will be used automatically
6823 * in various ways. For C applications you generally just call
6824 * g_initable_new() directly, or indirectly via a foo_thing_new() wrapper.
6825 * This will call g_initable_init() under the cover, returning %NULL and
6826 * setting a #GError on failure (at which point the instance is
6829 * For bindings in languages where the native constructor supports
6830 * exceptions the binding could check for objects implemention %GInitable
6831 * during normal construction and automatically initialize them, throwing
6832 * an exception on failure.
6837 * SECTION:ginputstream
6838 * @short_description: Base class for implementing streaming input
6839 * @include: gio/gio.h
6841 * #GInputStream has functions to read from a stream (g_input_stream_read()),
6842 * to close a stream (g_input_stream_close()) and to skip some content
6843 * (g_input_stream_skip()).
6845 * To copy the content of an input stream to an output stream without
6846 * manually handling the reads and writes, use g_output_stream_splice().
6848 * See the documentation for #GIOStream for details of thread safety of
6851 * All of these functions have async variants too.
6857 * @short_description: Error helper functions
6858 * @include: gio/gio.h
6860 * Contains helper functions for reporting errors to the user.
6866 * @short_description: Loadable GIO Modules
6867 * @include: gio/gio.h
6869 * Provides an interface and default functions for loading and unloading
6870 * modules. This is used internally to make GIO extensible, but can also
6871 * be used by others to implement module loading.
6876 * SECTION:gioscheduler
6877 * @short_description: I/O Scheduler
6878 * @include: gio/gio.h
6880 * As of GLib 2.36, #GIOScheduler is deprecated in favor of
6881 * #GThreadPool and #GTask.
6883 * Schedules asynchronous I/O operations. #GIOScheduler integrates
6884 * into the main event loop (#GMainLoop) and uses threads.
6890 * @short_description: Base class for implementing read/write streams
6891 * @include: gio/gio.h
6892 * @see_also: #GInputStream, #GOutputStream
6894 * GIOStream represents an object that has both read and write streams.
6895 * Generally the two streams act as separate input and output streams,
6896 * but they share some common resources and state. For instance, for
6897 * seekable streams, both streams may use the same position.
6899 * Examples of #GIOStream objects are #GSocketConnection, which represents
6900 * a two-way network connection; and #GFileIOStream, which represents a
6901 * file handle opened in read-write mode.
6903 * To do the actual reading and writing you need to get the substreams
6904 * with g_io_stream_get_input_stream() and g_io_stream_get_output_stream().
6906 * The #GIOStream object owns the input and the output streams, not the other
6907 * way around, so keeping the substreams alive will not keep the #GIOStream
6908 * object alive. If the #GIOStream object is freed it will be closed, thus
6909 * closing the substreams, so even if the substreams stay alive they will
6910 * always return %G_IO_ERROR_CLOSED for all operations.
6912 * To close a stream use g_io_stream_close() which will close the common
6913 * stream object and also the individual substreams. You can also close
6914 * the substreams themselves. In most cases this only marks the
6915 * substream as closed, so further I/O on it fails but common state in the
6916 * #GIOStream may still be open. However, some streams may support
6917 * "half-closed" states where one direction of the stream is actually shut down.
6919 * Operations on #GIOStreams cannot be started while another operation on the
6920 * #GIOStream or its substreams is in progress. Specifically, an application can
6921 * read from the #GInputStream and write to the #GOutputStream simultaneously
6922 * (either in separate threads, or as asynchronous operations in the same
6923 * thread), but an application cannot start any #GIOStream operation while there
6924 * is a #GIOStream, #GInputStream or #GOutputStream operation in progress, and
6925 * an application can’t start any #GInputStream or #GOutputStream operation
6926 * while there is a #GIOStream operation in progress.
6928 * This is a product of individual stream operations being associated with a
6929 * given #GMainContext (the thread-default context at the time the operation was
6930 * started), rather than entire streams being associated with a single
6933 * GIO may run operations on #GIOStreams from other (worker) threads, and this
6934 * may be exposed to application code in the behaviour of wrapper streams, such
6935 * as #GBufferedInputStream or #GTlsConnection. With such wrapper APIs,
6936 * application code may only run operations on the base (wrapped) stream when
6937 * the wrapper stream is idle. Note that the semantics of such operations may
6938 * not be well-defined due to the state the wrapper stream leaves the base
6939 * stream in (though they are guaranteed not to crash).
6946 * SECTION:glistmodel
6947 * @title: GListModel
6948 * @short_description: An interface describing a dynamic list of objects
6949 * @include: gio/gio.h
6950 * @see_also: #GListStore
6952 * #GListModel is an interface that represents a mutable list of
6953 * #GObjects. Its main intention is as a model for various widgets in
6954 * user interfaces, such as list views, but it can also be used as a
6955 * convenient method of returning lists of data, with support for
6958 * Each object in the list may also report changes in itself via some
6959 * mechanism (normally the #GObject::notify signal). Taken together
6960 * with the #GListModel::items-changed signal, this provides for a list
6961 * that can change its membership, and in which the members can change
6962 * their individual properties.
6964 * A good example would be the list of visible wireless network access
6965 * points, where each access point can report dynamic properties such as
6968 * It is important to note that the #GListModel itself does not report
6969 * changes to the individual items. It only reports changes to the list
6970 * membership. If you want to observe changes to the objects themselves
6971 * then you need to connect signals to the objects that you are
6974 * All items in a #GListModel are of (or derived from) the same type.
6975 * g_list_model_get_item_type() returns that type. The type may be an
6976 * interface, in which case all objects in the list must implement it.
6978 * The semantics are close to that of an array:
6979 * g_list_model_get_n_items() returns the number of items in the list and
6980 * g_list_model_get_item() returns an item at a (0-based) position. In
6981 * order to allow implementations to calculate the list length lazily,
6982 * you can also iterate over items: starting from 0, repeatedly call
6983 * g_list_model_get_item() until it returns %NULL.
6985 * An implementation may create objects lazily, but must take care to
6986 * return the same object for a given position until all references to
6989 * On the other side, a consumer is expected only to hold references on
6990 * objects that are currently "user visible", in order to faciliate the
6991 * maximum level of laziness in the implementation of the list and to
6992 * reduce the required number of signal connections at a given time.
6994 * This interface is intended only to be used from a single thread. The
6995 * thread in which it is appropriate to use it depends on the particular
6996 * implementation, but typically it will be from the thread that owns
6997 * the [thread-default main context][g-main-context-push-thread-default]
6998 * in effect at the time that the model was created.
7003 * SECTION:gliststore
7004 * @title: GListStore
7005 * @short_description: A simple implementation of #GListModel
7006 * @include: gio/gio.h
7008 * #GListStore is a simple implementation of #GListModel that stores all
7011 * It provides insertions, deletions, and lookups in logarithmic time
7012 * with a fast path for the common case of iterating the list linearly.
7017 * SECTION:gloadableicon
7018 * @short_description: Loadable Icons
7019 * @include: gio/gio.h
7020 * @see_also: #GIcon, #GThemedIcon
7022 * Extends the #GIcon interface and adds the ability to
7023 * load icons from streams.
7028 * SECTION:gmemoryinputstream
7029 * @short_description: Streaming input operations on memory chunks
7030 * @include: gio/gio.h
7031 * @see_also: #GMemoryOutputStream
7033 * #GMemoryInputStream is a class for using arbitrary
7034 * memory chunks as input for GIO streaming input operations.
7036 * As of GLib 2.34, #GMemoryInputStream implements
7037 * #GPollableInputStream.
7042 * SECTION:gmemoryoutputstream
7043 * @short_description: Streaming output operations on memory chunks
7044 * @include: gio/gio.h
7045 * @see_also: #GMemoryInputStream
7047 * #GMemoryOutputStream is a class for using arbitrary
7048 * memory chunks as output for GIO streaming output operations.
7050 * As of GLib 2.34, #GMemoryOutputStream trivially implements
7051 * #GPollableOutputStream: it always polls as ready.
7058 * @short_description: A simple implementation of GMenuModel
7059 * @include: gio/gio.h
7061 * #GMenu is a simple implementation of #GMenuModel.
7062 * You populate a #GMenu by adding #GMenuItem instances to it.
7064 * There are some convenience functions to allow you to directly
7065 * add items (avoiding #GMenuItem) for the common cases. To add
7066 * a regular item, use g_menu_insert(). To add a section, use
7067 * g_menu_insert_section(). To add a submenu, use
7068 * g_menu_insert_submenu().
7073 * SECTION:gmenuexporter
7074 * @title: GMenuModel exporter
7075 * @short_description: Export GMenuModels on D-Bus
7076 * @include: gio/gio.h
7077 * @see_also: #GMenuModel, #GDBusMenuModel
7079 * These functions support exporting a #GMenuModel on D-Bus.
7080 * The D-Bus interface that is used is a private implementation
7083 * To access an exported #GMenuModel remotely, use
7084 * g_dbus_menu_model_get() to obtain a #GDBusMenuModel.
7089 * SECTION:gmenumodel
7090 * @title: GMenuModel
7091 * @short_description: An abstract class representing the contents of a menu
7092 * @include: gio/gio.h
7093 * @see_also: #GActionGroup
7095 * #GMenuModel represents the contents of a menu -- an ordered list of
7096 * menu items. The items are associated with actions, which can be
7097 * activated through them. Items can be grouped in sections, and may
7098 * have submenus associated with them. Both items and sections usually
7099 * have some representation data, such as labels or icons. The type of
7100 * the associated action (ie whether it is stateful, and what kind of
7101 * state it has) can influence the representation of the item.
7103 * The conceptual model of menus in #GMenuModel is hierarchical:
7104 * sections and submenus are again represented by #GMenuModels.
7105 * Menus themselves do not define their own roles. Rather, the role
7106 * of a particular #GMenuModel is defined by the item that references
7107 * it (or, in the case of the 'root' menu, is defined by the context
7108 * in which it is used).
7110 * As an example, consider the visible portions of this menu:
7112 * ## An example menu # {#menu-example}
7114 * ![](menu-example.png)
7116 * There are 8 "menus" visible in the screenshot: one menubar, two
7117 * submenus and 5 sections:
7119 * - the toplevel menubar (containing 4 items)
7120 * - the View submenu (containing 3 sections)
7121 * - the first section of the View submenu (containing 2 items)
7122 * - the second section of the View submenu (containing 1 item)
7123 * - the final section of the View submenu (containing 1 item)
7124 * - the Highlight Mode submenu (containing 2 sections)
7125 * - the Sources section (containing 2 items)
7126 * - the Markup section (containing 2 items)
7128 * The [example][menu-model] illustrates the conceptual connection between
7129 * these 8 menus. Each large block in the figure represents a menu and the
7130 * smaller blocks within the large block represent items in that menu. Some
7131 * items contain references to other menus.
7133 * ## A menu example # {#menu-model}
7135 * ![](menu-model.png)
7137 * Notice that the separators visible in the [example][menu-example]
7138 * appear nowhere in the [menu model][menu-model]. This is because
7139 * separators are not explicitly represented in the menu model. Instead,
7140 * a separator is inserted between any two non-empty sections of a menu.
7141 * Section items can have labels just like any other item. In that case,
7142 * a display system may show a section header instead of a separator.
7144 * The motivation for this abstract model of application controls is
7145 * that modern user interfaces tend to make these controls available
7146 * outside the application. Examples include global menus, jumplists,
7147 * dash boards, etc. To support such uses, it is necessary to 'export'
7148 * information about actions and their representation in menus, which
7149 * is exactly what the [GActionGroup exporter][gio-GActionGroup-exporter]
7150 * and the [GMenuModel exporter][gio-GMenuModel-exporter] do for
7151 * #GActionGroup and #GMenuModel. The client-side counterparts to
7152 * make use of the exported information are #GDBusActionGroup and
7155 * The API of #GMenuModel is very generic, with iterators for the
7156 * attributes and links of an item, see g_menu_model_iterate_item_attributes()
7157 * and g_menu_model_iterate_item_links(). The 'standard' attributes and
7158 * link types have predefined names: %G_MENU_ATTRIBUTE_LABEL,
7159 * %G_MENU_ATTRIBUTE_ACTION, %G_MENU_ATTRIBUTE_TARGET, %G_MENU_LINK_SECTION
7160 * and %G_MENU_LINK_SUBMENU.
7162 * Items in a #GMenuModel represent active controls if they refer to
7163 * an action that can get activated when the user interacts with the
7164 * menu item. The reference to the action is encoded by the string id
7165 * in the %G_MENU_ATTRIBUTE_ACTION attribute. An action id uniquely
7166 * identifies an action in an action group. Which action group(s) provide
7167 * actions depends on the context in which the menu model is used.
7168 * E.g. when the model is exported as the application menu of a
7169 * #GtkApplication, actions can be application-wide or window-specific
7170 * (and thus come from two different action groups). By convention, the
7171 * application-wide actions have names that start with "app.", while the
7172 * names of window-specific actions start with "win.".
7174 * While a wide variety of stateful actions is possible, the following
7175 * is the minimum that is expected to be supported by all users of exported
7177 * - an action with no parameter type and no state
7178 * - an action with no parameter type and boolean state
7179 * - an action with string parameter type and string state
7183 * A stateless action typically corresponds to an ordinary menu item.
7185 * Selecting such a menu item will activate the action (with no parameter).
7189 * An action with a boolean state will most typically be used with a "toggle"
7190 * or "switch" menu item. The state can be set directly, but activating the
7191 * action (with no parameter) results in the state being toggled.
7193 * Selecting a toggle menu item will activate the action. The menu item should
7194 * be rendered as "checked" when the state is true.
7196 * ## String Parameter and State
7198 * Actions with string parameters and state will most typically be used to
7199 * represent an enumerated choice over the items available for a group of
7200 * radio menu items. Activating the action with a string parameter is
7201 * equivalent to setting that parameter as the state.
7203 * Radio menu items, in addition to being associated with the action, will
7204 * have a target value. Selecting that menu item will result in activation
7205 * of the action with the target value as the parameter. The menu item should
7206 * be rendered as "selected" when the state of the action is equal to the
7207 * target value of the menu item.
7213 * @short_description: Mount management
7214 * @include: gio/gio.h
7215 * @see_also: GVolume, GUnixMountEntry, GUnixMountPoint
7217 * The #GMount interface represents user-visible mounts. Note, when
7218 * porting from GnomeVFS, #GMount is the moral equivalent of #GnomeVFSVolume.
7220 * #GMount is a "mounted" filesystem that you can access. Mounted is in
7221 * quotes because it's not the same as a unix mount, it might be a gvfs
7222 * mount, but you can still access the files on it if you use GIO. Might or
7223 * might not be related to a volume object.
7225 * Unmounting a #GMount instance is an asynchronous operation. For
7226 * more information about asynchronous operations, see #GAsyncResult
7227 * and #GTask. To unmount a #GMount instance, first call
7228 * g_mount_unmount_with_operation() with (at least) the #GMount instance and a
7229 * #GAsyncReadyCallback. The callback will be fired when the
7230 * operation has resolved (either with success or failure), and a
7231 * #GAsyncReady structure will be passed to the callback. That
7232 * callback should then call g_mount_unmount_with_operation_finish() with the #GMount
7233 * and the #GAsyncReady data to see if the operation was completed
7234 * successfully. If an @error is present when g_mount_unmount_with_operation_finish()
7235 * is called, then it will be filled with any error information.
7240 * SECTION:gmountoperation
7241 * @short_description: Object used for authentication and user interaction
7242 * @include: gio/gio.h
7244 * #GMountOperation provides a mechanism for interacting with the user.
7245 * It can be used for authenticating mountable operations, such as loop
7246 * mounting files, hard drive partitions or server locations. It can
7247 * also be used to ask the user questions or show a list of applications
7248 * preventing unmount or eject operations from completing.
7250 * Note that #GMountOperation is used for more than just #GMount
7251 * objects – for example it is also used in g_drive_start() and
7254 * Users should instantiate a subclass of this that implements all the
7255 * various callbacks to show the required dialogs, such as
7256 * #GtkMountOperation. If no user interaction is desired (for example
7257 * when automounting filesystems at login time), usually %NULL can be
7258 * passed, see each method taking a #GMountOperation for details.
7263 * SECTION:gnativesocketaddress
7264 * @short_description: Native GSocketAddress
7265 * @include: gio/gio.h
7267 * An socket address of some unknown native type.
7272 * SECTION:gnetworkaddress
7273 * @short_description: A GSocketConnectable for resolving hostnames
7274 * @include: gio/gio.h
7276 * #GNetworkAddress provides an easy way to resolve a hostname and
7277 * then attempt to connect to that host, handling the possibility of
7278 * multiple IP addresses and multiple address families.
7280 * See #GSocketConnectable for and example of using the connectable
7286 * SECTION:gnetworking
7287 * @title: gnetworking.h
7288 * @short_description: System networking includes
7289 * @include: gio/gnetworking.h
7291 * The `<gio/gnetworking.h>` header can be included to get
7292 * various low-level networking-related system headers, automatically
7293 * taking care of certain portability issues for you.
7295 * This can be used, for example, if you want to call setsockopt()
7298 * Note that while WinSock has many of the same APIs as the
7299 * traditional UNIX socket API, most of them behave at least slightly
7300 * differently (particularly with respect to error handling). If you
7301 * want your code to work under both UNIX and Windows, you will need
7302 * to take these differences into account.
7304 * Also, under GNU libc, certain non-portable functions are only visible
7305 * in the headers if you define %_GNU_SOURCE before including them. Note
7306 * that this symbol must be defined before including any headers, or it
7307 * may not take effect.
7312 * SECTION:gnetworkmonitor
7313 * @title: GNetworkMonitor
7314 * @short_description: Network status monitor
7315 * @include: gio/gio.h
7317 * #GNetworkMonitor provides an easy-to-use cross-platform API
7318 * for monitoring network connectivity. On Linux, the implementation
7319 * is based on the kernel's netlink interface.
7324 * SECTION:gnetworkservice
7325 * @short_description: A GSocketConnectable for resolving SRV records
7326 * @include: gio/gio.h
7328 * Like #GNetworkAddress does with hostnames, #GNetworkService
7329 * provides an easy way to resolve a SRV record, and then attempt to
7330 * connect to one of the hosts that implements that service, handling
7331 * service priority/weighting, multiple IP addresses, and multiple
7334 * See #GSrvTarget for more information about SRV records, and see
7335 * #GSocketConnectable for and example of using the connectable
7341 * SECTION:gnotification
7342 * @short_description: User Notifications (pop up messages)
7343 * @include: gio/gio.h
7345 * #GNotification is a mechanism for creating a notification to be shown
7346 * to the user -- typically as a pop-up notification presented by the
7347 * desktop environment shell.
7349 * The key difference between #GNotification and other similar APIs is
7350 * that, if supported by the desktop environment, notifications sent
7351 * with #GNotification will persist after the application has exited,
7352 * and even across system reboots.
7354 * Since the user may click on a notification while the application is
7355 * not running, applications using #GNotification should be able to be
7356 * started as a D-Bus service, using #GApplication.
7358 * User interaction with a notification (either the default action, or
7359 * buttons) must be associated with actions on the application (ie:
7360 * "app." actions). It is not possible to route user interaction
7361 * through the notification itself, because the object will not exist if
7362 * the application is autostarted as a result of a notification being
7365 * A notification can be sent with g_application_send_notification().
7372 * SECTION:goutputstream
7373 * @short_description: Base class for implementing streaming output
7374 * @include: gio/gio.h
7376 * #GOutputStream has functions to write to a stream (g_output_stream_write()),
7377 * to close a stream (g_output_stream_close()) and to flush pending writes
7378 * (g_output_stream_flush()).
7380 * To copy the content of an input stream to an output stream without
7381 * manually handling the reads and writes, use g_output_stream_splice().
7383 * See the documentation for #GIOStream for details of thread safety of
7386 * All of these functions have async variants too.
7391 * SECTION:gpermission
7392 * @title: GPermission
7393 * @short_description: An object representing the permission
7394 * to perform a certain action
7395 * @include: gio/gio.h
7397 * A #GPermission represents the status of the caller's permission to
7398 * perform a certain action.
7400 * You can query if the action is currently allowed and if it is
7401 * possible to acquire the permission so that the action will be allowed
7404 * There is also an API to actually acquire the permission and one to
7407 * As an example, a #GPermission might represent the ability for the
7408 * user to write to a #GSettings object. This #GPermission object could
7409 * then be used to decide if it is appropriate to show a "Click here to
7410 * unlock" button in a dialog and to provide the mechanism to invoke
7411 * when that button is clicked.
7416 * SECTION:gpollableinputstream
7417 * @short_description: Interface for pollable input streams
7418 * @include: gio/gio.h
7419 * @see_also: #GInputStream, #GPollableOutputStream, #GFileDescriptorBased
7421 * #GPollableInputStream is implemented by #GInputStreams that
7422 * can be polled for readiness to read. This can be used when
7423 * interfacing with a non-GIO API that expects
7424 * UNIX-file-descriptor-style asynchronous I/O rather than GIO-style.
7431 * SECTION:gpollableoutputstream
7432 * @short_description: Interface for pollable output streams
7433 * @include: gio/gio.h
7434 * @see_also: #GOutputStream, #GFileDescriptorBased, #GPollableInputStream
7436 * #GPollableOutputStream is implemented by #GOutputStreams that
7437 * can be polled for readiness to write. This can be used when
7438 * interfacing with a non-GIO API that expects
7439 * UNIX-file-descriptor-style asynchronous I/O rather than GIO-style.
7446 * SECTION:gpollableutils
7447 * @short_description: Utilities for pollable streams
7448 * @include: gio/gio.h
7450 * Utility functions for #GPollableInputStream and
7451 * #GPollableOutputStream implementations.
7456 * SECTION:gpropertyaction
7457 * @title: GPropertyAction
7458 * @short_description: A GAction reflecting a GObject property
7459 * @include: gio/gio.h
7461 * A #GPropertyAction is a way to get a #GAction with a state value
7462 * reflecting and controlling the value of a #GObject property.
7464 * The state of the action will correspond to the value of the property.
7465 * Changing it will change the property (assuming the requested value
7466 * matches the requirements as specified in the #GParamSpec).
7468 * Only the most common types are presently supported. Booleans are
7469 * mapped to booleans, strings to strings, signed/unsigned integers to
7470 * int32/uint32 and floats and doubles to doubles.
7472 * If the property is an enum then the state will be string-typed and
7473 * conversion will automatically be performed between the enum value and
7474 * "nick" string as per the #GEnumValue table.
7476 * Flags types are not currently supported.
7478 * Properties of object types, boxed types and pointer types are not
7479 * supported and probably never will be.
7481 * Properties of #GVariant types are not currently supported.
7483 * If the property is boolean-valued then the action will have a NULL
7484 * parameter type, and activating the action (with no parameter) will
7485 * toggle the value of the property.
7487 * In all other cases, the parameter type will correspond to the type of
7490 * The general idea here is to reduce the number of locations where a
7491 * particular piece of state is kept (and therefore has to be synchronised
7492 * between). #GPropertyAction does not have a separate state that is kept
7493 * in sync with the property value -- its state is the property value.
7495 * For example, it might be useful to create a #GAction corresponding to
7496 * the "visible-child-name" property of a #GtkStack so that the current
7497 * page can be switched from a menu. The active radio indication in the
7498 * menu is then directly determined from the active page of the
7501 * An anti-example would be binding the "active-id" property on a
7502 * #GtkComboBox. This is because the state of the combobox itself is
7503 * probably uninteresting and is actually being used to control
7506 * Another anti-example would be to bind to the "visible-child-name"
7507 * property of a #GtkStack if this value is actually stored in
7508 * #GSettings. In that case, the real source of the value is
7509 * #GSettings. If you want a #GAction to control a setting stored in
7510 * #GSettings, see g_settings_create_action() instead, and possibly
7511 * combine its use with g_settings_bind().
7519 * @short_description: Interface for proxy handling
7520 * @include: gio/gio.h
7522 * A #GProxy handles connecting to a remote host via a given type of
7523 * proxy server. It is implemented by the 'gio-proxy' extension point.
7524 * The extensions are named after their proxy protocol name. As an
7525 * example, a SOCKS5 proxy implementation can be retrieved with the
7526 * name 'socks5' using the function
7527 * g_io_extension_point_get_extension_by_name().
7534 * SECTION:gproxyaddress
7535 * @short_description: An internet address with proxy information
7536 * @include: gio/gio.h
7538 * Support for proxied #GInetSocketAddress.
7543 * SECTION:gproxyresolver
7544 * @short_description: Asynchronous and cancellable network proxy resolver
7545 * @include: gio/gio.h
7547 * #GProxyResolver provides synchronous and asynchronous network proxy
7548 * resolution. #GProxyResolver is used within #GSocketClient through
7549 * the method g_socket_connectable_proxy_enumerate().
7554 * SECTION:gremoteactiongroup
7555 * @title: GRemoteActionGroup
7556 * @short_description: A GActionGroup that interacts with other processes
7557 * @include: gio/gio.h
7559 * The GRemoteActionGroup interface is implemented by #GActionGroup
7560 * instances that either transmit action invocations to other processes
7561 * or receive action invocations in the local process from other
7564 * The interface has `_full` variants of the two
7565 * methods on #GActionGroup used to activate actions:
7566 * g_action_group_activate_action() and
7567 * g_action_group_change_action_state(). These variants allow a
7568 * "platform data" #GVariant to be specified: a dictionary providing
7569 * context for the action invocation (for example: timestamps, startup
7570 * notification IDs, etc).
7572 * #GDBusActionGroup implements #GRemoteActionGroup. This provides a
7573 * mechanism to send platform data for action invocations over D-Bus.
7575 * Additionally, g_dbus_connection_export_action_group() will check if
7576 * the exported #GActionGroup implements #GRemoteActionGroup and use the
7577 * `_full` variants of the calls if available. This
7578 * provides a mechanism by which to receive platform data for action
7579 * invocations that arrive by way of D-Bus.
7587 * @short_description: Asynchronous and cancellable DNS resolver
7588 * @include: gio/gio.h
7590 * #GResolver provides cancellable synchronous and asynchronous DNS
7591 * resolution, for hostnames (g_resolver_lookup_by_address(),
7592 * g_resolver_lookup_by_name() and their async variants) and SRV
7593 * (service) records (g_resolver_lookup_service()).
7595 * #GNetworkAddress and #GNetworkService provide wrappers around
7596 * #GResolver functionality that also implement #GSocketConnectable,
7597 * making it easy to connect to a remote host/service.
7603 * @short_description: Resource framework
7604 * @include: gio/gio.h
7606 * Applications and libraries often contain binary or textual data that is
7607 * really part of the application, rather than user data. For instance
7608 * #GtkBuilder .ui files, splashscreen images, GMenu markup XML, CSS files,
7609 * icons, etc. These are often shipped as files in `$datadir/appname`, or
7610 * manually included as literal strings in the code.
7612 * The #GResource API and the [glib-compile-resources][glib-compile-resources] program
7613 * provide a convenient and efficient alternative to this which has some nice properties. You
7614 * maintain the files as normal files, so its easy to edit them, but during the build the files
7615 * are combined into a binary bundle that is linked into the executable. This means that loading
7616 * the resource files are efficient (as they are already in memory, shared with other instances) and
7617 * simple (no need to check for things like I/O errors or locate the files in the filesystem). It
7618 * also makes it easier to create relocatable applications.
7620 * Resource files can also be marked as compressed. Such files will be included in the resource bundle
7621 * in a compressed form, but will be automatically uncompressed when the resource is used. This
7622 * is very useful e.g. for larger text files that are parsed once (or rarely) and then thrown away.
7624 * Resource files can also be marked to be preprocessed, by setting the value of the
7625 * `preprocess` attribute to a comma-separated list of preprocessing options.
7626 * The only options currently supported are:
7628 * `xml-stripblanks` which will use the xmllint command
7629 * to strip ignorable whitespace from the XML file. For this to work,
7630 * the `XMLLINT` environment variable must be set to the full path to
7631 * the xmllint executable, or xmllint must be in the `PATH`; otherwise
7632 * the preprocessing step is skipped.
7634 * `to-pixdata` which will use the gdk-pixbuf-pixdata command to convert
7635 * images to the GdkPixdata format, which allows you to create pixbufs directly using the data inside
7636 * the resource file, rather than an (uncompressed) copy if it. For this, the gdk-pixbuf-pixdata
7637 * program must be in the PATH, or the `GDK_PIXBUF_PIXDATA` environment variable must be
7638 * set to the full path to the gdk-pixbuf-pixdata executable; otherwise the resource compiler will
7641 * Resource bundles are created by the [glib-compile-resources][glib-compile-resources] program
7642 * which takes an XML file that describes the bundle, and a set of files that the XML references. These
7643 * are combined into a binary resource bundle.
7645 * An example resource description:
7647 * <?xml version="1.0" encoding="UTF-8"?>
7649 * <gresource prefix="/org/gtk/Example">
7650 * <file>data/splashscreen.png</file>
7651 * <file compressed="true">dialog.ui</file>
7652 * <file preprocess="xml-stripblanks">menumarkup.xml</file>
7657 * This will create a resource bundle with the following files:
7659 * /org/gtk/Example/data/splashscreen.png
7660 * /org/gtk/Example/dialog.ui
7661 * /org/gtk/Example/menumarkup.xml
7664 * Note that all resources in the process share the same namespace, so use Java-style
7665 * path prefixes (like in the above example) to avoid conflicts.
7667 * You can then use [glib-compile-resources][glib-compile-resources] to compile the XML to a
7668 * binary bundle that you can load with g_resource_load(). However, its more common to use the --generate-source and
7669 * --generate-header arguments to create a source file and header to link directly into your application.
7670 * This will generate `get_resource()`, `register_resource()` and
7671 * `unregister_resource()` functions, prefixed by the `--c-name` argument passed
7672 * to [glib-compile-resources][glib-compile-resources]. `get_resource()` returns
7673 * the generated #GResource object. The register and unregister functions
7674 * register the resource so its files can be accessed using
7675 * g_resources_lookup_data().
7677 * Once a #GResource has been created and registered all the data in it can be accessed globally in the process by
7678 * using API calls like g_resources_open_stream() to stream the data or g_resources_lookup_data() to get a direct pointer
7679 * to the data. You can also use URIs like "resource:///org/gtk/Example/data/splashscreen.png" with #GFile to access
7680 * the resource data.
7682 * There are two forms of the generated source, the default version uses the compiler support for constructor
7683 * and destructor functions (where available) to automatically create and register the #GResource on startup
7684 * or library load time. If you pass --manual-register two functions to register/unregister the resource is instead
7685 * created. This requires an explicit initialization call in your application/library, but it works on all platforms,
7686 * even on the minor ones where this is not available. (Constructor support is available for at least Win32, Mac OS and Linux.)
7688 * Note that resource data can point directly into the data segment of e.g. a library, so if you are unloading libraries
7689 * during runtime you need to be very careful with keeping around pointers to data from a resource, as this goes away
7690 * when the library is unloaded. However, in practice this is not generally a problem, since most resource accesses
7691 * is for your own resources, and resource data is often used once, during parsing, and then released.
7693 * When debugging a program or testing a change to an installed version, it is often useful to be able to
7694 * replace resources in the program or library, without recompiling, for debugging or quick hacking and testing
7697 * Since GLib 2.50, it is possible to use the `G_RESOURCE_OVERLAYS` environment variable to selectively overlay
7698 * resources with replacements from the filesystem. It is a colon-separated list of substitutions to perform
7699 * during resource lookups.
7701 * A substitution has the form
7704 * /org/gtk/libgtk=/home/desrt/gtk-overlay
7707 * The part before the `=` is the resource subpath for which the overlay applies. The part after is a
7708 * filesystem path which contains files and subdirectories as you would like to be loaded as resources with the
7711 * In the example above, if an application tried to load a resource with the resource path
7712 * `/org/gtk/libgtk/ui/gtkdialog.ui` then GResource would check the filesystem path
7713 * `/home/desrt/gtk-overlay/ui/gtkdialog.ui`. If a file was found there, it would be used instead. This is an
7714 * overlay, not an outright replacement, which means that if a file is not found at that path, the built-in
7715 * version will be used instead. Whiteouts are not currently supported.
7717 * Substitutions must start with a slash, and must not contain a trailing slash before the '='. The path after
7718 * the slash should ideally be absolute, but this is not strictly required. It is possible to overlay the
7719 * location of a single resource with an individual file.
7727 * @short_description: Stream seeking interface
7728 * @include: gio/gio.h
7729 * @see_also: #GInputStream, #GOutputStream
7731 * #GSeekable is implemented by streams (implementations of
7732 * #GInputStream or #GOutputStream) that support seeking.
7734 * Seekable streams largely fall into two categories: resizable and
7737 * #GSeekable on fixed-sized streams is approximately the same as POSIX
7738 * lseek() on a block device (for example: attmepting to seek past the
7739 * end of the device is an error). Fixed streams typically cannot be
7742 * #GSeekable on resizable streams is approximately the same as POSIX
7743 * lseek() on a normal file. Seeking past the end and writing data will
7744 * usually cause the stream to resize by introducing zero bytes.
7750 * @short_description: High-level API for application settings
7751 * @include: gio/gio.h
7753 * The #GSettings class provides a convenient API for storing and retrieving
7754 * application settings.
7756 * Reads and writes can be considered to be non-blocking. Reading
7757 * settings with #GSettings is typically extremely fast: on
7758 * approximately the same order of magnitude (but slower than) a
7759 * #GHashTable lookup. Writing settings is also extremely fast in terms
7760 * of time to return to your application, but can be extremely expensive
7761 * for other threads and other processes. Many settings backends
7762 * (including dconf) have lazy initialisation which means in the common
7763 * case of the user using their computer without modifying any settings
7764 * a lot of work can be avoided. For dconf, the D-Bus service doesn't
7765 * even need to be started in this case. For this reason, you should
7766 * only ever modify #GSettings keys in response to explicit user action.
7767 * Particular care should be paid to ensure that modifications are not
7768 * made during startup -- for example, when setting the initial value
7769 * of preferences widgets. The built-in g_settings_bind() functionality
7770 * is careful not to write settings in response to notify signals as a
7771 * result of modifications that it makes to widgets.
7773 * When creating a GSettings instance, you have to specify a schema
7774 * that describes the keys in your settings and their types and default
7775 * values, as well as some other information.
7777 * Normally, a schema has as fixed path that determines where the settings
7778 * are stored in the conceptual global tree of settings. However, schemas
7779 * can also be '[relocatable][gsettings-relocatable]', i.e. not equipped with
7780 * a fixed path. This is
7781 * useful e.g. when the schema describes an 'account', and you want to be
7782 * able to store a arbitrary number of accounts.
7784 * Paths must start with and end with a forward slash character ('/')
7785 * and must not contain two sequential slash characters. Paths should
7786 * be chosen based on a domain name associated with the program or
7787 * library to which the settings belong. Examples of paths are
7788 * "/org/gtk/settings/file-chooser/" and "/ca/desrt/dconf-editor/".
7789 * Paths should not start with "/apps/", "/desktop/" or "/system/" as
7790 * they often did in GConf.
7792 * Unlike other configuration systems (like GConf), GSettings does not
7793 * restrict keys to basic types like strings and numbers. GSettings stores
7794 * values as #GVariant, and allows any #GVariantType for keys. Key names
7795 * are restricted to lowercase characters, numbers and '-'. Furthermore,
7796 * the names must begin with a lowercase character, must not end
7797 * with a '-', and must not contain consecutive dashes.
7799 * Similar to GConf, the default values in GSettings schemas can be
7800 * localized, but the localized values are stored in gettext catalogs
7801 * and looked up with the domain that is specified in the
7802 * `gettext-domain` attribute of the <schemalist> or <schema>
7803 * elements and the category that is specified in the `l10n` attribute of
7804 * the <default> element. The string which is translated includes all text in
7805 * the <default> element, including any surrounding quotation marks.
7807 * The `l10n` attribute must be set to `messages` or `time`, and sets the
7808 * [locale category for
7809 * translation](https://www.gnu.org/software/gettext/manual/html_node/Aspects.html#index-locale-categories-1).
7810 * The `messages` category should be used by default; use `time` for
7811 * translatable date or time formats. A translation comment can be added as an
7812 * XML comment immediately above the <default> element — it is recommended to
7813 * add these comments to aid translators understand the meaning and
7814 * implications of the default value. An optional translation `context`
7815 * attribute can be set on the <default> element to disambiguate multiple
7816 * defaults which use the same string.
7820 * <!-- Translators: A list of words which are not allowed to be typed, in
7821 * GVariant serialization syntax.
7822 * See: https://developer.gnome.org/glib/stable/gvariant-text.html -->
7823 * <default l10n='messages' context='Banned words'>['bad', 'words']</default>
7826 * Translations of default values must remain syntactically valid serialized
7827 * #GVariants (e.g. retaining any surrounding quotation marks) or runtime
7828 * errors will occur.
7830 * GSettings uses schemas in a compact binary form that is created
7831 * by the [glib-compile-schemas][glib-compile-schemas]
7832 * utility. The input is a schema description in an XML format.
7834 * A DTD for the gschema XML format can be found here:
7835 * [gschema.dtd](https://git.gnome.org/browse/glib/tree/gio/gschema.dtd)
7837 * The [glib-compile-schemas][glib-compile-schemas] tool expects schema
7838 * files to have the extension `.gschema.xml`.
7840 * At runtime, schemas are identified by their id (as specified in the
7841 * id attribute of the <schema> element). The convention for schema
7842 * ids is to use a dotted name, similar in style to a D-Bus bus name,
7843 * e.g. "org.gnome.SessionManager". In particular, if the settings are
7844 * for a specific service that owns a D-Bus bus name, the D-Bus bus name
7845 * and schema id should match. For schemas which deal with settings not
7846 * associated with one named application, the id should not use
7847 * StudlyCaps, e.g. "org.gnome.font-rendering".
7849 * In addition to #GVariant types, keys can have types that have
7850 * enumerated types. These can be described by a <choice>,
7851 * <enum> or <flags> element, as seen in the
7852 * [example][schema-enumerated]. The underlying type of such a key
7853 * is string, but you can use g_settings_get_enum(), g_settings_set_enum(),
7854 * g_settings_get_flags(), g_settings_set_flags() access the numeric values
7855 * corresponding to the string value of enum and flags keys.
7857 * An example for default value:
7860 * <schema id="org.gtk.Test" path="/org/gtk/Test/" gettext-domain="test">
7862 * <key name="greeting" type="s">
7863 * <default l10n="messages">"Hello, earthlings"</default>
7864 * <summary>A greeting</summary>
7866 * Greeting of the invading martians
7870 * <key name="box" type="(ii)">
7871 * <default>(20,30)</default>
7878 * An example for ranges, choices and enumerated types:
7882 * <enum id="org.gtk.Test.myenum">
7883 * <value nick="first" value="1"/>
7884 * <value nick="second" value="2"/>
7887 * <flags id="org.gtk.Test.myflags">
7888 * <value nick="flag1" value="1"/>
7889 * <value nick="flag2" value="2"/>
7890 * <value nick="flag3" value="4"/>
7893 * <schema id="org.gtk.Test">
7895 * <key name="key-with-range" type="i">
7896 * <range min="1" max="100"/>
7897 * <default>10</default>
7900 * <key name="key-with-choices" type="s">
7902 * <choice value='Elisabeth'/>
7903 * <choice value='Annabeth'/>
7904 * <choice value='Joe'/>
7907 * <alias value='Anna' target='Annabeth'/>
7908 * <alias value='Beth' target='Elisabeth'/>
7910 * <default>'Joe'</default>
7913 * <key name='enumerated-key' enum='org.gtk.Test.myenum'>
7914 * <default>'first'</default>
7917 * <key name='flags-key' flags='org.gtk.Test.myflags'>
7918 * <default>["flag1","flag2"]</default>
7924 * ## Vendor overrides
7926 * Default values are defined in the schemas that get installed by
7927 * an application. Sometimes, it is necessary for a vendor or distributor
7928 * to adjust these defaults. Since patching the XML source for the schema
7929 * is inconvenient and error-prone,
7930 * [glib-compile-schemas][glib-compile-schemas] reads so-called vendor
7931 * override' files. These are keyfiles in the same directory as the XML
7932 * schema sources which can override default values. The schema id serves
7933 * as the group name in the key file, and the values are expected in
7934 * serialized GVariant form, as in the following example:
7941 * glib-compile-schemas expects schema files to have the extension
7942 * `.gschema.override`.
7946 * A very convenient feature of GSettings lets you bind #GObject properties
7947 * directly to settings, using g_settings_bind(). Once a GObject property
7948 * has been bound to a setting, changes on either side are automatically
7949 * propagated to the other side. GSettings handles details like mapping
7950 * between GObject and GVariant types, and preventing infinite cycles.
7952 * This makes it very easy to hook up a preferences dialog to the
7953 * underlying settings. To make this even more convenient, GSettings
7954 * looks for a boolean property with the name "sensitivity" and
7955 * automatically binds it to the writability of the bound setting.
7956 * If this 'magic' gets in the way, it can be suppressed with the
7957 * #G_SETTINGS_BIND_NO_SENSITIVITY flag.
7959 * ## Relocatable schemas # {#gsettings-relocatable}
7961 * A relocatable schema is one with no `path` attribute specified on its
7962 * <schema> element. By using g_settings_new_with_path(), a #GSettings object
7963 * can be instantiated for a relocatable schema, assigning a path to the
7964 * instance. Paths passed to g_settings_new_with_path() will typically be
7965 * constructed dynamically from a constant prefix plus some form of instance
7966 * identifier; but they must still be valid GSettings paths. Paths could also
7967 * be constant and used with a globally installed schema originating from a
7968 * dependency library.
7970 * For example, a relocatable schema could be used to store geometry information
7971 * for different windows in an application. If the schema ID was
7972 * `org.foo.MyApp.Window`, it could be instantiated for paths
7973 * `/org/foo/MyApp/main/`, `/org/foo/MyApp/document-1/`,
7974 * `/org/foo/MyApp/document-2/`, etc. If any of the paths are well-known
7975 * they can be specified as <child> elements in the parent schema, e.g.:
7977 * <schema id="org.foo.MyApp" path="/org/foo/MyApp/">
7978 * <child name="main" schema="org.foo.MyApp.Window"/>
7982 * ## Build system integration # {#gsettings-build-system}
7984 * GSettings comes with autotools integration to simplify compiling and
7985 * installing schemas. To add GSettings support to an application, add the
7986 * following to your `configure.ac`:
7991 * In the appropriate `Makefile.am`, use the following snippet to compile and
7992 * install the named schema:
7994 * gsettings_SCHEMAS = org.foo.MyApp.gschema.xml
7995 * EXTRA_DIST = $(gsettings_SCHEMAS)
8000 * No changes are needed to the build system to mark a schema XML file for
8001 * translation. Assuming it sets the `gettext-domain` attribute, a schema may
8002 * be marked for translation by adding it to `POTFILES.in`, assuming gettext
8003 * 0.19 is in use (the preferred method for translation):
8005 * data/org.foo.MyApp.gschema.xml
8008 * Alternatively, if intltool 0.50.1 is in use:
8010 * [type: gettext/gsettings]data/org.foo.MyApp.gschema.xml
8013 * GSettings will use gettext to look up translations for the <summary> and
8014 * <description> elements, and also any <default> elements which have a `l10n`
8015 * attribute set. Translations must not be included in the `.gschema.xml` file
8016 * by the build system, for example by using intltool XML rules with a
8017 * `.gschema.xml.in` template.
8019 * If an enumerated type defined in a C header file is to be used in a GSettings
8020 * schema, it can either be defined manually using an <enum> element in the
8021 * schema XML, or it can be extracted automatically from the C header. This
8022 * approach is preferred, as it ensures the two representations are always
8023 * synchronised. To do so, add the following to the relevant `Makefile.am`:
8025 * gsettings_ENUM_NAMESPACE = org.foo.MyApp
8026 * gsettings_ENUM_FILES = my-app-enums.h my-app-misc.h
8029 * `gsettings_ENUM_NAMESPACE` specifies the schema namespace for the enum files,
8030 * which are specified in `gsettings_ENUM_FILES`. This will generate a
8031 * `org.foo.MyApp.enums.xml` file containing the extracted enums, which will be
8032 * automatically included in the schema compilation, install and uninstall
8033 * rules. It should not be committed to version control or included in
8039 * SECTION:gsettingsbackend
8040 * @title: GSettingsBackend
8041 * @short_description: Interface for settings backend implementations
8042 * @include: gio/gsettingsbackend.h
8043 * @see_also: #GSettings, #GIOExtensionPoint
8045 * The #GSettingsBackend interface defines a generic interface for
8046 * non-strictly-typed data that is stored in a hierarchy. To implement
8047 * an alternative storage backend for #GSettings, you need to implement
8048 * the #GSettingsBackend interface and then make it implement the
8049 * extension point #G_SETTINGS_BACKEND_EXTENSION_POINT_NAME.
8051 * The interface defines methods for reading and writing values, a
8052 * method for determining if writing of certain values will fail
8053 * (lockdown) and a change notification mechanism.
8055 * The semantics of the interface are very precisely defined and
8056 * implementations must carefully adhere to the expectations of
8057 * callers that are documented on each of the interface methods.
8059 * Some of the GSettingsBackend functions accept or return a #GTree.
8060 * These trees always have strings as keys and #GVariant as values.
8061 * g_settings_backend_create_tree() is a convenience function to create
8064 * The GSettingsBackend API is exported to allow third-party
8065 * implementations, but does not carry the same stability guarantees
8066 * as the public GIO API. For this reason, you have to define the
8067 * C preprocessor symbol %G_SETTINGS_ENABLE_BACKEND before including
8068 * `gio/gsettingsbackend.h`.
8073 * SECTION:gsettingsschema
8074 * @short_description: Introspecting and controlling the loading
8075 * of GSettings schemas
8076 * @include: gio/gio.h
8078 * The #GSettingsSchemaSource and #GSettingsSchema APIs provide a
8079 * mechanism for advanced control over the loading of schemas and a
8080 * mechanism for introspecting their content.
8082 * Plugin loading systems that wish to provide plugins a way to access
8083 * settings face the problem of how to make the schemas for these
8084 * settings visible to GSettings. Typically, a plugin will want to ship
8085 * the schema along with itself and it won't be installed into the
8086 * standard system directories for schemas.
8088 * #GSettingsSchemaSource provides a mechanism for dealing with this by
8089 * allowing the creation of a new 'schema source' from which schemas can
8090 * be acquired. This schema source can then become part of the metadata
8091 * associated with the plugin and queried whenever the plugin requires
8092 * access to some settings.
8094 * Consider the following example:
8096 * |[<!-- language="C" -->
8100 * GSettingsSchemaSource *schema_source;
8105 * initialise_plugin (const gchar *dir)
8111 * plugin->schema_source =
8112 * g_settings_new_schema_source_from_directory (dir,
8113 * g_settings_schema_source_get_default (), FALSE, NULL);
8123 * plugin_get_settings (Plugin *plugin,
8124 * const gchar *schema_id)
8126 * GSettingsSchema *schema;
8128 * if (schema_id == NULL)
8129 * schema_id = plugin->identifier;
8131 * schema = g_settings_schema_source_lookup (plugin->schema_source,
8132 * schema_id, FALSE);
8134 * if (schema == NULL)
8136 * ... disable the plugin or abort, etc ...
8139 * return g_settings_new_full (schema, NULL, NULL);
8143 * The code above shows how hooks should be added to the code that
8144 * initialises (or enables) the plugin to create the schema source and
8145 * how an API can be added to the plugin system to provide a convenient
8146 * way for the plugin to access its settings, using the schemas that it
8149 * From the standpoint of the plugin, it would need to ensure that it
8150 * ships a gschemas.compiled file as part of itself, and then simply do
8153 * |[<!-- language="C" -->
8155 * GSettings *settings;
8158 * settings = plugin_get_settings (self, NULL);
8159 * some_value = g_settings_get_int (settings, "some-value");
8164 * It's also possible that the plugin system expects the schema source
8165 * files (ie: .gschema.xml files) instead of a gschemas.compiled file.
8166 * In that case, the plugin loading system must compile the schemas for
8167 * itself before attempting to create the settings source.
8174 * SECTION:gsimpleaction
8175 * @title: GSimpleAction
8176 * @short_description: A simple GAction implementation
8177 * @include: gio/gio.h
8179 * A #GSimpleAction is the obvious simple implementation of the #GAction
8180 * interface. This is the easiest way to create an action for purposes of
8181 * adding it to a #GSimpleActionGroup.
8183 * See also #GtkAction.
8188 * SECTION:gsimpleactiongroup
8189 * @title: GSimpleActionGroup
8190 * @short_description: A simple GActionGroup implementation
8191 * @include: gio/gio.h
8193 * #GSimpleActionGroup is a hash table filled with #GAction objects,
8194 * implementing the #GActionGroup and #GActionMap interfaces.
8199 * SECTION:gsimpleasyncresult
8200 * @short_description: Simple asynchronous results implementation
8201 * @include: gio/gio.h
8202 * @see_also: #GAsyncResult, #GTask
8204 * As of GLib 2.46, #GSimpleAsyncResult is deprecated in favor of
8205 * #GTask, which provides a simpler API.
8207 * #GSimpleAsyncResult implements #GAsyncResult.
8209 * GSimpleAsyncResult handles #GAsyncReadyCallbacks, error
8210 * reporting, operation cancellation and the final state of an operation,
8211 * completely transparent to the application. Results can be returned
8212 * as a pointer e.g. for functions that return data that is collected
8213 * asynchronously, a boolean value for checking the success or failure
8214 * of an operation, or a #gssize for operations which return the number
8215 * of bytes modified by the operation; all of the simple return cases
8218 * Most of the time, an application will not need to know of the details
8219 * of this API; it is handled transparently, and any necessary operations
8220 * are handled by #GAsyncResult's interface. However, if implementing a
8221 * new GIO module, for writing language bindings, or for complex
8222 * applications that need better control of how asynchronous operations
8223 * are completed, it is important to understand this functionality.
8225 * GSimpleAsyncResults are tagged with the calling function to ensure
8226 * that asynchronous functions and their finishing functions are used
8227 * together correctly.
8229 * To create a new #GSimpleAsyncResult, call g_simple_async_result_new().
8230 * If the result needs to be created for a #GError, use
8231 * g_simple_async_result_new_from_error() or
8232 * g_simple_async_result_new_take_error(). If a #GError is not available
8233 * (e.g. the asynchronous operation's doesn't take a #GError argument),
8234 * but the result still needs to be created for an error condition, use
8235 * g_simple_async_result_new_error() (or g_simple_async_result_set_error_va()
8236 * if your application or binding requires passing a variable argument list
8237 * directly), and the error can then be propagated through the use of
8238 * g_simple_async_result_propagate_error().
8240 * An asynchronous operation can be made to ignore a cancellation event by
8241 * calling g_simple_async_result_set_handle_cancellation() with a
8242 * #GSimpleAsyncResult for the operation and %FALSE. This is useful for
8243 * operations that are dangerous to cancel, such as close (which would
8244 * cause a leak if cancelled before being run).
8246 * GSimpleAsyncResult can integrate into GLib's event loop, #GMainLoop,
8247 * or it can use #GThreads.
8248 * g_simple_async_result_complete() will finish an I/O task directly
8249 * from the point where it is called. g_simple_async_result_complete_in_idle()
8250 * will finish it from an idle handler in the
8251 * [thread-default main context][g-main-context-push-thread-default]
8252 * . g_simple_async_result_run_in_thread() will run the
8253 * job in a separate thread and then deliver the result to the
8254 * thread-default main context.
8256 * To set the results of an asynchronous function,
8257 * g_simple_async_result_set_op_res_gpointer(),
8258 * g_simple_async_result_set_op_res_gboolean(), and
8259 * g_simple_async_result_set_op_res_gssize()
8260 * are provided, setting the operation's result to a gpointer, gboolean, or
8261 * gssize, respectively.
8263 * Likewise, to get the result of an asynchronous function,
8264 * g_simple_async_result_get_op_res_gpointer(),
8265 * g_simple_async_result_get_op_res_gboolean(), and
8266 * g_simple_async_result_get_op_res_gssize() are
8267 * provided, getting the operation's result as a gpointer, gboolean, and
8268 * gssize, respectively.
8270 * For the details of the requirements implementations must respect, see
8271 * #GAsyncResult. A typical implementation of an asynchronous operation
8272 * using GSimpleAsyncResult looks something like this:
8274 * |[<!-- language="C" -->
8276 * baked_cb (Cake *cake,
8277 * gpointer user_data)
8279 * // In this example, this callback is not given a reference to the cake,
8280 * // so the GSimpleAsyncResult has to take a reference to it.
8281 * GSimpleAsyncResult *result = user_data;
8284 * g_simple_async_result_set_error (result,
8286 * BAKER_ERROR_NO_FLOUR,
8287 * "Go to the supermarket");
8289 * g_simple_async_result_set_op_res_gpointer (result,
8290 * g_object_ref (cake),
8294 * // In this example, we assume that baked_cb is called as a callback from
8295 * // the mainloop, so it's safe to complete the operation synchronously here.
8296 * // If, however, _baker_prepare_cake () might call its callback without
8297 * // first returning to the mainloop — inadvisable, but some APIs do so —
8298 * // we would need to use g_simple_async_result_complete_in_idle().
8299 * g_simple_async_result_complete (result);
8300 * g_object_unref (result);
8304 * baker_bake_cake_async (Baker *self,
8306 * GAsyncReadyCallback callback,
8307 * gpointer user_data)
8309 * GSimpleAsyncResult *simple;
8314 * g_simple_async_report_error_in_idle (G_OBJECT (self),
8318 * BAKER_ERROR_TOO_SMALL,
8319 * "%ucm radius cakes are silly",
8324 * simple = g_simple_async_result_new (G_OBJECT (self),
8327 * baker_bake_cake_async);
8328 * cake = _baker_get_cached_cake (self, radius);
8332 * g_simple_async_result_set_op_res_gpointer (simple,
8333 * g_object_ref (cake),
8335 * g_simple_async_result_complete_in_idle (simple);
8336 * g_object_unref (simple);
8337 * // Drop the reference returned by _baker_get_cached_cake();
8338 * // the GSimpleAsyncResult has taken its own reference.
8339 * g_object_unref (cake);
8343 * _baker_prepare_cake (self, radius, baked_cb, simple);
8347 * baker_bake_cake_finish (Baker *self,
8348 * GAsyncResult *result,
8351 * GSimpleAsyncResult *simple;
8354 * g_return_val_if_fail (g_simple_async_result_is_valid (result,
8356 * baker_bake_cake_async),
8359 * simple = (GSimpleAsyncResult *) result;
8361 * if (g_simple_async_result_propagate_error (simple, error))
8364 * cake = CAKE (g_simple_async_result_get_op_res_gpointer (simple));
8365 * return g_object_ref (cake);
8372 * SECTION:gsimpleiostream
8373 * @short_description: A wrapper around an input and an output stream.
8374 * @include: gio/gio.h
8375 * @see_also: #GIOStream
8377 * GSimpleIOStream creates a #GIOStream from an arbitrary #GInputStream and
8378 * #GOutputStream. This allows any pair of input and output streams to be used
8379 * with #GIOStream methods.
8381 * This is useful when you obtained a #GInputStream and a #GOutputStream
8382 * by other means, for instance creating them with platform specific methods as
8383 * g_unix_input_stream_new() or g_win32_input_stream_new(), and you want
8384 * to take advantage of the methods provided by #GIOStream.
8391 * SECTION:gsimplepermission
8392 * @title: GSimplePermission
8393 * @short_description: A GPermission that doesn't change value
8394 * @include: gio/gio.h
8396 * #GSimplePermission is a trivial implementation of #GPermission that
8397 * represents a permission that is either always or never allowed. The
8398 * value is given at construction and doesn't change.
8400 * Calling request or release will result in errors.
8405 * SECTION:gsimpleproxyresolver
8406 * @short_description: Simple proxy resolver implementation
8407 * @include: gio/gio.h
8408 * @see_also: g_socket_client_set_proxy_resolver()
8410 * #GSimpleProxyResolver is a simple #GProxyResolver implementation
8411 * that handles a single default proxy, multiple URI-scheme-specific
8412 * proxies, and a list of hosts that proxies should not be used for.
8414 * #GSimpleProxyResolver is never the default proxy resolver, but it
8415 * can be used as the base class for another proxy resolver
8416 * implementation, or it can be created and used manually, such as
8417 * with g_socket_client_set_proxy_resolver().
8425 * @short_description: Low-level socket object
8426 * @include: gio/gio.h
8427 * @see_also: #GInitable, [<gnetworking.h>][gio-gnetworking.h]
8429 * A #GSocket is a low-level networking primitive. It is a more or less
8430 * direct mapping of the BSD socket API in a portable GObject based API.
8431 * It supports both the UNIX socket implementations and winsock2 on Windows.
8433 * #GSocket is the platform independent base upon which the higher level
8434 * network primitives are based. Applications are not typically meant to
8435 * use it directly, but rather through classes like #GSocketClient,
8436 * #GSocketService and #GSocketConnection. However there may be cases where
8437 * direct use of #GSocket is useful.
8439 * #GSocket implements the #GInitable interface, so if it is manually constructed
8440 * by e.g. g_object_new() you must call g_initable_init() and check the
8441 * results before using the object. This is done automatically in
8442 * g_socket_new() and g_socket_new_from_fd(), so these functions can return
8445 * Sockets operate in two general modes, blocking or non-blocking. When
8446 * in blocking mode all operations (which don’t take an explicit blocking
8447 * parameter) block until the requested operation
8448 * is finished or there is an error. In non-blocking mode all calls that
8449 * would block return immediately with a %G_IO_ERROR_WOULD_BLOCK error.
8450 * To know when a call would successfully run you can call g_socket_condition_check(),
8451 * or g_socket_condition_wait(). You can also use g_socket_create_source() and
8452 * attach it to a #GMainContext to get callbacks when I/O is possible.
8453 * Note that all sockets are always set to non blocking mode in the system, and
8454 * blocking mode is emulated in GSocket.
8456 * When working in non-blocking mode applications should always be able to
8457 * handle getting a %G_IO_ERROR_WOULD_BLOCK error even when some other
8458 * function said that I/O was possible. This can easily happen in case
8459 * of a race condition in the application, but it can also happen for other
8460 * reasons. For instance, on Windows a socket is always seen as writable
8461 * until a write returns %G_IO_ERROR_WOULD_BLOCK.
8463 * #GSockets can be either connection oriented or datagram based.
8464 * For connection oriented types you must first establish a connection by
8465 * either connecting to an address or accepting a connection from another
8466 * address. For connectionless socket types the target/source address is
8467 * specified or received in each I/O operation.
8469 * All socket file descriptors are set to be close-on-exec.
8471 * Note that creating a #GSocket causes the signal %SIGPIPE to be
8472 * ignored for the remainder of the program. If you are writing a
8473 * command-line utility that uses #GSocket, you may need to take into
8474 * account the fact that your program will not automatically be killed
8475 * if it tries to write to %stdout after it has been closed.
8477 * Like most other APIs in GLib, #GSocket is not inherently thread safe. To use
8478 * a #GSocket concurrently from multiple threads, you must implement your own
8486 * SECTION:gsocketaddress
8487 * @short_description: Abstract base class representing endpoints
8488 * for socket communication
8489 * @include: gio/gio.h
8491 * #GSocketAddress is the equivalent of struct sockaddr in the BSD
8492 * sockets API. This is an abstract class; use #GInetSocketAddress
8493 * for internet sockets, or #GUnixSocketAddress for UNIX domain sockets.
8498 * SECTION:gsocketclient
8499 * @short_description: Helper for connecting to a network service
8500 * @include: gio/gio.h
8501 * @see_also: #GSocketConnection, #GSocketListener
8503 * #GSocketClient is a lightweight high-level utility class for connecting to
8504 * a network host using a connection oriented socket type.
8506 * You create a #GSocketClient object, set any options you want, and then
8507 * call a sync or async connect operation, which returns a #GSocketConnection
8508 * subclass on success.
8510 * The type of the #GSocketConnection object returned depends on the type of
8511 * the underlying socket that is in use. For instance, for a TCP/IP connection
8512 * it will be a #GTcpConnection.
8514 * As #GSocketClient is a lightweight object, you don't need to cache it. You
8515 * can just create a new one any time you need one.
8522 * SECTION:gsocketconnectable
8523 * @short_description: Interface for potential socket endpoints
8524 * @include: gio/gio.h
8526 * Objects that describe one or more potential socket endpoints
8527 * implement #GSocketConnectable. Callers can then use
8528 * g_socket_connectable_enumerate() to get a #GSocketAddressEnumerator
8529 * to try out each socket address in turn until one succeeds, as shown
8530 * in the sample code below.
8532 * |[<!-- language="C" -->
8533 * MyConnectionType *
8534 * connect_to_host (const char *hostname,
8536 * GCancellable *cancellable,
8539 * MyConnection *conn = NULL;
8540 * GSocketConnectable *addr;
8541 * GSocketAddressEnumerator *enumerator;
8542 * GSocketAddress *sockaddr;
8543 * GError *conn_error = NULL;
8545 * addr = g_network_address_new (hostname, port);
8546 * enumerator = g_socket_connectable_enumerate (addr);
8547 * g_object_unref (addr);
8549 * // Try each sockaddr until we succeed. Record the first connection error,
8550 * // but not any further ones (since they'll probably be basically the same
8552 * while (!conn && (sockaddr = g_socket_address_enumerator_next (enumerator, cancellable, error))
8554 * conn = connect_to_sockaddr (sockaddr, conn_error ? NULL : &conn_error);
8555 * g_object_unref (sockaddr);
8557 * g_object_unref (enumerator);
8563 * // We couldn't connect to the first address, but we succeeded
8564 * // in connecting to a later address.
8565 * g_error_free (conn_error);
8571 * /// Either initial lookup failed, or else the caller cancelled us.
8573 * g_error_free (conn_error);
8578 * g_error_propagate (error, conn_error);
8587 * SECTION:gsocketconnection
8588 * @short_description: A socket connection
8589 * @include: gio/gio.h
8590 * @see_also: #GIOStream, #GSocketClient, #GSocketListener
8592 * #GSocketConnection is a #GIOStream for a connected socket. They
8593 * can be created either by #GSocketClient when connecting to a host,
8594 * or by #GSocketListener when accepting a new client.
8596 * The type of the #GSocketConnection object returned from these calls
8597 * depends on the type of the underlying socket that is in use. For
8598 * instance, for a TCP/IP connection it will be a #GTcpConnection.
8600 * Choosing what type of object to construct is done with the socket
8601 * connection factory, and it is possible for 3rd parties to register
8602 * custom socket connection types for specific combination of socket
8603 * family/type/protocol using g_socket_connection_factory_register_type().
8605 * To close a #GSocketConnection, use g_io_stream_close(). Closing both
8606 * substreams of the #GIOStream separately will not close the underlying
8614 * SECTION:gsocketcontrolmessage
8615 * @title: GSocketControlMessage
8616 * @short_description: A GSocket control message
8617 * @include: gio/gio.h
8618 * @see_also: #GSocket.
8620 * A #GSocketControlMessage is a special-purpose utility message that
8621 * can be sent to or received from a #GSocket. These types of
8622 * messages are often called "ancillary data".
8624 * The message can represent some sort of special instruction to or
8625 * information from the socket or can represent a special kind of
8626 * transfer to the peer (for example, sending a file descriptor over
8629 * These messages are sent with g_socket_send_message() and received
8630 * with g_socket_receive_message().
8632 * To extend the set of control message that can be sent, subclass this
8633 * class and override the get_size, get_level, get_type and serialize
8636 * To extend the set of control messages that can be received, subclass
8637 * this class and implement the deserialize method. Also, make sure your
8638 * class is registered with the GType typesystem before calling
8639 * g_socket_receive_message() to read such a message.
8646 * SECTION:gsocketlistener
8647 * @title: GSocketListener
8648 * @short_description: Helper for accepting network client connections
8649 * @include: gio/gio.h
8650 * @see_also: #GThreadedSocketService, #GSocketService.
8652 * A #GSocketListener is an object that keeps track of a set
8653 * of server sockets and helps you accept sockets from any of the
8654 * socket, either sync or async.
8656 * If you want to implement a network server, also look at #GSocketService
8657 * and #GThreadedSocketService which are subclass of #GSocketListener
8658 * that makes this even easier.
8665 * SECTION:gsocketservice
8666 * @title: GSocketService
8667 * @short_description: Make it easy to implement a network service
8668 * @include: gio/gio.h
8669 * @see_also: #GThreadedSocketService, #GSocketListener.
8671 * A #GSocketService is an object that represents a service that
8672 * is provided to the network or over local sockets. When a new
8673 * connection is made to the service the #GSocketService::incoming
8674 * signal is emitted.
8676 * A #GSocketService is a subclass of #GSocketListener and you need
8677 * to add the addresses you want to accept connections on with the
8678 * #GSocketListener APIs.
8680 * There are two options for implementing a network service based on
8681 * #GSocketService. The first is to create the service using
8682 * g_socket_service_new() and to connect to the #GSocketService::incoming
8683 * signal. The second is to subclass #GSocketService and override the
8684 * default signal handler implementation.
8686 * In either case, the handler must immediately return, or else it
8687 * will block additional incoming connections from being serviced.
8688 * If you are interested in writing connection handlers that contain
8689 * blocking code then see #GThreadedSocketService.
8691 * The socket service runs on the main loop of the
8692 * [thread-default context][g-main-context-push-thread-default-context]
8693 * of the thread it is created in, and is not
8694 * threadsafe in general. However, the calls to start and stop the
8695 * service are thread-safe so these can be used from threads that
8696 * handle incoming clients.
8703 * SECTION:gsrvtarget
8704 * @short_description: DNS SRV record target
8705 * @include: gio/gio.h
8707 * SRV (service) records are used by some network protocols to provide
8708 * service-specific aliasing and load-balancing. For example, XMPP
8709 * (Jabber) uses SRV records to locate the XMPP server for a domain;
8710 * rather than connecting directly to "example.com" or assuming a
8711 * specific server hostname like "xmpp.example.com", an XMPP client
8712 * would look up the "xmpp-client" SRV record for "example.com", and
8713 * then connect to whatever host was pointed to by that record.
8715 * You can use g_resolver_lookup_service() or
8716 * g_resolver_lookup_service_async() to find the #GSrvTargets
8717 * for a given service. However, if you are simply planning to connect
8718 * to the remote service, you can use #GNetworkService's
8719 * #GSocketConnectable interface and not need to worry about
8720 * #GSrvTarget at all.
8725 * SECTION:gsubprocess
8726 * @title: GSubprocess
8727 * @short_description: Child processes
8728 * @include: gio/gio.h
8729 * @see_also: #GSubprocessLauncher
8731 * #GSubprocess allows the creation of and interaction with child
8734 * Processes can be communicated with using standard GIO-style APIs (ie:
8735 * #GInputStream, #GOutputStream). There are GIO-style APIs to wait for
8736 * process termination (ie: cancellable and with an asynchronous
8739 * There is an API to force a process to terminate, as well as a
8740 * race-free API for sending UNIX signals to a subprocess.
8742 * One major advantage that GIO brings over the core GLib library is
8743 * comprehensive API for asynchronous I/O, such
8744 * g_output_stream_splice_async(). This makes GSubprocess
8745 * significantly more powerful and flexible than equivalent APIs in
8746 * some other languages such as the `subprocess.py`
8747 * included with Python. For example, using #GSubprocess one could
8748 * create two child processes, reading standard output from the first,
8749 * processing it, and writing to the input stream of the second, all
8750 * without blocking the main loop.
8752 * A powerful g_subprocess_communicate() API is provided similar to the
8753 * `communicate()` method of `subprocess.py`. This enables very easy
8754 * interaction with a subprocess that has been opened with pipes.
8756 * #GSubprocess defaults to tight control over the file descriptors open
8757 * in the child process, avoiding dangling-fd issues that are caused by
8758 * a simple fork()/exec(). The only open file descriptors in the
8759 * spawned process are ones that were explicitly specified by the
8760 * #GSubprocess API (unless %G_SUBPROCESS_FLAGS_INHERIT_FDS was
8763 * #GSubprocess will quickly reap all child processes as they exit,
8764 * avoiding "zombie processes" remaining around for long periods of
8765 * time. g_subprocess_wait() can be used to wait for this to happen,
8766 * but it will happen even without the call being explicitly made.
8768 * As a matter of principle, #GSubprocess has no API that accepts
8769 * shell-style space-separated strings. It will, however, match the
8770 * typical shell behaviour of searching the PATH for executables that do
8771 * not contain a directory separator in their name.
8773 * #GSubprocess attempts to have a very simple API for most uses (ie:
8774 * spawning a subprocess with arguments and support for most typical
8775 * kinds of input and output redirection). See g_subprocess_new(). The
8776 * #GSubprocessLauncher API is provided for more complicated cases
8777 * (advanced types of redirection, environment variable manipulation,
8778 * change of working directory, child setup functions, etc).
8780 * A typical use of #GSubprocess will involve calling
8781 * g_subprocess_new(), followed by g_subprocess_wait_async() or
8782 * g_subprocess_wait(). After the process exits, the status can be
8783 * checked using functions such as g_subprocess_get_if_exited() (which
8784 * are similar to the familiar WIFEXITED-style POSIX macros).
8791 * SECTION:gsubprocesslauncher
8792 * @title: GSubprocess Launcher
8793 * @short_description: Environment options for launching a child process
8794 * @include: gio/gio.h
8796 * This class contains a set of options for launching child processes,
8797 * such as where its standard input and output will be directed, the
8798 * argument list, the environment, and more.
8800 * While the #GSubprocess class has high level functions covering
8801 * popular cases, use of this class allows access to more advanced
8802 * options. It can also be used to launch multiple subprocesses with
8803 * a similar configuration.
8811 * @short_description: Cancellable synchronous or asynchronous task
8813 * @include: gio/gio.h
8814 * @see_also: #GAsyncResult
8816 * A #GTask represents and manages a cancellable "task".
8818 * ## Asynchronous operations
8820 * The most common usage of #GTask is as a #GAsyncResult, to
8821 * manage data during an asynchronous operation. You call
8822 * g_task_new() in the "start" method, followed by
8823 * g_task_set_task_data() and the like if you need to keep some
8824 * additional data associated with the task, and then pass the
8825 * task object around through your asynchronous operation.
8826 * Eventually, you will call a method such as
8827 * g_task_return_pointer() or g_task_return_error(), which will
8828 * save the value you give it and then invoke the task's callback
8829 * function (waiting until the next iteration of the main
8830 * loop first, if necessary). The caller will pass the #GTask back
8831 * to the operation's finish function (as a #GAsyncResult), and
8832 * you can use g_task_propagate_pointer() or the like to extract
8835 * Here is an example for using GTask as a GAsyncResult:
8836 * |[<!-- language="C" -->
8838 * CakeFrostingType frosting;
8843 * decoration_data_free (DecorationData *decoration)
8845 * g_free (decoration->message);
8846 * g_slice_free (DecorationData, decoration);
8850 * baked_cb (Cake *cake,
8851 * gpointer user_data)
8853 * GTask *task = user_data;
8854 * DecorationData *decoration = g_task_get_task_data (task);
8855 * GError *error = NULL;
8859 * g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_NO_FLOUR,
8860 * "Go to the supermarket");
8861 * g_object_unref (task);
8865 * if (!cake_decorate (cake, decoration->frosting, decoration->message, &error))
8867 * g_object_unref (cake);
8868 * // g_task_return_error() takes ownership of error
8869 * g_task_return_error (task, error);
8870 * g_object_unref (task);
8874 * g_task_return_pointer (task, cake, g_object_unref);
8875 * g_object_unref (task);
8879 * baker_bake_cake_async (Baker *self,
8881 * CakeFlavor flavor,
8882 * CakeFrostingType frosting,
8883 * const char *message,
8884 * GCancellable *cancellable,
8885 * GAsyncReadyCallback callback,
8886 * gpointer user_data)
8889 * DecorationData *decoration;
8892 * task = g_task_new (self, cancellable, callback, user_data);
8895 * g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_TOO_SMALL,
8896 * "%ucm radius cakes are silly",
8898 * g_object_unref (task);
8902 * cake = _baker_get_cached_cake (self, radius, flavor, frosting, message);
8905 * // _baker_get_cached_cake() returns a reffed cake
8906 * g_task_return_pointer (task, cake, g_object_unref);
8907 * g_object_unref (task);
8911 * decoration = g_slice_new (DecorationData);
8912 * decoration->frosting = frosting;
8913 * decoration->message = g_strdup (message);
8914 * g_task_set_task_data (task, decoration, (GDestroyNotify) decoration_data_free);
8916 * _baker_begin_cake (self, radius, flavor, cancellable, baked_cb, task);
8920 * baker_bake_cake_finish (Baker *self,
8921 * GAsyncResult *result,
8924 * g_return_val_if_fail (g_task_is_valid (result, self), NULL);
8926 * return g_task_propagate_pointer (G_TASK (result), error);
8930 * ## Chained asynchronous operations
8932 * #GTask also tries to simplify asynchronous operations that
8933 * internally chain together several smaller asynchronous
8934 * operations. g_task_get_cancellable(), g_task_get_context(),
8935 * and g_task_get_priority() allow you to get back the task's
8936 * #GCancellable, #GMainContext, and [I/O priority][io-priority]
8937 * when starting a new subtask, so you don't have to keep track
8938 * of them yourself. g_task_attach_source() simplifies the case
8939 * of waiting for a source to fire (automatically using the correct
8940 * #GMainContext and priority).
8942 * Here is an example for chained asynchronous operations:
8943 * |[<!-- language="C" -->
8946 * CakeFrostingType frosting;
8951 * decoration_data_free (BakingData *bd)
8954 * g_object_unref (bd->cake);
8955 * g_free (bd->message);
8956 * g_slice_free (BakingData, bd);
8960 * decorated_cb (Cake *cake,
8961 * GAsyncResult *result,
8962 * gpointer user_data)
8964 * GTask *task = user_data;
8965 * GError *error = NULL;
8967 * if (!cake_decorate_finish (cake, result, &error))
8969 * g_object_unref (cake);
8970 * g_task_return_error (task, error);
8971 * g_object_unref (task);
8975 * // baking_data_free() will drop its ref on the cake, so we have to
8976 * // take another here to give to the caller.
8977 * g_task_return_pointer (task, g_object_ref (cake), g_object_unref);
8978 * g_object_unref (task);
8982 * decorator_ready (gpointer user_data)
8984 * GTask *task = user_data;
8985 * BakingData *bd = g_task_get_task_data (task);
8987 * cake_decorate_async (bd->cake, bd->frosting, bd->message,
8988 * g_task_get_cancellable (task),
8989 * decorated_cb, task);
8991 * return G_SOURCE_REMOVE;
8995 * baked_cb (Cake *cake,
8996 * gpointer user_data)
8998 * GTask *task = user_data;
8999 * BakingData *bd = g_task_get_task_data (task);
9000 * GError *error = NULL;
9004 * g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_NO_FLOUR,
9005 * "Go to the supermarket");
9006 * g_object_unref (task);
9012 * // Bail out now if the user has already cancelled
9013 * if (g_task_return_error_if_cancelled (task))
9015 * g_object_unref (task);
9019 * if (cake_decorator_available (cake))
9020 * decorator_ready (task);
9025 * source = cake_decorator_wait_source_new (cake);
9026 * // Attach @source to @task's GMainContext and have it call
9027 * // decorator_ready() when it is ready.
9028 * g_task_attach_source (task, source, decorator_ready);
9029 * g_source_unref (source);
9034 * baker_bake_cake_async (Baker *self,
9036 * CakeFlavor flavor,
9037 * CakeFrostingType frosting,
9038 * const char *message,
9040 * GCancellable *cancellable,
9041 * GAsyncReadyCallback callback,
9042 * gpointer user_data)
9047 * task = g_task_new (self, cancellable, callback, user_data);
9048 * g_task_set_priority (task, priority);
9050 * bd = g_slice_new0 (BakingData);
9051 * bd->frosting = frosting;
9052 * bd->message = g_strdup (message);
9053 * g_task_set_task_data (task, bd, (GDestroyNotify) baking_data_free);
9055 * _baker_begin_cake (self, radius, flavor, cancellable, baked_cb, task);
9059 * baker_bake_cake_finish (Baker *self,
9060 * GAsyncResult *result,
9063 * g_return_val_if_fail (g_task_is_valid (result, self), NULL);
9065 * return g_task_propagate_pointer (G_TASK (result), error);
9069 * ## Asynchronous operations from synchronous ones
9071 * You can use g_task_run_in_thread() to turn a synchronous
9072 * operation into an asynchronous one, by running it in a thread
9073 * which will then dispatch the result back to the caller's
9074 * #GMainContext when it completes.
9076 * Running a task in a thread:
9077 * |[<!-- language="C" -->
9080 * CakeFlavor flavor;
9081 * CakeFrostingType frosting;
9086 * cake_data_free (CakeData *cake_data)
9088 * g_free (cake_data->message);
9089 * g_slice_free (CakeData, cake_data);
9093 * bake_cake_thread (GTask *task,
9094 * gpointer source_object,
9095 * gpointer task_data,
9096 * GCancellable *cancellable)
9098 * Baker *self = source_object;
9099 * CakeData *cake_data = task_data;
9101 * GError *error = NULL;
9103 * cake = bake_cake (baker, cake_data->radius, cake_data->flavor,
9104 * cake_data->frosting, cake_data->message,
9105 * cancellable, &error);
9107 * g_task_return_pointer (task, cake, g_object_unref);
9109 * g_task_return_error (task, error);
9113 * baker_bake_cake_async (Baker *self,
9115 * CakeFlavor flavor,
9116 * CakeFrostingType frosting,
9117 * const char *message,
9118 * GCancellable *cancellable,
9119 * GAsyncReadyCallback callback,
9120 * gpointer user_data)
9122 * CakeData *cake_data;
9125 * cake_data = g_slice_new (CakeData);
9126 * cake_data->radius = radius;
9127 * cake_data->flavor = flavor;
9128 * cake_data->frosting = frosting;
9129 * cake_data->message = g_strdup (message);
9130 * task = g_task_new (self, cancellable, callback, user_data);
9131 * g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free);
9132 * g_task_run_in_thread (task, bake_cake_thread);
9133 * g_object_unref (task);
9137 * baker_bake_cake_finish (Baker *self,
9138 * GAsyncResult *result,
9141 * g_return_val_if_fail (g_task_is_valid (result, self), NULL);
9143 * return g_task_propagate_pointer (G_TASK (result), error);
9147 * ## Adding cancellability to uncancellable tasks
9149 * Finally, g_task_run_in_thread() and g_task_run_in_thread_sync()
9150 * can be used to turn an uncancellable operation into a
9151 * cancellable one. If you call g_task_set_return_on_cancel(),
9152 * passing %TRUE, then if the task's #GCancellable is cancelled,
9153 * it will return control back to the caller immediately, while
9154 * allowing the task thread to continue running in the background
9155 * (and simply discarding its result when it finally does finish).
9156 * Provided that the task thread is careful about how it uses
9157 * locks and other externally-visible resources, this allows you
9158 * to make "GLib-friendly" asynchronous and cancellable
9159 * synchronous variants of blocking APIs.
9161 * Cancelling a task:
9162 * |[<!-- language="C" -->
9164 * bake_cake_thread (GTask *task,
9165 * gpointer source_object,
9166 * gpointer task_data,
9167 * GCancellable *cancellable)
9169 * Baker *self = source_object;
9170 * CakeData *cake_data = task_data;
9172 * GError *error = NULL;
9174 * cake = bake_cake (baker, cake_data->radius, cake_data->flavor,
9175 * cake_data->frosting, cake_data->message,
9179 * g_task_return_error (task, error);
9183 * // If the task has already been cancelled, then we don't want to add
9184 * // the cake to the cake cache. Likewise, we don't want to have the
9185 * // task get cancelled in the middle of updating the cache.
9186 * // g_task_set_return_on_cancel() will return %TRUE here if it managed
9187 * // to disable return-on-cancel, or %FALSE if the task was cancelled
9188 * // before it could.
9189 * if (g_task_set_return_on_cancel (task, FALSE))
9191 * // If the caller cancels at this point, their
9192 * // GAsyncReadyCallback won't be invoked until we return,
9193 * // so we don't have to worry that this code will run at
9194 * // the same time as that code does. But if there were
9195 * // other functions that might look at the cake cache,
9196 * // then we'd probably need a GMutex here as well.
9197 * baker_add_cake_to_cache (baker, cake);
9198 * g_task_return_pointer (task, cake, g_object_unref);
9203 * baker_bake_cake_async (Baker *self,
9205 * CakeFlavor flavor,
9206 * CakeFrostingType frosting,
9207 * const char *message,
9208 * GCancellable *cancellable,
9209 * GAsyncReadyCallback callback,
9210 * gpointer user_data)
9212 * CakeData *cake_data;
9215 * cake_data = g_slice_new (CakeData);
9219 * task = g_task_new (self, cancellable, callback, user_data);
9220 * g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free);
9221 * g_task_set_return_on_cancel (task, TRUE);
9222 * g_task_run_in_thread (task, bake_cake_thread);
9226 * baker_bake_cake_sync (Baker *self,
9228 * CakeFlavor flavor,
9229 * CakeFrostingType frosting,
9230 * const char *message,
9231 * GCancellable *cancellable,
9234 * CakeData *cake_data;
9238 * cake_data = g_slice_new (CakeData);
9242 * task = g_task_new (self, cancellable, NULL, NULL);
9243 * g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free);
9244 * g_task_set_return_on_cancel (task, TRUE);
9245 * g_task_run_in_thread_sync (task, bake_cake_thread);
9247 * cake = g_task_propagate_pointer (task, error);
9248 * g_object_unref (task);
9253 * ## Porting from GSimpleAsyncResult
9255 * #GTask's API attempts to be simpler than #GSimpleAsyncResult's
9257 * - You can save task-specific data with g_task_set_task_data(), and
9258 * retrieve it later with g_task_get_task_data(). This replaces the
9259 * abuse of g_simple_async_result_set_op_res_gpointer() for the same
9260 * purpose with #GSimpleAsyncResult.
9261 * - In addition to the task data, #GTask also keeps track of the
9262 * [priority][io-priority], #GCancellable, and
9263 * #GMainContext associated with the task, so tasks that consist of
9264 * a chain of simpler asynchronous operations will have easy access
9265 * to those values when starting each sub-task.
9266 * - g_task_return_error_if_cancelled() provides simplified
9267 * handling for cancellation. In addition, cancellation
9268 * overrides any other #GTask return value by default, like
9269 * #GSimpleAsyncResult does when
9270 * g_simple_async_result_set_check_cancellable() is called.
9271 * (You can use g_task_set_check_cancellable() to turn off that
9272 * behavior.) On the other hand, g_task_run_in_thread()
9273 * guarantees that it will always run your
9274 * `task_func`, even if the task's #GCancellable
9275 * is already cancelled before the task gets a chance to run;
9276 * you can start your `task_func` with a
9277 * g_task_return_error_if_cancelled() check if you need the
9279 * - The "return" methods (eg, g_task_return_pointer())
9280 * automatically cause the task to be "completed" as well, and
9281 * there is no need to worry about the "complete" vs "complete
9282 * in idle" distinction. (#GTask automatically figures out
9283 * whether the task's callback can be invoked directly, or
9284 * if it needs to be sent to another #GMainContext, or delayed
9285 * until the next iteration of the current #GMainContext.)
9286 * - The "finish" functions for #GTask-based operations are generally
9287 * much simpler than #GSimpleAsyncResult ones, normally consisting
9288 * of only a single call to g_task_propagate_pointer() or the like.
9289 * Since g_task_propagate_pointer() "steals" the return value from
9290 * the #GTask, it is not necessary to juggle pointers around to
9291 * prevent it from being freed twice.
9292 * - With #GSimpleAsyncResult, it was common to call
9293 * g_simple_async_result_propagate_error() from the
9294 * `_finish()` wrapper function, and have
9295 * virtual method implementations only deal with successful
9296 * returns. This behavior is deprecated, because it makes it
9297 * difficult for a subclass to chain to a parent class's async
9298 * methods. Instead, the wrapper function should just be a
9299 * simple wrapper, and the virtual method should call an
9300 * appropriate `g_task_propagate_` function.
9301 * Note that wrapper methods can now use
9302 * g_async_result_legacy_propagate_error() to do old-style
9303 * #GSimpleAsyncResult error-returning behavior, and
9304 * g_async_result_is_tagged() to check if a result is tagged as
9305 * having come from the `_async()` wrapper
9306 * function (for "short-circuit" results, such as when passing
9307 * 0 to g_input_stream_read_async()).
9312 * SECTION:gtcpconnection
9313 * @title: GTcpConnection
9314 * @short_description: A TCP GSocketConnection
9315 * @include: gio/gio.h
9316 * @see_also: #GSocketConnection.
9318 * This is the subclass of #GSocketConnection that is created
9319 * for TCP/IP sockets.
9326 * SECTION:gtcpwrapperconnection
9327 * @title: GTcpWrapperConnection
9328 * @short_description: Wrapper for non-GSocketConnection-based,
9329 * GSocket-based GIOStreams
9330 * @include: gio/gio.h
9331 * @see_also: #GSocketConnection.
9333 * A #GTcpWrapperConnection can be used to wrap a #GIOStream that is
9334 * based on a #GSocket, but which is not actually a
9335 * #GSocketConnection. This is used by #GSocketClient so that it can
9336 * always return a #GSocketConnection, even when the connection it has
9337 * actually created is not directly a #GSocketConnection.
9345 * @short_description: D-Bus testing helper
9346 * @include: gio/gio.h
9348 * A helper class for testing code which uses D-Bus without touching the user's
9351 * Note that #GTestDBus modifies the user’s environment, calling setenv().
9352 * This is not thread-safe, so all #GTestDBus calls should be completed before
9353 * threads are spawned, or should have appropriate locking to ensure no access
9354 * conflicts to environment variables shared between #GTestDBus and other
9357 * ## Creating unit tests using GTestDBus
9359 * Testing of D-Bus services can be tricky because normally we only ever run
9360 * D-Bus services over an existing instance of the D-Bus daemon thus we
9361 * usually don't activate D-Bus services that are not yet installed into the
9362 * target system. The #GTestDBus object makes this easier for us by taking care
9363 * of the lower level tasks such as running a private D-Bus daemon and looking
9364 * up uninstalled services in customizable locations, typically in your source
9367 * The first thing you will need is a separate service description file for the
9368 * D-Bus daemon. Typically a `services` subdirectory of your `tests` directory
9369 * is a good place to put this file.
9371 * The service file should list your service along with an absolute path to the
9372 * uninstalled service executable in your source tree. Using autotools we would
9373 * achieve this by adding a file such as `my-server.service.in` in the services
9374 * directory and have it processed by configure.
9377 * Name=org.gtk.GDBus.Examples.ObjectManager
9378 * Exec=@abs_top_builddir@/gio/tests/gdbus-example-objectmanager-server
9380 * You will also need to indicate this service directory in your test
9381 * fixtures, so you will need to pass the path while compiling your
9382 * test cases. Typically this is done with autotools with an added
9383 * preprocessor flag specified to compile your tests such as:
9385 * -DTEST_SERVICES=\""$(abs_top_builddir)/tests/services"\"
9387 * Once you have a service definition file which is local to your source tree,
9388 * you can proceed to set up a GTest fixture using the #GTestDBus scaffolding.
9390 * An example of a test fixture for D-Bus services can be found
9392 * [gdbus-test-fixture.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-test-fixture.c)
9394 * Note that these examples only deal with isolating the D-Bus aspect of your
9395 * service. To successfully run isolated unit tests on your service you may need
9396 * some additional modifications to your test case fixture. For example; if your
9397 * service uses GSettings and installs a schema then it is important that your test service
9398 * not load the schema in the ordinary installed location (chances are that your service
9399 * and schema files are not yet installed, or worse; there is an older version of the
9400 * schema file sitting in the install location).
9402 * Most of the time we can work around these obstacles using the
9403 * environment. Since the environment is inherited by the D-Bus daemon
9404 * created by #GTestDBus and then in turn inherited by any services the
9405 * D-Bus daemon activates, using the setup routine for your fixture is
9406 * a practical place to help sandbox your runtime environment. For the
9407 * rather typical GSettings case we can work around this by setting
9408 * `GSETTINGS_SCHEMA_DIR` to the in tree directory holding your schemas
9409 * in the above fixture_setup() routine.
9411 * The GSettings schemas need to be locally pre-compiled for this to work. This can be achieved
9412 * by compiling the schemas locally as a step before running test cases, an autotools setup might
9413 * do the following in the directory holding schemas:
9416 * $(GLIB_COMPILE_SCHEMAS) .
9418 * CLEANFILES += gschemas.compiled
9424 * SECTION:gthemedicon
9425 * @short_description: Icon theming support
9426 * @include: gio/gio.h
9427 * @see_also: #GIcon, #GLoadableIcon
9429 * #GThemedIcon is an implementation of #GIcon that supports icon themes.
9430 * #GThemedIcon contains a list of all of the icons present in an icon
9431 * theme, so that icons can be looked up quickly. #GThemedIcon does
9432 * not provide actual pixmaps for icons, just the icon names.
9433 * Ideally something like gtk_icon_theme_choose_icon() should be used to
9434 * resolve the list of names so that fallback icons work nicely with
9435 * themes that inherit other themes.
9440 * SECTION:gthreadedsocketservice
9441 * @title: GThreadedSocketService
9442 * @short_description: A threaded GSocketService
9443 * @include: gio/gio.h
9444 * @see_also: #GSocketService.
9446 * A #GThreadedSocketService is a simple subclass of #GSocketService
9447 * that handles incoming connections by creating a worker thread and
9448 * dispatching the connection to it by emitting the
9449 * #GThreadedSocketService::run signal in the new thread.
9451 * The signal handler may perform blocking IO and need not return
9452 * until the connection is closed.
9454 * The service is implemented using a thread pool, so there is a
9455 * limited amount of threads available to serve incoming requests.
9456 * The service automatically stops the #GSocketService from accepting
9457 * new connections when all threads are busy.
9459 * As with #GSocketService, you may connect to #GThreadedSocketService::run,
9460 * or subclass and override the default handler.
9466 * @title: TLS Overview
9467 * @short_description: TLS (aka SSL) support for GSocketConnection
9468 * @include: gio/gio.h
9470 * #GTlsConnection and related classes provide TLS (Transport Layer
9471 * Security, previously known as SSL, Secure Sockets Layer) support for
9472 * gio-based network streams.
9474 * #GDtlsConnection and related classes provide DTLS (Datagram TLS) support for
9475 * GIO-based network sockets, using the #GDatagramBased interface. The TLS and
9476 * DTLS APIs are almost identical, except TLS is stream-based and DTLS is
9477 * datagram-based. They share certificate and backend infrastructure.
9479 * In the simplest case, for a client TLS connection, you can just set the
9480 * #GSocketClient:tls flag on a #GSocketClient, and then any
9481 * connections created by that client will have TLS negotiated
9482 * automatically, using appropriate default settings, and rejecting
9483 * any invalid or self-signed certificates (unless you change that
9484 * default by setting the #GSocketClient:tls-validation-flags
9485 * property). The returned object will be a #GTcpWrapperConnection,
9486 * which wraps the underlying #GTlsClientConnection.
9488 * For greater control, you can create your own #GTlsClientConnection,
9489 * wrapping a #GSocketConnection (or an arbitrary #GIOStream with
9490 * pollable input and output streams) and then connect to its signals,
9491 * such as #GTlsConnection::accept-certificate, before starting the
9494 * Server-side TLS is similar, using #GTlsServerConnection. At the
9495 * moment, there is no support for automatically wrapping server-side
9496 * connections in the way #GSocketClient does for client-side
9502 * SECTION:gtlsbackend
9503 * @title: GTlsBackend
9504 * @short_description: TLS backend implementation
9505 * @include: gio/gio.h
9507 * TLS (Transport Layer Security, aka SSL) and DTLS backend.
9514 * SECTION:gtlscertificate
9515 * @title: GTlsCertificate
9516 * @short_description: TLS certificate
9517 * @include: gio/gio.h
9518 * @see_also: #GTlsConnection
9520 * A certificate used for TLS authentication and encryption.
9521 * This can represent either a certificate only (eg, the certificate
9522 * received by a client from a server), or the combination of
9523 * a certificate and a private key (which is needed when acting as a
9524 * #GTlsServerConnection).
9531 * SECTION:gtlsclientconnection
9532 * @short_description: TLS client-side connection
9533 * @include: gio/gio.h
9535 * #GTlsClientConnection is the client-side subclass of
9536 * #GTlsConnection, representing a client-side TLS connection.
9541 * SECTION:gtlsconnection
9542 * @short_description: TLS connection type
9543 * @include: gio/gio.h
9545 * #GTlsConnection is the base TLS connection class type, which wraps
9546 * a #GIOStream and provides TLS encryption on top of it. Its
9547 * subclasses, #GTlsClientConnection and #GTlsServerConnection,
9548 * implement client-side and server-side TLS, respectively.
9550 * For DTLS (Datagram TLS) support, see #GDtlsConnection.
9557 * SECTION:gtlsdatabase
9558 * @short_description: TLS database type
9559 * @include: gio/gio.h
9561 * #GTlsDatabase is used to lookup certificates and other information
9562 * from a certificate or key store. It is an abstract base class which
9563 * TLS library specific subtypes override.
9565 * Most common client applications will not directly interact with
9566 * #GTlsDatabase. It is used internally by #GTlsConnection.
9573 * SECTION:gtlsfiledatabase
9574 * @short_description: TLS file based database type
9575 * @include: gio/gio.h
9577 * #GTlsFileDatabase is implemented by #GTlsDatabase objects which load
9578 * their certificate information from a file. It is an interface which
9579 * TLS library specific subtypes implement.
9586 * SECTION:gtlsinteraction
9587 * @short_description: Interaction with the user during TLS operations.
9588 * @include: gio/gio.h
9590 * #GTlsInteraction provides a mechanism for the TLS connection and database
9591 * code to interact with the user. It can be used to ask the user for passwords.
9593 * To use a #GTlsInteraction with a TLS connection use
9594 * g_tls_connection_set_interaction().
9596 * Callers should instantiate a derived class that implements the various
9597 * interaction methods to show the required dialogs.
9599 * Callers should use the 'invoke' functions like
9600 * g_tls_interaction_invoke_ask_password() to run interaction methods. These
9601 * functions make sure that the interaction is invoked in the main loop
9602 * and not in the current thread, if the current thread is not running the
9605 * Derived classes can choose to implement whichever interactions methods they'd
9606 * like to support by overriding those virtual methods in their class
9607 * initialization function. Any interactions not implemented will return
9608 * %G_TLS_INTERACTION_UNHANDLED. If a derived class implements an async method,
9609 * it must also implement the corresponding finish method.
9614 * SECTION:gtlspassword
9615 * @title: GTlsPassword
9616 * @short_description: TLS Passwords for prompting
9617 * @include: gio/gio.h
9619 * Holds a password used in TLS.
9624 * SECTION:gtlsserverconnection
9625 * @short_description: TLS server-side connection
9626 * @include: gio/gio.h
9628 * #GTlsServerConnection is the server-side subclass of #GTlsConnection,
9629 * representing a server-side TLS connection.
9636 * SECTION:gunixconnection
9637 * @title: GUnixConnection
9638 * @short_description: A UNIX domain GSocketConnection
9639 * @include: gio/gunixconnection.h
9640 * @see_also: #GSocketConnection.
9642 * This is the subclass of #GSocketConnection that is created
9643 * for UNIX domain sockets.
9645 * It contains functions to do some of the UNIX socket specific
9646 * functionality like passing file descriptors.
9648 * Note that `<gio/gunixconnection.h>` belongs to the UNIX-specific
9649 * GIO interfaces, thus you have to use the `gio-unix-2.0.pc`
9650 * pkg-config file when using it.
9657 * SECTION:gunixcredentialsmessage
9658 * @title: GUnixCredentialsMessage
9659 * @short_description: A GSocketControlMessage containing credentials
9660 * @include: gio/gunixcredentialsmessage.h
9661 * @see_also: #GUnixConnection, #GSocketControlMessage
9663 * This #GSocketControlMessage contains a #GCredentials instance. It
9664 * may be sent using g_socket_send_message() and received using
9665 * g_socket_receive_message() over UNIX sockets (ie: sockets in the
9666 * %G_SOCKET_FAMILY_UNIX family).
9668 * For an easier way to send and receive credentials over
9669 * stream-oriented UNIX sockets, see
9670 * g_unix_connection_send_credentials() and
9671 * g_unix_connection_receive_credentials(). To receive credentials of
9672 * a foreign process connected to a socket, use
9673 * g_socket_get_credentials().
9678 * SECTION:gunixfdlist
9679 * @title: GUnixFDList
9680 * @short_description: An object containing a set of UNIX file descriptors
9681 * @include: gio/gunixfdlist.h
9682 * @see_also: #GUnixFDMessage
9684 * A #GUnixFDList contains a list of file descriptors. It owns the file
9685 * descriptors that it contains, closing them when finalized.
9687 * It may be wrapped in a #GUnixFDMessage and sent over a #GSocket in
9688 * the %G_SOCKET_ADDRESS_UNIX family by using g_socket_send_message()
9689 * and received using g_socket_receive_message().
9691 * Note that `<gio/gunixfdlist.h>` belongs to the UNIX-specific GIO
9692 * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config
9693 * file when using it.
9698 * SECTION:gunixfdmessage
9699 * @title: GUnixFDMessage
9700 * @short_description: A GSocketControlMessage containing a GUnixFDList
9701 * @include: gio/gunixfdmessage.h
9702 * @see_also: #GUnixConnection, #GUnixFDList, #GSocketControlMessage
9704 * This #GSocketControlMessage contains a #GUnixFDList.
9705 * It may be sent using g_socket_send_message() and received using
9706 * g_socket_receive_message() over UNIX sockets (ie: sockets in the
9707 * %G_SOCKET_ADDRESS_UNIX family). The file descriptors are copied
9708 * between processes by the kernel.
9710 * For an easier way to send and receive file descriptors over
9711 * stream-oriented UNIX sockets, see g_unix_connection_send_fd() and
9712 * g_unix_connection_receive_fd().
9714 * Note that `<gio/gunixfdmessage.h>` belongs to the UNIX-specific GIO
9715 * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config
9716 * file when using it.
9721 * SECTION:gunixinputstream
9722 * @short_description: Streaming input operations for UNIX file descriptors
9723 * @include: gio/gunixinputstream.h
9724 * @see_also: #GInputStream
9726 * #GUnixInputStream implements #GInputStream for reading from a UNIX
9727 * file descriptor, including asynchronous operations. (If the file
9728 * descriptor refers to a socket or pipe, this will use poll() to do
9729 * asynchronous I/O. If it refers to a regular file, it will fall back
9730 * to doing asynchronous I/O in another thread.)
9732 * Note that `<gio/gunixinputstream.h>` belongs to the UNIX-specific GIO
9733 * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config
9734 * file when using it.
9739 * SECTION:gunixmounts
9740 * @include: gio/gunixmounts.h
9741 * @short_description: UNIX mounts
9743 * Routines for managing mounted UNIX mount points and paths.
9745 * Note that `<gio/gunixmounts.h>` belongs to the UNIX-specific GIO
9746 * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config
9747 * file when using it.
9752 * SECTION:gunixoutputstream
9753 * @short_description: Streaming output operations for UNIX file descriptors
9754 * @include: gio/gunixoutputstream.h
9755 * @see_also: #GOutputStream
9757 * #GUnixOutputStream implements #GOutputStream for writing to a UNIX
9758 * file descriptor, including asynchronous operations. (If the file
9759 * descriptor refers to a socket or pipe, this will use poll() to do
9760 * asynchronous I/O. If it refers to a regular file, it will fall back
9761 * to doing asynchronous I/O in another thread.)
9763 * Note that `<gio/gunixoutputstream.h>` belongs to the UNIX-specific GIO
9764 * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config file
9770 * SECTION:gunixsocketaddress
9771 * @short_description: UNIX GSocketAddress
9772 * @include: gio/gunixsocketaddress.h
9774 * Support for UNIX-domain (also known as local) sockets.
9776 * UNIX domain sockets are generally visible in the filesystem.
9777 * However, some systems support abstract socket names which are not
9778 * visible in the filesystem and not affected by the filesystem
9779 * permissions, visibility, etc. Currently this is only supported
9780 * under Linux. If you attempt to use abstract sockets on other
9781 * systems, function calls may return %G_IO_ERROR_NOT_SUPPORTED
9782 * errors. You can use g_unix_socket_address_abstract_names_supported()
9783 * to see if abstract names are supported.
9785 * Note that `<gio/gunixsocketaddress.h>` belongs to the UNIX-specific GIO
9786 * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config file
9793 * @short_description: Virtual File System
9794 * @include: gio/gio.h
9796 * Entry point for using GIO functionality.
9802 * @short_description: Volume management
9803 * @include: gio/gio.h
9805 * The #GVolume interface represents user-visible objects that can be
9806 * mounted. Note, when porting from GnomeVFS, #GVolume is the moral
9807 * equivalent of #GnomeVFSDrive.
9809 * Mounting a #GVolume instance is an asynchronous operation. For more
9810 * information about asynchronous operations, see #GAsyncResult and
9811 * #GTask. To mount a #GVolume, first call g_volume_mount() with (at
9812 * least) the #GVolume instance, optionally a #GMountOperation object
9813 * and a #GAsyncReadyCallback.
9815 * Typically, one will only want to pass %NULL for the
9816 * #GMountOperation if automounting all volumes when a desktop session
9817 * starts since it's not desirable to put up a lot of dialogs asking
9820 * The callback will be fired when the operation has resolved (either
9821 * with success or failure), and a #GAsyncReady structure will be
9822 * passed to the callback. That callback should then call
9823 * g_volume_mount_finish() with the #GVolume instance and the
9824 * #GAsyncReady data to see if the operation was completed
9825 * successfully. If an @error is present when g_volume_mount_finish()
9826 * is called, then it will be filled with any error information.
9828 * ## Volume Identifiers # {#volume-identifier}
9830 * It is sometimes necessary to directly access the underlying
9831 * operating system object behind a volume (e.g. for passing a volume
9832 * to an application via the commandline). For this purpose, GIO
9833 * allows to obtain an 'identifier' for the volume. There can be
9834 * different kinds of identifiers, such as Hal UDIs, filesystem labels,
9835 * traditional Unix devices (e.g. `/dev/sda2`), UUIDs. GIO uses predefined
9836 * strings as names for the different kinds of identifiers:
9837 * #G_VOLUME_IDENTIFIER_KIND_HAL_UDI, #G_VOLUME_IDENTIFIER_KIND_LABEL, etc.
9838 * Use g_volume_get_identifier() to obtain an identifier for a volume.
9841 * Note that #G_VOLUME_IDENTIFIER_KIND_HAL_UDI will only be available
9842 * when the gvfs hal volume monitor is in use. Other volume monitors
9843 * will generally be able to provide the #G_VOLUME_IDENTIFIER_KIND_UNIX_DEVICE
9844 * identifier, which can be used to obtain a hal device by means of
9845 * libhal_manager_find_device_string_match().
9850 * SECTION:gvolumemonitor
9851 * @short_description: Volume Monitor
9852 * @include: gio/gio.h
9853 * @see_also: #GFileMonitor
9855 * #GVolumeMonitor is for listing the user interesting devices and volumes
9856 * on the computer. In other words, what a file selector or file manager
9857 * would show in a sidebar.
9859 * #GVolumeMonitor is not
9860 * [thread-default-context aware][g-main-context-push-thread-default],
9861 * and so should not be used other than from the main thread, with no
9862 * thread-default-context active.
9867 * SECTION:gwin32inputstream
9868 * @short_description: Streaming input operations for Windows file handles
9869 * @include: gio/gwin32inputstream.h
9870 * @see_also: #GInputStream
9872 * #GWin32InputStream implements #GInputStream for reading from a
9873 * Windows file handle.
9875 * Note that `<gio/gwin32inputstream.h>` belongs to the Windows-specific GIO
9876 * interfaces, thus you have to use the `gio-windows-2.0.pc` pkg-config file
9882 * SECTION:gwin32outputstream
9883 * @short_description: Streaming output operations for Windows file handles
9884 * @include: gio/gwin32outputstream.h
9885 * @see_also: #GOutputStream
9887 * #GWin32OutputStream implements #GOutputStream for writing to a
9888 * Windows file handle.
9890 * Note that `<gio/gwin32outputstream.h>` belongs to the Windows-specific GIO
9891 * interfaces, thus you have to use the `gio-windows-2.0.pc` pkg-config file
9897 * SECTION:gwin32registrykey
9898 * @title: GWin32RegistryKey
9899 * @short_description: W32 registry access helper
9900 * @include: gio/win32/gwin32registrykey.h
9902 * #GWin32RegistryKey represents a single Windows Registry key.
9904 * #GWin32RegistryKey is used by a number of helper functions that read
9905 * Windows Registry. All keys are opened with read-only access, and at
9906 * the moment there is no API for writing into registry keys or creating
9909 * #GWin32RegistryKey implements the #GInitable interface, so if it is manually
9910 * constructed by e.g. g_object_new() you must call g_initable_init() and check
9911 * the results before using the object. This is done automatically
9912 * in g_win32_registry_key_new() and g_win32_registry_key_get_child(), so these
9913 * functions can return %NULL.
9915 * To increase efficiency, a UTF-16 variant is available for all functions
9916 * that deal with key or value names in the registry. Use these to perform
9917 * deep registry queries or other operations that require querying a name
9918 * of a key or a value and then opening it (or querying its data). The use
9919 * of UTF-16 functions avoids the overhead of converting names to UTF-8 and
9922 * All functions operate in current user's context (it is not possible to
9923 * access registry tree of a different user).
9925 * Key paths must use '\\' as a separator, '/' is not supported. Key names
9926 * must not include '\\', because it's used as a separator. Value names
9929 * Key and value names are not case sensitive.
9931 * Full key name (excluding the pre-defined ancestor's name) can't exceed
9932 * 255 UTF-16 characters, give or take. Value name can't exceed 16383 UTF-16
9933 * characters. Tree depth is limited to 512 levels.
9938 * SECTION:gzcompressor
9939 * @short_description: Zlib compressor
9940 * @include: gio/gio.h
9942 * #GZlibCompressor is an implementation of #GConverter that
9943 * compresses data using zlib.
9948 * SECTION:gzdecompressor
9949 * @short_description: Zlib decompressor
9950 * @include: gio/gio.h
9952 * #GZlibDecompressor is an implementation of #GConverter that
9953 * decompresses data compressed with zlib.
9958 * _GFreedesktopDBus:
9960 * Abstract interface type for the D-Bus interface <link linkend="gdbus-interface-org-freedesktop-DBus.top_of_page">org.freedesktop.DBus</link>.
9965 * _GFreedesktopDBus::handle-add-match:
9966 * @object: A #_GFreedesktopDBus.
9967 * @invocation: A #GDBusMethodInvocation.
9968 * @arg_rule: Argument passed by remote caller.
9970 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.AddMatch">AddMatch()</link> D-Bus method.
9972 * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call _g_freedesktop_dbus_complete_add_match() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
9974 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
9979 * _GFreedesktopDBus::handle-get-connection-selinux-security-context:
9980 * @object: A #_GFreedesktopDBus.
9981 * @invocation: A #GDBusMethodInvocation.
9982 * @arg_name: Argument passed by remote caller.
9984 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionSELinuxSecurityContext">GetConnectionSELinuxSecurityContext()</link> D-Bus method.
9986 * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call _g_freedesktop_dbus_complete_get_connection_selinux_security_context() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
9988 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
9993 * _GFreedesktopDBus::handle-get-connection-unix-process-id:
9994 * @object: A #_GFreedesktopDBus.
9995 * @invocation: A #GDBusMethodInvocation.
9996 * @arg_name: Argument passed by remote caller.
9998 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionUnixProcessID">GetConnectionUnixProcessID()</link> D-Bus method.
10000 * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call _g_freedesktop_dbus_complete_get_connection_unix_process_id() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
10002 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
10007 * _GFreedesktopDBus::handle-get-connection-unix-user:
10008 * @object: A #_GFreedesktopDBus.
10009 * @invocation: A #GDBusMethodInvocation.
10010 * @arg_name: Argument passed by remote caller.
10012 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionUnixUser">GetConnectionUnixUser()</link> D-Bus method.
10014 * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call _g_freedesktop_dbus_complete_get_connection_unix_user() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
10016 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
10021 * _GFreedesktopDBus::handle-get-id:
10022 * @object: A #_GFreedesktopDBus.
10023 * @invocation: A #GDBusMethodInvocation.
10025 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.GetId">GetId()</link> D-Bus method.
10027 * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call _g_freedesktop_dbus_complete_get_id() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
10029 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
10034 * _GFreedesktopDBus::handle-get-name-owner:
10035 * @object: A #_GFreedesktopDBus.
10036 * @invocation: A #GDBusMethodInvocation.
10037 * @arg_name: Argument passed by remote caller.
10039 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.GetNameOwner">GetNameOwner()</link> D-Bus method.
10041 * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call _g_freedesktop_dbus_complete_get_name_owner() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
10043 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
10048 * _GFreedesktopDBus::handle-hello:
10049 * @object: A #_GFreedesktopDBus.
10050 * @invocation: A #GDBusMethodInvocation.
10052 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.Hello">Hello()</link> D-Bus method.
10054 * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call _g_freedesktop_dbus_complete_hello() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
10056 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
10061 * _GFreedesktopDBus::handle-list-activatable-names:
10062 * @object: A #_GFreedesktopDBus.
10063 * @invocation: A #GDBusMethodInvocation.
10065 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.ListActivatableNames">ListActivatableNames()</link> D-Bus method.
10067 * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call _g_freedesktop_dbus_complete_list_activatable_names() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
10069 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
10074 * _GFreedesktopDBus::handle-list-names:
10075 * @object: A #_GFreedesktopDBus.
10076 * @invocation: A #GDBusMethodInvocation.
10078 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.ListNames">ListNames()</link> D-Bus method.
10080 * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call _g_freedesktop_dbus_complete_list_names() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
10082 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
10087 * _GFreedesktopDBus::handle-list-queued-owners:
10088 * @object: A #_GFreedesktopDBus.
10089 * @invocation: A #GDBusMethodInvocation.
10090 * @arg_name: Argument passed by remote caller.
10092 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.ListQueuedOwners">ListQueuedOwners()</link> D-Bus method.
10094 * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call _g_freedesktop_dbus_complete_list_queued_owners() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
10096 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
10101 * _GFreedesktopDBus::handle-name-has-owner:
10102 * @object: A #_GFreedesktopDBus.
10103 * @invocation: A #GDBusMethodInvocation.
10104 * @arg_name: Argument passed by remote caller.
10106 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.NameHasOwner">NameHasOwner()</link> D-Bus method.
10108 * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call _g_freedesktop_dbus_complete_name_has_owner() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
10110 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
10115 * _GFreedesktopDBus::handle-release-name:
10116 * @object: A #_GFreedesktopDBus.
10117 * @invocation: A #GDBusMethodInvocation.
10118 * @arg_name: Argument passed by remote caller.
10120 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.ReleaseName">ReleaseName()</link> D-Bus method.
10122 * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call _g_freedesktop_dbus_complete_release_name() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
10124 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
10129 * _GFreedesktopDBus::handle-reload-config:
10130 * @object: A #_GFreedesktopDBus.
10131 * @invocation: A #GDBusMethodInvocation.
10133 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.ReloadConfig">ReloadConfig()</link> D-Bus method.
10135 * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call _g_freedesktop_dbus_complete_reload_config() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
10137 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
10142 * _GFreedesktopDBus::handle-remove-match:
10143 * @object: A #_GFreedesktopDBus.
10144 * @invocation: A #GDBusMethodInvocation.
10145 * @arg_rule: Argument passed by remote caller.
10147 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.RemoveMatch">RemoveMatch()</link> D-Bus method.
10149 * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call _g_freedesktop_dbus_complete_remove_match() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
10151 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
10156 * _GFreedesktopDBus::handle-request-name:
10157 * @object: A #_GFreedesktopDBus.
10158 * @invocation: A #GDBusMethodInvocation.
10159 * @arg_name: Argument passed by remote caller.
10160 * @arg_flags: Argument passed by remote caller.
10162 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.RequestName">RequestName()</link> D-Bus method.
10164 * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call _g_freedesktop_dbus_complete_request_name() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
10166 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
10171 * _GFreedesktopDBus::handle-start-service-by-name:
10172 * @object: A #_GFreedesktopDBus.
10173 * @invocation: A #GDBusMethodInvocation.
10174 * @arg_name: Argument passed by remote caller.
10175 * @arg_flags: Argument passed by remote caller.
10177 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.StartServiceByName">StartServiceByName()</link> D-Bus method.
10179 * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call _g_freedesktop_dbus_complete_start_service_by_name() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
10181 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
10186 * _GFreedesktopDBus::handle-update-activation-environment:
10187 * @object: A #_GFreedesktopDBus.
10188 * @invocation: A #GDBusMethodInvocation.
10189 * @arg_environment: Argument passed by remote caller.
10191 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.UpdateActivationEnvironment">UpdateActivationEnvironment()</link> D-Bus method.
10193 * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call _g_freedesktop_dbus_complete_update_activation_environment() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
10195 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
10200 * _GFreedesktopDBus::name-acquired:
10201 * @object: A #_GFreedesktopDBus.
10202 * @arg_name: Argument.
10204 * On the client-side, this signal is emitted whenever the D-Bus signal <link linkend="gdbus-signal-org-freedesktop-DBus.NameAcquired">"NameAcquired"</link> is received.
10206 * On the service-side, this signal can be used with e.g. g_signal_emit_by_name() to make the object emit the D-Bus signal.
10211 * _GFreedesktopDBus::name-lost:
10212 * @object: A #_GFreedesktopDBus.
10213 * @arg_name: Argument.
10215 * On the client-side, this signal is emitted whenever the D-Bus signal <link linkend="gdbus-signal-org-freedesktop-DBus.NameLost">"NameLost"</link> is received.
10217 * On the service-side, this signal can be used with e.g. g_signal_emit_by_name() to make the object emit the D-Bus signal.
10222 * _GFreedesktopDBus::name-owner-changed:
10223 * @object: A #_GFreedesktopDBus.
10224 * @arg_name: Argument.
10225 * @arg_old_owner: Argument.
10226 * @arg_new_owner: Argument.
10228 * On the client-side, this signal is emitted whenever the D-Bus signal <link linkend="gdbus-signal-org-freedesktop-DBus.NameOwnerChanged">"NameOwnerChanged"</link> is received.
10230 * On the service-side, this signal can be used with e.g. g_signal_emit_by_name() to make the object emit the D-Bus signal.
10235 * _GFreedesktopDBusIface:
10236 * @parent_iface: The parent interface.
10237 * @handle_add_match: Handler for the #_GFreedesktopDBus::handle-add-match signal.
10238 * @handle_get_connection_selinux_security_context: Handler for the #_GFreedesktopDBus::handle-get-connection-selinux-security-context signal.
10239 * @handle_get_connection_unix_process_id: Handler for the #_GFreedesktopDBus::handle-get-connection-unix-process-id signal.
10240 * @handle_get_connection_unix_user: Handler for the #_GFreedesktopDBus::handle-get-connection-unix-user signal.
10241 * @handle_get_id: Handler for the #_GFreedesktopDBus::handle-get-id signal.
10242 * @handle_get_name_owner: Handler for the #_GFreedesktopDBus::handle-get-name-owner signal.
10243 * @handle_hello: Handler for the #_GFreedesktopDBus::handle-hello signal.
10244 * @handle_list_activatable_names: Handler for the #_GFreedesktopDBus::handle-list-activatable-names signal.
10245 * @handle_list_names: Handler for the #_GFreedesktopDBus::handle-list-names signal.
10246 * @handle_list_queued_owners: Handler for the #_GFreedesktopDBus::handle-list-queued-owners signal.
10247 * @handle_name_has_owner: Handler for the #_GFreedesktopDBus::handle-name-has-owner signal.
10248 * @handle_release_name: Handler for the #_GFreedesktopDBus::handle-release-name signal.
10249 * @handle_reload_config: Handler for the #_GFreedesktopDBus::handle-reload-config signal.
10250 * @handle_remove_match: Handler for the #_GFreedesktopDBus::handle-remove-match signal.
10251 * @handle_request_name: Handler for the #_GFreedesktopDBus::handle-request-name signal.
10252 * @handle_start_service_by_name: Handler for the #_GFreedesktopDBus::handle-start-service-by-name signal.
10253 * @handle_update_activation_environment: Handler for the #_GFreedesktopDBus::handle-update-activation-environment signal.
10254 * @name_acquired: Handler for the #_GFreedesktopDBus::name-acquired signal.
10255 * @name_lost: Handler for the #_GFreedesktopDBus::name-lost signal.
10256 * @name_owner_changed: Handler for the #_GFreedesktopDBus::name-owner-changed signal.
10258 * Virtual table for the D-Bus interface <link linkend="gdbus-interface-org-freedesktop-DBus.top_of_page">org.freedesktop.DBus</link>.
10263 * _GFreedesktopDBusProxy:
10265 * The #_GFreedesktopDBusProxy structure contains only private data and should only be accessed using the provided API.
10270 * _GFreedesktopDBusProxyClass:
10271 * @parent_class: The parent class.
10273 * Class structure for #_GFreedesktopDBusProxy.
10278 * _GFreedesktopDBusSkeleton:
10280 * The #_GFreedesktopDBusSkeleton structure contains only private data and should only be accessed using the provided API.
10285 * _GFreedesktopDBusSkeletonClass:
10286 * @parent_class: The parent class.
10288 * Class structure for #_GFreedesktopDBusSkeleton.
10293 * _g_dbus_initialize:
10295 * Does various one-time init things such as
10297 * - registering the G_DBUS_ERROR error domain
10298 * - parses the G_DBUS_DEBUG environment variable
10303 * _g_file_attribute_value_as_string:
10304 * @attr: a #GFileAttributeValue.
10306 * Converts a #GFileAttributeValue to a string for display.
10307 * The returned string should be freed when no longer needed.
10309 * Returns: a string from the @attr, %NULL on error, or "<invalid>"
10310 * if @attr is of type %G_FILE_ATTRIBUTE_TYPE_INVALID.
10315 * _g_file_attribute_value_clear:
10316 * @attr: a #GFileAttributeValue.
10318 * Clears the value of @attr and sets its type to
10319 * %G_FILE_ATTRIBUTE_TYPE_INVALID.
10324 * _g_file_attribute_value_free:
10325 * @attr: a #GFileAttributeValue.
10327 * Frees the memory used by @attr.
10332 * _g_file_attribute_value_get_boolean:
10333 * @attr: a #GFileAttributeValue.
10335 * Gets the boolean value from a file attribute value. If the value is not the
10336 * right type then %FALSE will be returned.
10338 * Returns: the boolean value contained within the attribute, or %FALSE.
10343 * _g_file_attribute_value_get_byte_string:
10344 * @attr: a #GFileAttributeValue.
10346 * Gets the byte string from a file attribute value. If the value is not the
10347 * right type then %NULL will be returned.
10349 * Returns: the byte string contained within the attribute or %NULL.
10354 * _g_file_attribute_value_get_int32:
10355 * @attr: a #GFileAttributeValue.
10357 * Gets the signed 32-bit integer from a file attribute value. If the value
10358 * is not the right type then 0 will be returned.
10360 * Returns: the signed 32-bit integer from the attribute, or 0.
10365 * _g_file_attribute_value_get_int64:
10366 * @attr: a #GFileAttributeValue.
10368 * Gets the signed 64-bit integer from a file attribute value. If the value
10369 * is not the right type then 0 will be returned.
10371 * Returns: the signed 64-bit integer from the attribute, or 0.
10376 * _g_file_attribute_value_get_object:
10377 * @attr: a #GFileAttributeValue.
10379 * Gets the GObject from a file attribute value. If the value
10380 * is not the right type then %NULL will be returned.
10382 * Returns: the GObject from the attribute, or %NULL.
10387 * _g_file_attribute_value_get_string:
10388 * @attr: a #GFileAttributeValue.
10390 * Gets the string from a file attribute value. If the value is not the
10391 * right type then %NULL will be returned.
10393 * Returns: the UTF-8 string value contained within the attribute, or %NULL.
10398 * _g_file_attribute_value_get_uint32:
10399 * @attr: a #GFileAttributeValue.
10401 * Gets the unsigned 32-bit integer from a file attribute value. If the value
10402 * is not the right type then 0 will be returned.
10404 * Returns: the unsigned 32-bit integer from the attribute, or 0.
10409 * _g_file_attribute_value_get_uint64:
10410 * @attr: a #GFileAttributeValue.
10412 * Gets the unsigned 64-bit integer from a file attribute value. If the value
10413 * is not the right type then 0 will be returned.
10415 * Returns: the unsigned 64-bit integer from the attribute, or 0.
10420 * _g_file_attribute_value_new:
10422 * Creates a new file attribute.
10424 * Returns: a #GFileAttributeValue.
10429 * _g_file_attribute_value_set_boolean:
10430 * @attr: a #GFileAttributeValue.
10431 * @value: a #gboolean to set within the type.
10433 * Sets the attribute value to the given boolean value.
10438 * _g_file_attribute_value_set_byte_string:
10439 * @attr: a #GFileAttributeValue.
10440 * @string: a byte string to set within the type.
10442 * Sets the attribute value to a given byte string.
10447 * _g_file_attribute_value_set_int32:
10448 * @attr: a #GFileAttributeValue.
10449 * @value: a #gint32 to set within the type.
10451 * Sets the attribute value to the given signed 32-bit integer.
10456 * _g_file_attribute_value_set_int64:
10457 * @attr: a #GFileAttributeValue.
10458 * @value: a #gint64 to set within the type.
10460 * Sets the attribute value to a given signed 64-bit integer.
10465 * _g_file_attribute_value_set_object:
10466 * @attr: a #GFileAttributeValue.
10467 * @obj: a #GObject.
10469 * Sets the attribute to contain the value @obj.
10470 * The @attr references the GObject internally.
10475 * _g_file_attribute_value_set_string:
10476 * @attr: a #GFileAttributeValue.
10477 * @string: a UTF-8 string to set within the type.
10479 * Sets the attribute value to a given UTF-8 string.
10484 * _g_file_attribute_value_set_uint32:
10485 * @attr: a #GFileAttributeValue.
10486 * @value: a #guint32 to set within the type.
10488 * Sets the attribute value to the given unsigned 32-bit integer.
10493 * _g_file_attribute_value_set_uint64:
10494 * @attr: a #GFileAttributeValue.
10495 * @value: a #guint64 to set within the type.
10497 * Sets the attribute value to a given unsigned 64-bit integer.
10502 * _g_freedesktop_dbus_call_add_match:
10503 * @proxy: A #_GFreedesktopDBusProxy.
10504 * @arg_rule: Argument to pass with the method invocation.
10505 * @cancellable: (allow-none): A #GCancellable or %NULL.
10506 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
10507 * @user_data: User data to pass to @callback.
10509 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.AddMatch">AddMatch()</link> D-Bus method on @proxy.
10510 * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from.
10511 * You can then call _g_freedesktop_dbus_call_add_match_finish() to get the result of the operation.
10513 * See _g_freedesktop_dbus_call_add_match_sync() for the synchronous, blocking version of this method.
10518 * _g_freedesktop_dbus_call_add_match_finish:
10519 * @proxy: A #_GFreedesktopDBusProxy.
10520 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_add_match().
10521 * @error: Return location for error or %NULL.
10523 * Finishes an operation started with _g_freedesktop_dbus_call_add_match().
10525 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
10530 * _g_freedesktop_dbus_call_add_match_sync:
10531 * @proxy: A #_GFreedesktopDBusProxy.
10532 * @arg_rule: Argument to pass with the method invocation.
10533 * @cancellable: (allow-none): A #GCancellable or %NULL.
10534 * @error: Return location for error or %NULL.
10536 * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.AddMatch">AddMatch()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
10538 * See _g_freedesktop_dbus_call_add_match() for the asynchronous version of this method.
10540 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
10545 * _g_freedesktop_dbus_call_get_connection_selinux_security_context:
10546 * @proxy: A #_GFreedesktopDBusProxy.
10547 * @arg_name: Argument to pass with the method invocation.
10548 * @cancellable: (allow-none): A #GCancellable or %NULL.
10549 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
10550 * @user_data: User data to pass to @callback.
10552 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionSELinuxSecurityContext">GetConnectionSELinuxSecurityContext()</link> D-Bus method on @proxy.
10553 * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from.
10554 * You can then call _g_freedesktop_dbus_call_get_connection_selinux_security_context_finish() to get the result of the operation.
10556 * See _g_freedesktop_dbus_call_get_connection_selinux_security_context_sync() for the synchronous, blocking version of this method.
10561 * _g_freedesktop_dbus_call_get_connection_selinux_security_context_finish:
10562 * @proxy: A #_GFreedesktopDBusProxy.
10563 * @out_security_context: (out): Return location for return parameter or %NULL to ignore.
10564 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_get_connection_selinux_security_context().
10565 * @error: Return location for error or %NULL.
10567 * Finishes an operation started with _g_freedesktop_dbus_call_get_connection_selinux_security_context().
10569 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
10574 * _g_freedesktop_dbus_call_get_connection_selinux_security_context_sync:
10575 * @proxy: A #_GFreedesktopDBusProxy.
10576 * @arg_name: Argument to pass with the method invocation.
10577 * @out_security_context: (out): Return location for return parameter or %NULL to ignore.
10578 * @cancellable: (allow-none): A #GCancellable or %NULL.
10579 * @error: Return location for error or %NULL.
10581 * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionSELinuxSecurityContext">GetConnectionSELinuxSecurityContext()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
10583 * See _g_freedesktop_dbus_call_get_connection_selinux_security_context() for the asynchronous version of this method.
10585 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
10590 * _g_freedesktop_dbus_call_get_connection_unix_process_id:
10591 * @proxy: A #_GFreedesktopDBusProxy.
10592 * @arg_name: Argument to pass with the method invocation.
10593 * @cancellable: (allow-none): A #GCancellable or %NULL.
10594 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
10595 * @user_data: User data to pass to @callback.
10597 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionUnixProcessID">GetConnectionUnixProcessID()</link> D-Bus method on @proxy.
10598 * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from.
10599 * You can then call _g_freedesktop_dbus_call_get_connection_unix_process_id_finish() to get the result of the operation.
10601 * See _g_freedesktop_dbus_call_get_connection_unix_process_id_sync() for the synchronous, blocking version of this method.
10606 * _g_freedesktop_dbus_call_get_connection_unix_process_id_finish:
10607 * @proxy: A #_GFreedesktopDBusProxy.
10608 * @out_pid: (out): Return location for return parameter or %NULL to ignore.
10609 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_get_connection_unix_process_id().
10610 * @error: Return location for error or %NULL.
10612 * Finishes an operation started with _g_freedesktop_dbus_call_get_connection_unix_process_id().
10614 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
10619 * _g_freedesktop_dbus_call_get_connection_unix_process_id_sync:
10620 * @proxy: A #_GFreedesktopDBusProxy.
10621 * @arg_name: Argument to pass with the method invocation.
10622 * @out_pid: (out): Return location for return parameter or %NULL to ignore.
10623 * @cancellable: (allow-none): A #GCancellable or %NULL.
10624 * @error: Return location for error or %NULL.
10626 * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionUnixProcessID">GetConnectionUnixProcessID()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
10628 * See _g_freedesktop_dbus_call_get_connection_unix_process_id() for the asynchronous version of this method.
10630 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
10635 * _g_freedesktop_dbus_call_get_connection_unix_user:
10636 * @proxy: A #_GFreedesktopDBusProxy.
10637 * @arg_name: Argument to pass with the method invocation.
10638 * @cancellable: (allow-none): A #GCancellable or %NULL.
10639 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
10640 * @user_data: User data to pass to @callback.
10642 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionUnixUser">GetConnectionUnixUser()</link> D-Bus method on @proxy.
10643 * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from.
10644 * You can then call _g_freedesktop_dbus_call_get_connection_unix_user_finish() to get the result of the operation.
10646 * See _g_freedesktop_dbus_call_get_connection_unix_user_sync() for the synchronous, blocking version of this method.
10651 * _g_freedesktop_dbus_call_get_connection_unix_user_finish:
10652 * @proxy: A #_GFreedesktopDBusProxy.
10653 * @out_uid: (out): Return location for return parameter or %NULL to ignore.
10654 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_get_connection_unix_user().
10655 * @error: Return location for error or %NULL.
10657 * Finishes an operation started with _g_freedesktop_dbus_call_get_connection_unix_user().
10659 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
10664 * _g_freedesktop_dbus_call_get_connection_unix_user_sync:
10665 * @proxy: A #_GFreedesktopDBusProxy.
10666 * @arg_name: Argument to pass with the method invocation.
10667 * @out_uid: (out): Return location for return parameter or %NULL to ignore.
10668 * @cancellable: (allow-none): A #GCancellable or %NULL.
10669 * @error: Return location for error or %NULL.
10671 * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionUnixUser">GetConnectionUnixUser()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
10673 * See _g_freedesktop_dbus_call_get_connection_unix_user() for the asynchronous version of this method.
10675 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
10680 * _g_freedesktop_dbus_call_get_id:
10681 * @proxy: A #_GFreedesktopDBusProxy.
10682 * @cancellable: (allow-none): A #GCancellable or %NULL.
10683 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
10684 * @user_data: User data to pass to @callback.
10686 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.GetId">GetId()</link> D-Bus method on @proxy.
10687 * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from.
10688 * You can then call _g_freedesktop_dbus_call_get_id_finish() to get the result of the operation.
10690 * See _g_freedesktop_dbus_call_get_id_sync() for the synchronous, blocking version of this method.
10695 * _g_freedesktop_dbus_call_get_id_finish:
10696 * @proxy: A #_GFreedesktopDBusProxy.
10697 * @out_unique_id: (out): Return location for return parameter or %NULL to ignore.
10698 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_get_id().
10699 * @error: Return location for error or %NULL.
10701 * Finishes an operation started with _g_freedesktop_dbus_call_get_id().
10703 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
10708 * _g_freedesktop_dbus_call_get_id_sync:
10709 * @proxy: A #_GFreedesktopDBusProxy.
10710 * @out_unique_id: (out): Return location for return parameter or %NULL to ignore.
10711 * @cancellable: (allow-none): A #GCancellable or %NULL.
10712 * @error: Return location for error or %NULL.
10714 * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.GetId">GetId()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
10716 * See _g_freedesktop_dbus_call_get_id() for the asynchronous version of this method.
10718 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
10723 * _g_freedesktop_dbus_call_get_name_owner:
10724 * @proxy: A #_GFreedesktopDBusProxy.
10725 * @arg_name: Argument to pass with the method invocation.
10726 * @cancellable: (allow-none): A #GCancellable or %NULL.
10727 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
10728 * @user_data: User data to pass to @callback.
10730 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.GetNameOwner">GetNameOwner()</link> D-Bus method on @proxy.
10731 * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from.
10732 * You can then call _g_freedesktop_dbus_call_get_name_owner_finish() to get the result of the operation.
10734 * See _g_freedesktop_dbus_call_get_name_owner_sync() for the synchronous, blocking version of this method.
10739 * _g_freedesktop_dbus_call_get_name_owner_finish:
10740 * @proxy: A #_GFreedesktopDBusProxy.
10741 * @out_unique_name: (out): Return location for return parameter or %NULL to ignore.
10742 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_get_name_owner().
10743 * @error: Return location for error or %NULL.
10745 * Finishes an operation started with _g_freedesktop_dbus_call_get_name_owner().
10747 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
10752 * _g_freedesktop_dbus_call_get_name_owner_sync:
10753 * @proxy: A #_GFreedesktopDBusProxy.
10754 * @arg_name: Argument to pass with the method invocation.
10755 * @out_unique_name: (out): Return location for return parameter or %NULL to ignore.
10756 * @cancellable: (allow-none): A #GCancellable or %NULL.
10757 * @error: Return location for error or %NULL.
10759 * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.GetNameOwner">GetNameOwner()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
10761 * See _g_freedesktop_dbus_call_get_name_owner() for the asynchronous version of this method.
10763 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
10768 * _g_freedesktop_dbus_call_hello:
10769 * @proxy: A #_GFreedesktopDBusProxy.
10770 * @cancellable: (allow-none): A #GCancellable or %NULL.
10771 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
10772 * @user_data: User data to pass to @callback.
10774 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.Hello">Hello()</link> D-Bus method on @proxy.
10775 * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from.
10776 * You can then call _g_freedesktop_dbus_call_hello_finish() to get the result of the operation.
10778 * See _g_freedesktop_dbus_call_hello_sync() for the synchronous, blocking version of this method.
10783 * _g_freedesktop_dbus_call_hello_finish:
10784 * @proxy: A #_GFreedesktopDBusProxy.
10785 * @out_assigned_name: (out): Return location for return parameter or %NULL to ignore.
10786 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_hello().
10787 * @error: Return location for error or %NULL.
10789 * Finishes an operation started with _g_freedesktop_dbus_call_hello().
10791 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
10796 * _g_freedesktop_dbus_call_hello_sync:
10797 * @proxy: A #_GFreedesktopDBusProxy.
10798 * @out_assigned_name: (out): Return location for return parameter or %NULL to ignore.
10799 * @cancellable: (allow-none): A #GCancellable or %NULL.
10800 * @error: Return location for error or %NULL.
10802 * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.Hello">Hello()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
10804 * See _g_freedesktop_dbus_call_hello() for the asynchronous version of this method.
10806 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
10811 * _g_freedesktop_dbus_call_list_activatable_names:
10812 * @proxy: A #_GFreedesktopDBusProxy.
10813 * @cancellable: (allow-none): A #GCancellable or %NULL.
10814 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
10815 * @user_data: User data to pass to @callback.
10817 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.ListActivatableNames">ListActivatableNames()</link> D-Bus method on @proxy.
10818 * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from.
10819 * You can then call _g_freedesktop_dbus_call_list_activatable_names_finish() to get the result of the operation.
10821 * See _g_freedesktop_dbus_call_list_activatable_names_sync() for the synchronous, blocking version of this method.
10826 * _g_freedesktop_dbus_call_list_activatable_names_finish:
10827 * @proxy: A #_GFreedesktopDBusProxy.
10828 * @out_activatable_names: (out): Return location for return parameter or %NULL to ignore.
10829 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_list_activatable_names().
10830 * @error: Return location for error or %NULL.
10832 * Finishes an operation started with _g_freedesktop_dbus_call_list_activatable_names().
10834 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
10839 * _g_freedesktop_dbus_call_list_activatable_names_sync:
10840 * @proxy: A #_GFreedesktopDBusProxy.
10841 * @out_activatable_names: (out): Return location for return parameter or %NULL to ignore.
10842 * @cancellable: (allow-none): A #GCancellable or %NULL.
10843 * @error: Return location for error or %NULL.
10845 * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.ListActivatableNames">ListActivatableNames()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
10847 * See _g_freedesktop_dbus_call_list_activatable_names() for the asynchronous version of this method.
10849 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
10854 * _g_freedesktop_dbus_call_list_names:
10855 * @proxy: A #_GFreedesktopDBusProxy.
10856 * @cancellable: (allow-none): A #GCancellable or %NULL.
10857 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
10858 * @user_data: User data to pass to @callback.
10860 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.ListNames">ListNames()</link> D-Bus method on @proxy.
10861 * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from.
10862 * You can then call _g_freedesktop_dbus_call_list_names_finish() to get the result of the operation.
10864 * See _g_freedesktop_dbus_call_list_names_sync() for the synchronous, blocking version of this method.
10869 * _g_freedesktop_dbus_call_list_names_finish:
10870 * @proxy: A #_GFreedesktopDBusProxy.
10871 * @out_names: (out): Return location for return parameter or %NULL to ignore.
10872 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_list_names().
10873 * @error: Return location for error or %NULL.
10875 * Finishes an operation started with _g_freedesktop_dbus_call_list_names().
10877 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
10882 * _g_freedesktop_dbus_call_list_names_sync:
10883 * @proxy: A #_GFreedesktopDBusProxy.
10884 * @out_names: (out): Return location for return parameter or %NULL to ignore.
10885 * @cancellable: (allow-none): A #GCancellable or %NULL.
10886 * @error: Return location for error or %NULL.
10888 * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.ListNames">ListNames()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
10890 * See _g_freedesktop_dbus_call_list_names() for the asynchronous version of this method.
10892 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
10897 * _g_freedesktop_dbus_call_list_queued_owners:
10898 * @proxy: A #_GFreedesktopDBusProxy.
10899 * @arg_name: Argument to pass with the method invocation.
10900 * @cancellable: (allow-none): A #GCancellable or %NULL.
10901 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
10902 * @user_data: User data to pass to @callback.
10904 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.ListQueuedOwners">ListQueuedOwners()</link> D-Bus method on @proxy.
10905 * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from.
10906 * You can then call _g_freedesktop_dbus_call_list_queued_owners_finish() to get the result of the operation.
10908 * See _g_freedesktop_dbus_call_list_queued_owners_sync() for the synchronous, blocking version of this method.
10913 * _g_freedesktop_dbus_call_list_queued_owners_finish:
10914 * @proxy: A #_GFreedesktopDBusProxy.
10915 * @out_queued_owners: (out): Return location for return parameter or %NULL to ignore.
10916 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_list_queued_owners().
10917 * @error: Return location for error or %NULL.
10919 * Finishes an operation started with _g_freedesktop_dbus_call_list_queued_owners().
10921 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
10926 * _g_freedesktop_dbus_call_list_queued_owners_sync:
10927 * @proxy: A #_GFreedesktopDBusProxy.
10928 * @arg_name: Argument to pass with the method invocation.
10929 * @out_queued_owners: (out): Return location for return parameter or %NULL to ignore.
10930 * @cancellable: (allow-none): A #GCancellable or %NULL.
10931 * @error: Return location for error or %NULL.
10933 * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.ListQueuedOwners">ListQueuedOwners()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
10935 * See _g_freedesktop_dbus_call_list_queued_owners() for the asynchronous version of this method.
10937 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
10942 * _g_freedesktop_dbus_call_name_has_owner:
10943 * @proxy: A #_GFreedesktopDBusProxy.
10944 * @arg_name: Argument to pass with the method invocation.
10945 * @cancellable: (allow-none): A #GCancellable or %NULL.
10946 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
10947 * @user_data: User data to pass to @callback.
10949 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.NameHasOwner">NameHasOwner()</link> D-Bus method on @proxy.
10950 * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from.
10951 * You can then call _g_freedesktop_dbus_call_name_has_owner_finish() to get the result of the operation.
10953 * See _g_freedesktop_dbus_call_name_has_owner_sync() for the synchronous, blocking version of this method.
10958 * _g_freedesktop_dbus_call_name_has_owner_finish:
10959 * @proxy: A #_GFreedesktopDBusProxy.
10960 * @out_has_owner: (out): Return location for return parameter or %NULL to ignore.
10961 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_name_has_owner().
10962 * @error: Return location for error or %NULL.
10964 * Finishes an operation started with _g_freedesktop_dbus_call_name_has_owner().
10966 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
10971 * _g_freedesktop_dbus_call_name_has_owner_sync:
10972 * @proxy: A #_GFreedesktopDBusProxy.
10973 * @arg_name: Argument to pass with the method invocation.
10974 * @out_has_owner: (out): Return location for return parameter or %NULL to ignore.
10975 * @cancellable: (allow-none): A #GCancellable or %NULL.
10976 * @error: Return location for error or %NULL.
10978 * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.NameHasOwner">NameHasOwner()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
10980 * See _g_freedesktop_dbus_call_name_has_owner() for the asynchronous version of this method.
10982 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
10987 * _g_freedesktop_dbus_call_release_name:
10988 * @proxy: A #_GFreedesktopDBusProxy.
10989 * @arg_name: Argument to pass with the method invocation.
10990 * @cancellable: (allow-none): A #GCancellable or %NULL.
10991 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
10992 * @user_data: User data to pass to @callback.
10994 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.ReleaseName">ReleaseName()</link> D-Bus method on @proxy.
10995 * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from.
10996 * You can then call _g_freedesktop_dbus_call_release_name_finish() to get the result of the operation.
10998 * See _g_freedesktop_dbus_call_release_name_sync() for the synchronous, blocking version of this method.
11003 * _g_freedesktop_dbus_call_release_name_finish:
11004 * @proxy: A #_GFreedesktopDBusProxy.
11005 * @out_value: (out): Return location for return parameter or %NULL to ignore.
11006 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_release_name().
11007 * @error: Return location for error or %NULL.
11009 * Finishes an operation started with _g_freedesktop_dbus_call_release_name().
11011 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
11016 * _g_freedesktop_dbus_call_release_name_sync:
11017 * @proxy: A #_GFreedesktopDBusProxy.
11018 * @arg_name: Argument to pass with the method invocation.
11019 * @out_value: (out): Return location for return parameter or %NULL to ignore.
11020 * @cancellable: (allow-none): A #GCancellable or %NULL.
11021 * @error: Return location for error or %NULL.
11023 * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.ReleaseName">ReleaseName()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
11025 * See _g_freedesktop_dbus_call_release_name() for the asynchronous version of this method.
11027 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
11032 * _g_freedesktop_dbus_call_reload_config:
11033 * @proxy: A #_GFreedesktopDBusProxy.
11034 * @cancellable: (allow-none): A #GCancellable or %NULL.
11035 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
11036 * @user_data: User data to pass to @callback.
11038 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.ReloadConfig">ReloadConfig()</link> D-Bus method on @proxy.
11039 * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from.
11040 * You can then call _g_freedesktop_dbus_call_reload_config_finish() to get the result of the operation.
11042 * See _g_freedesktop_dbus_call_reload_config_sync() for the synchronous, blocking version of this method.
11047 * _g_freedesktop_dbus_call_reload_config_finish:
11048 * @proxy: A #_GFreedesktopDBusProxy.
11049 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_reload_config().
11050 * @error: Return location for error or %NULL.
11052 * Finishes an operation started with _g_freedesktop_dbus_call_reload_config().
11054 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
11059 * _g_freedesktop_dbus_call_reload_config_sync:
11060 * @proxy: A #_GFreedesktopDBusProxy.
11061 * @cancellable: (allow-none): A #GCancellable or %NULL.
11062 * @error: Return location for error or %NULL.
11064 * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.ReloadConfig">ReloadConfig()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
11066 * See _g_freedesktop_dbus_call_reload_config() for the asynchronous version of this method.
11068 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
11073 * _g_freedesktop_dbus_call_remove_match:
11074 * @proxy: A #_GFreedesktopDBusProxy.
11075 * @arg_rule: Argument to pass with the method invocation.
11076 * @cancellable: (allow-none): A #GCancellable or %NULL.
11077 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
11078 * @user_data: User data to pass to @callback.
11080 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.RemoveMatch">RemoveMatch()</link> D-Bus method on @proxy.
11081 * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from.
11082 * You can then call _g_freedesktop_dbus_call_remove_match_finish() to get the result of the operation.
11084 * See _g_freedesktop_dbus_call_remove_match_sync() for the synchronous, blocking version of this method.
11089 * _g_freedesktop_dbus_call_remove_match_finish:
11090 * @proxy: A #_GFreedesktopDBusProxy.
11091 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_remove_match().
11092 * @error: Return location for error or %NULL.
11094 * Finishes an operation started with _g_freedesktop_dbus_call_remove_match().
11096 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
11101 * _g_freedesktop_dbus_call_remove_match_sync:
11102 * @proxy: A #_GFreedesktopDBusProxy.
11103 * @arg_rule: Argument to pass with the method invocation.
11104 * @cancellable: (allow-none): A #GCancellable or %NULL.
11105 * @error: Return location for error or %NULL.
11107 * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.RemoveMatch">RemoveMatch()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
11109 * See _g_freedesktop_dbus_call_remove_match() for the asynchronous version of this method.
11111 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
11116 * _g_freedesktop_dbus_call_request_name:
11117 * @proxy: A #_GFreedesktopDBusProxy.
11118 * @arg_name: Argument to pass with the method invocation.
11119 * @arg_flags: Argument to pass with the method invocation.
11120 * @cancellable: (allow-none): A #GCancellable or %NULL.
11121 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
11122 * @user_data: User data to pass to @callback.
11124 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.RequestName">RequestName()</link> D-Bus method on @proxy.
11125 * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from.
11126 * You can then call _g_freedesktop_dbus_call_request_name_finish() to get the result of the operation.
11128 * See _g_freedesktop_dbus_call_request_name_sync() for the synchronous, blocking version of this method.
11133 * _g_freedesktop_dbus_call_request_name_finish:
11134 * @proxy: A #_GFreedesktopDBusProxy.
11135 * @out_value: (out): Return location for return parameter or %NULL to ignore.
11136 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_request_name().
11137 * @error: Return location for error or %NULL.
11139 * Finishes an operation started with _g_freedesktop_dbus_call_request_name().
11141 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
11146 * _g_freedesktop_dbus_call_request_name_sync:
11147 * @proxy: A #_GFreedesktopDBusProxy.
11148 * @arg_name: Argument to pass with the method invocation.
11149 * @arg_flags: Argument to pass with the method invocation.
11150 * @out_value: (out): Return location for return parameter or %NULL to ignore.
11151 * @cancellable: (allow-none): A #GCancellable or %NULL.
11152 * @error: Return location for error or %NULL.
11154 * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.RequestName">RequestName()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
11156 * See _g_freedesktop_dbus_call_request_name() for the asynchronous version of this method.
11158 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
11163 * _g_freedesktop_dbus_call_start_service_by_name:
11164 * @proxy: A #_GFreedesktopDBusProxy.
11165 * @arg_name: Argument to pass with the method invocation.
11166 * @arg_flags: Argument to pass with the method invocation.
11167 * @cancellable: (allow-none): A #GCancellable or %NULL.
11168 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
11169 * @user_data: User data to pass to @callback.
11171 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.StartServiceByName">StartServiceByName()</link> D-Bus method on @proxy.
11172 * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from.
11173 * You can then call _g_freedesktop_dbus_call_start_service_by_name_finish() to get the result of the operation.
11175 * See _g_freedesktop_dbus_call_start_service_by_name_sync() for the synchronous, blocking version of this method.
11180 * _g_freedesktop_dbus_call_start_service_by_name_finish:
11181 * @proxy: A #_GFreedesktopDBusProxy.
11182 * @out_value: (out): Return location for return parameter or %NULL to ignore.
11183 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_start_service_by_name().
11184 * @error: Return location for error or %NULL.
11186 * Finishes an operation started with _g_freedesktop_dbus_call_start_service_by_name().
11188 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
11193 * _g_freedesktop_dbus_call_start_service_by_name_sync:
11194 * @proxy: A #_GFreedesktopDBusProxy.
11195 * @arg_name: Argument to pass with the method invocation.
11196 * @arg_flags: Argument to pass with the method invocation.
11197 * @out_value: (out): Return location for return parameter or %NULL to ignore.
11198 * @cancellable: (allow-none): A #GCancellable or %NULL.
11199 * @error: Return location for error or %NULL.
11201 * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.StartServiceByName">StartServiceByName()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
11203 * See _g_freedesktop_dbus_call_start_service_by_name() for the asynchronous version of this method.
11205 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
11210 * _g_freedesktop_dbus_call_update_activation_environment:
11211 * @proxy: A #_GFreedesktopDBusProxy.
11212 * @arg_environment: Argument to pass with the method invocation.
11213 * @cancellable: (allow-none): A #GCancellable or %NULL.
11214 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
11215 * @user_data: User data to pass to @callback.
11217 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.UpdateActivationEnvironment">UpdateActivationEnvironment()</link> D-Bus method on @proxy.
11218 * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from.
11219 * You can then call _g_freedesktop_dbus_call_update_activation_environment_finish() to get the result of the operation.
11221 * See _g_freedesktop_dbus_call_update_activation_environment_sync() for the synchronous, blocking version of this method.
11226 * _g_freedesktop_dbus_call_update_activation_environment_finish:
11227 * @proxy: A #_GFreedesktopDBusProxy.
11228 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_update_activation_environment().
11229 * @error: Return location for error or %NULL.
11231 * Finishes an operation started with _g_freedesktop_dbus_call_update_activation_environment().
11233 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
11238 * _g_freedesktop_dbus_call_update_activation_environment_sync:
11239 * @proxy: A #_GFreedesktopDBusProxy.
11240 * @arg_environment: Argument to pass with the method invocation.
11241 * @cancellable: (allow-none): A #GCancellable or %NULL.
11242 * @error: Return location for error or %NULL.
11244 * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.UpdateActivationEnvironment">UpdateActivationEnvironment()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
11246 * See _g_freedesktop_dbus_call_update_activation_environment() for the asynchronous version of this method.
11248 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
11253 * _g_freedesktop_dbus_complete_add_match:
11254 * @object: A #_GFreedesktopDBus.
11255 * @invocation: (transfer full): A #GDBusMethodInvocation.
11257 * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-DBus.AddMatch">AddMatch()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
11259 * This method will free @invocation, you cannot use it afterwards.
11264 * _g_freedesktop_dbus_complete_get_connection_selinux_security_context:
11265 * @object: A #_GFreedesktopDBus.
11266 * @invocation: (transfer full): A #GDBusMethodInvocation.
11267 * @security_context: Parameter to return.
11269 * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionSELinuxSecurityContext">GetConnectionSELinuxSecurityContext()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
11271 * This method will free @invocation, you cannot use it afterwards.
11276 * _g_freedesktop_dbus_complete_get_connection_unix_process_id:
11277 * @object: A #_GFreedesktopDBus.
11278 * @invocation: (transfer full): A #GDBusMethodInvocation.
11279 * @pid: Parameter to return.
11281 * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionUnixProcessID">GetConnectionUnixProcessID()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
11283 * This method will free @invocation, you cannot use it afterwards.
11288 * _g_freedesktop_dbus_complete_get_connection_unix_user:
11289 * @object: A #_GFreedesktopDBus.
11290 * @invocation: (transfer full): A #GDBusMethodInvocation.
11291 * @uid: Parameter to return.
11293 * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionUnixUser">GetConnectionUnixUser()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
11295 * This method will free @invocation, you cannot use it afterwards.
11300 * _g_freedesktop_dbus_complete_get_id:
11301 * @object: A #_GFreedesktopDBus.
11302 * @invocation: (transfer full): A #GDBusMethodInvocation.
11303 * @unique_id: Parameter to return.
11305 * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-DBus.GetId">GetId()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
11307 * This method will free @invocation, you cannot use it afterwards.
11312 * _g_freedesktop_dbus_complete_get_name_owner:
11313 * @object: A #_GFreedesktopDBus.
11314 * @invocation: (transfer full): A #GDBusMethodInvocation.
11315 * @unique_name: Parameter to return.
11317 * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-DBus.GetNameOwner">GetNameOwner()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
11319 * This method will free @invocation, you cannot use it afterwards.
11324 * _g_freedesktop_dbus_complete_hello:
11325 * @object: A #_GFreedesktopDBus.
11326 * @invocation: (transfer full): A #GDBusMethodInvocation.
11327 * @assigned_name: Parameter to return.
11329 * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-DBus.Hello">Hello()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
11331 * This method will free @invocation, you cannot use it afterwards.
11336 * _g_freedesktop_dbus_complete_list_activatable_names:
11337 * @object: A #_GFreedesktopDBus.
11338 * @invocation: (transfer full): A #GDBusMethodInvocation.
11339 * @activatable_names: Parameter to return.
11341 * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-DBus.ListActivatableNames">ListActivatableNames()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
11343 * This method will free @invocation, you cannot use it afterwards.
11348 * _g_freedesktop_dbus_complete_list_names:
11349 * @object: A #_GFreedesktopDBus.
11350 * @invocation: (transfer full): A #GDBusMethodInvocation.
11351 * @names: Parameter to return.
11353 * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-DBus.ListNames">ListNames()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
11355 * This method will free @invocation, you cannot use it afterwards.
11360 * _g_freedesktop_dbus_complete_list_queued_owners:
11361 * @object: A #_GFreedesktopDBus.
11362 * @invocation: (transfer full): A #GDBusMethodInvocation.
11363 * @queued_owners: Parameter to return.
11365 * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-DBus.ListQueuedOwners">ListQueuedOwners()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
11367 * This method will free @invocation, you cannot use it afterwards.
11372 * _g_freedesktop_dbus_complete_name_has_owner:
11373 * @object: A #_GFreedesktopDBus.
11374 * @invocation: (transfer full): A #GDBusMethodInvocation.
11375 * @has_owner: Parameter to return.
11377 * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-DBus.NameHasOwner">NameHasOwner()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
11379 * This method will free @invocation, you cannot use it afterwards.
11384 * _g_freedesktop_dbus_complete_release_name:
11385 * @object: A #_GFreedesktopDBus.
11386 * @invocation: (transfer full): A #GDBusMethodInvocation.
11387 * @value: Parameter to return.
11389 * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-DBus.ReleaseName">ReleaseName()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
11391 * This method will free @invocation, you cannot use it afterwards.
11396 * _g_freedesktop_dbus_complete_reload_config:
11397 * @object: A #_GFreedesktopDBus.
11398 * @invocation: (transfer full): A #GDBusMethodInvocation.
11400 * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-DBus.ReloadConfig">ReloadConfig()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
11402 * This method will free @invocation, you cannot use it afterwards.
11407 * _g_freedesktop_dbus_complete_remove_match:
11408 * @object: A #_GFreedesktopDBus.
11409 * @invocation: (transfer full): A #GDBusMethodInvocation.
11411 * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-DBus.RemoveMatch">RemoveMatch()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
11413 * This method will free @invocation, you cannot use it afterwards.
11418 * _g_freedesktop_dbus_complete_request_name:
11419 * @object: A #_GFreedesktopDBus.
11420 * @invocation: (transfer full): A #GDBusMethodInvocation.
11421 * @value: Parameter to return.
11423 * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-DBus.RequestName">RequestName()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
11425 * This method will free @invocation, you cannot use it afterwards.
11430 * _g_freedesktop_dbus_complete_start_service_by_name:
11431 * @object: A #_GFreedesktopDBus.
11432 * @invocation: (transfer full): A #GDBusMethodInvocation.
11433 * @value: Parameter to return.
11435 * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-DBus.StartServiceByName">StartServiceByName()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
11437 * This method will free @invocation, you cannot use it afterwards.
11442 * _g_freedesktop_dbus_complete_update_activation_environment:
11443 * @object: A #_GFreedesktopDBus.
11444 * @invocation: (transfer full): A #GDBusMethodInvocation.
11446 * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-DBus.UpdateActivationEnvironment">UpdateActivationEnvironment()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
11448 * This method will free @invocation, you cannot use it afterwards.
11453 * _g_freedesktop_dbus_emit_name_acquired:
11454 * @object: A #_GFreedesktopDBus.
11455 * @arg_name: Argument to pass with the signal.
11457 * Emits the <link linkend="gdbus-signal-org-freedesktop-DBus.NameAcquired">"NameAcquired"</link> D-Bus signal.
11462 * _g_freedesktop_dbus_emit_name_lost:
11463 * @object: A #_GFreedesktopDBus.
11464 * @arg_name: Argument to pass with the signal.
11466 * Emits the <link linkend="gdbus-signal-org-freedesktop-DBus.NameLost">"NameLost"</link> D-Bus signal.
11471 * _g_freedesktop_dbus_emit_name_owner_changed:
11472 * @object: A #_GFreedesktopDBus.
11473 * @arg_name: Argument to pass with the signal.
11474 * @arg_old_owner: Argument to pass with the signal.
11475 * @arg_new_owner: Argument to pass with the signal.
11477 * Emits the <link linkend="gdbus-signal-org-freedesktop-DBus.NameOwnerChanged">"NameOwnerChanged"</link> D-Bus signal.
11482 * _g_freedesktop_dbus_interface_info:
11484 * Gets a machine-readable description of the <link linkend="gdbus-interface-org-freedesktop-DBus.top_of_page">org.freedesktop.DBus</link> D-Bus interface.
11486 * Returns: (transfer none): A #GDBusInterfaceInfo. Do not free.
11491 * _g_freedesktop_dbus_override_properties:
11492 * @klass: The class structure for a #GObject<!-- -->-derived class.
11493 * @property_id_begin: The property id to assign to the first overridden property.
11495 * Overrides all #GObject properties in the #_GFreedesktopDBus interface for a concrete class.
11496 * The properties are overridden in the order they are defined.
11498 * Returns: The last property id.
11503 * _g_freedesktop_dbus_proxy_new:
11504 * @connection: A #GDBusConnection.
11505 * @flags: Flags from the #GDBusProxyFlags enumeration.
11506 * @name: (allow-none): A bus name (well-known or unique) or %NULL if @connection is not a message bus connection.
11507 * @object_path: An object path.
11508 * @cancellable: (allow-none): A #GCancellable or %NULL.
11509 * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
11510 * @user_data: User data to pass to @callback.
11512 * Asynchronously creates a proxy for the D-Bus interface <link linkend="gdbus-interface-org-freedesktop-DBus.top_of_page">org.freedesktop.DBus</link>. See g_dbus_proxy_new() for more details.
11514 * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from.
11515 * You can then call _g_freedesktop_dbus_proxy_new_finish() to get the result of the operation.
11517 * See _g_freedesktop_dbus_proxy_new_sync() for the synchronous, blocking version of this constructor.
11522 * _g_freedesktop_dbus_proxy_new_finish:
11523 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_proxy_new().
11524 * @error: Return location for error or %NULL
11526 * Finishes an operation started with _g_freedesktop_dbus_proxy_new().
11528 * Returns: (transfer full) (type _GFreedesktopDBusProxy): The constructed proxy object or %NULL if @error is set.
11533 * _g_freedesktop_dbus_proxy_new_for_bus:
11534 * @bus_type: A #GBusType.
11535 * @flags: Flags from the #GDBusProxyFlags enumeration.
11536 * @name: A bus name (well-known or unique).
11537 * @object_path: An object path.
11538 * @cancellable: (allow-none): A #GCancellable or %NULL.
11539 * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
11540 * @user_data: User data to pass to @callback.
11542 * Like _g_freedesktop_dbus_proxy_new() but takes a #GBusType instead of a #GDBusConnection.
11544 * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from.
11545 * You can then call _g_freedesktop_dbus_proxy_new_for_bus_finish() to get the result of the operation.
11547 * See _g_freedesktop_dbus_proxy_new_for_bus_sync() for the synchronous, blocking version of this constructor.
11552 * _g_freedesktop_dbus_proxy_new_for_bus_finish:
11553 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_proxy_new_for_bus().
11554 * @error: Return location for error or %NULL
11556 * Finishes an operation started with _g_freedesktop_dbus_proxy_new_for_bus().
11558 * Returns: (transfer full) (type _GFreedesktopDBusProxy): The constructed proxy object or %NULL if @error is set.
11563 * _g_freedesktop_dbus_proxy_new_for_bus_sync:
11564 * @bus_type: A #GBusType.
11565 * @flags: Flags from the #GDBusProxyFlags enumeration.
11566 * @name: A bus name (well-known or unique).
11567 * @object_path: An object path.
11568 * @cancellable: (allow-none): A #GCancellable or %NULL.
11569 * @error: Return location for error or %NULL
11571 * Like _g_freedesktop_dbus_proxy_new_sync() but takes a #GBusType instead of a #GDBusConnection.
11573 * The calling thread is blocked until a reply is received.
11575 * See _g_freedesktop_dbus_proxy_new_for_bus() for the asynchronous version of this constructor.
11577 * Returns: (transfer full) (type _GFreedesktopDBusProxy): The constructed proxy object or %NULL if @error is set.
11582 * _g_freedesktop_dbus_proxy_new_sync:
11583 * @connection: A #GDBusConnection.
11584 * @flags: Flags from the #GDBusProxyFlags enumeration.
11585 * @name: (allow-none): A bus name (well-known or unique) or %NULL if @connection is not a message bus connection.
11586 * @object_path: An object path.
11587 * @cancellable: (allow-none): A #GCancellable or %NULL.
11588 * @error: Return location for error or %NULL
11590 * Synchronously creates a proxy for the D-Bus interface <link linkend="gdbus-interface-org-freedesktop-DBus.top_of_page">org.freedesktop.DBus</link>. See g_dbus_proxy_new_sync() for more details.
11592 * The calling thread is blocked until a reply is received.
11594 * See _g_freedesktop_dbus_proxy_new() for the asynchronous version of this constructor.
11596 * Returns: (transfer full) (type _GFreedesktopDBusProxy): The constructed proxy object or %NULL if @error is set.
11601 * _g_freedesktop_dbus_skeleton_new:
11603 * Creates a skeleton object for the D-Bus interface <link linkend="gdbus-interface-org-freedesktop-DBus.top_of_page">org.freedesktop.DBus</link>.
11605 * Returns: (transfer full) (type _GFreedesktopDBusSkeleton): The skeleton object.
11610 * _g_io_module_get_default:
11611 * @extension_point: the name of an extension point
11612 * @envvar: (allow-none): the name of an environment variable to
11613 * override the default implementation.
11614 * @verify_func: (allow-none): a function to call to verify that
11615 * a given implementation is usable in the current environment.
11617 * Retrieves the default object implementing @extension_point.
11619 * If @envvar is not %NULL, and the environment variable with that
11620 * name is set, then the implementation it specifies will be tried
11621 * first. After that, or if @envvar is not set, all other
11622 * implementations will be tried in order of decreasing priority.
11624 * If an extension point implementation implements #GInitable, then
11625 * that implementation will only be used if it initializes
11626 * successfully. Otherwise, if @verify_func is not %NULL, then it will
11627 * be called on each candidate implementation after construction, to
11628 * check if it is actually usable or not.
11630 * The result is cached after it is generated the first time, and
11631 * the function is thread-safe.
11633 * Returns: (transfer none): an object implementing
11634 * @extension_point, or %NULL if there are no usable
11640 * _g_io_module_get_default_type:
11641 * @extension_point: the name of an extension point
11642 * @envvar: (allow-none): the name of an environment variable to
11643 * override the default implementation.
11644 * @is_supported_offset: a vtable offset, or zero
11646 * Retrieves the default class implementing @extension_point.
11648 * If @envvar is not %NULL, and the environment variable with that
11649 * name is set, then the implementation it specifies will be tried
11650 * first. After that, or if @envvar is not set, all other
11651 * implementations will be tried in order of decreasing priority.
11653 * If @is_supported_offset is non-zero, then it is the offset into the
11654 * class vtable at which there is a function that takes no arguments and
11655 * returns a boolean. This function will be called on each candidate
11656 * implementation to check if it is actually usable or not.
11658 * The result is cached after it is generated the first time, and
11659 * the function is thread-safe.
11661 * Returns: (transfer none): an object implementing
11662 * @extension_point, or %NULL if there are no usable
11668 * _g_poll_file_monitor_new:
11671 * Polls @file for changes.
11673 * Returns: a new #GFileMonitor for the given #GFile.
11678 * g_action_activate:
11679 * @action: a #GAction
11680 * @parameter: (allow-none): the parameter to the activation
11682 * Activates the action.
11684 * @parameter must be the correct type of parameter for the action (ie:
11685 * the parameter type given at construction time). If the parameter
11686 * type was %NULL then @parameter must also be %NULL.
11688 * If the @parameter GVariant is floating, it is consumed.
11695 * g_action_change_state:
11696 * @action: a #GAction
11697 * @value: the new state
11699 * Request for the state of @action to be changed to @value.
11701 * The action must be stateful and @value must be of the correct type.
11702 * See g_action_get_state_type().
11704 * This call merely requests a change. The action may refuse to change
11705 * its state or may change its state to something other than @value.
11706 * See g_action_get_state_hint().
11708 * If the @value GVariant is floating, it is consumed.
11715 * g_action_get_enabled:
11716 * @action: a #GAction
11718 * Checks if @action is currently enabled.
11720 * An action must be enabled in order to be activated or in order to
11721 * have its state changed from outside callers.
11723 * Returns: whether the action is enabled
11729 * g_action_get_name:
11730 * @action: a #GAction
11732 * Queries the name of @action.
11734 * Returns: the name of the action
11740 * g_action_get_parameter_type:
11741 * @action: a #GAction
11743 * Queries the type of the parameter that must be given when activating
11746 * When activating the action using g_action_activate(), the #GVariant
11747 * given to that function must be of the type returned by this function.
11749 * In the case that this function returns %NULL, you must not give any
11750 * #GVariant, but %NULL instead.
11752 * Returns: (allow-none): the parameter type
11758 * g_action_get_state:
11759 * @action: a #GAction
11761 * Queries the current state of @action.
11763 * If the action is not stateful then %NULL will be returned. If the
11764 * action is stateful then the type of the return value is the type
11765 * given by g_action_get_state_type().
11767 * The return value (if non-%NULL) should be freed with
11768 * g_variant_unref() when it is no longer required.
11770 * Returns: (transfer full): the current state of the action
11776 * g_action_get_state_hint:
11777 * @action: a #GAction
11779 * Requests a hint about the valid range of values for the state of
11782 * If %NULL is returned it either means that the action is not stateful
11783 * or that there is no hint about the valid range of values for the
11784 * state of the action.
11786 * If a #GVariant array is returned then each item in the array is a
11787 * possible value for the state. If a #GVariant pair (ie: two-tuple) is
11788 * returned then the tuple specifies the inclusive lower and upper bound
11789 * of valid values for the state.
11791 * In any case, the information is merely a hint. It may be possible to
11792 * have a state value outside of the hinted range and setting a value
11793 * within the range may fail.
11795 * The return value (if non-%NULL) should be freed with
11796 * g_variant_unref() when it is no longer required.
11798 * Returns: (nullable) (transfer full): the state range hint
11804 * g_action_get_state_type:
11805 * @action: a #GAction
11807 * Queries the type of the state of @action.
11809 * If the action is stateful (e.g. created with
11810 * g_simple_action_new_stateful()) then this function returns the
11811 * #GVariantType of the state. This is the type of the initial value
11812 * given as the state. All calls to g_action_change_state() must give a
11813 * #GVariant of this type and g_action_get_state() will return a
11814 * #GVariant of the same type.
11816 * If the action is not stateful (e.g. created with g_simple_action_new())
11817 * then this function will return %NULL. In that case, g_action_get_state()
11818 * will return %NULL and you must not call g_action_change_state().
11820 * Returns: (allow-none): the state type, if the action is stateful
11826 * g_action_group_action_added:
11827 * @action_group: a #GActionGroup
11828 * @action_name: the name of an action in the group
11830 * Emits the #GActionGroup::action-added signal on @action_group.
11832 * This function should only be called by #GActionGroup implementations.
11839 * g_action_group_action_enabled_changed:
11840 * @action_group: a #GActionGroup
11841 * @action_name: the name of an action in the group
11842 * @enabled: whether or not the action is now enabled
11844 * Emits the #GActionGroup::action-enabled-changed signal on @action_group.
11846 * This function should only be called by #GActionGroup implementations.
11853 * g_action_group_action_removed:
11854 * @action_group: a #GActionGroup
11855 * @action_name: the name of an action in the group
11857 * Emits the #GActionGroup::action-removed signal on @action_group.
11859 * This function should only be called by #GActionGroup implementations.
11866 * g_action_group_action_state_changed:
11867 * @action_group: a #GActionGroup
11868 * @action_name: the name of an action in the group
11869 * @state: the new state of the named action
11871 * Emits the #GActionGroup::action-state-changed signal on @action_group.
11873 * This function should only be called by #GActionGroup implementations.
11880 * g_action_group_activate_action:
11881 * @action_group: a #GActionGroup
11882 * @action_name: the name of the action to activate
11883 * @parameter: (allow-none): parameters to the activation
11885 * Activate the named action within @action_group.
11887 * If the action is expecting a parameter, then the correct type of
11888 * parameter must be given as @parameter. If the action is expecting no
11889 * parameters then @parameter must be %NULL. See
11890 * g_action_group_get_action_parameter_type().
11897 * g_action_group_change_action_state:
11898 * @action_group: a #GActionGroup
11899 * @action_name: the name of the action to request the change on
11900 * @value: the new state
11902 * Request for the state of the named action within @action_group to be
11903 * changed to @value.
11905 * The action must be stateful and @value must be of the correct type.
11906 * See g_action_group_get_action_state_type().
11908 * This call merely requests a change. The action may refuse to change
11909 * its state or may change its state to something other than @value.
11910 * See g_action_group_get_action_state_hint().
11912 * If the @value GVariant is floating, it is consumed.
11919 * g_action_group_get_action_enabled:
11920 * @action_group: a #GActionGroup
11921 * @action_name: the name of the action to query
11923 * Checks if the named action within @action_group is currently enabled.
11925 * An action must be enabled in order to be activated or in order to
11926 * have its state changed from outside callers.
11928 * Returns: whether or not the action is currently enabled
11934 * g_action_group_get_action_parameter_type:
11935 * @action_group: a #GActionGroup
11936 * @action_name: the name of the action to query
11938 * Queries the type of the parameter that must be given when activating
11939 * the named action within @action_group.
11941 * When activating the action using g_action_group_activate_action(),
11942 * the #GVariant given to that function must be of the type returned
11943 * by this function.
11945 * In the case that this function returns %NULL, you must not give any
11946 * #GVariant, but %NULL instead.
11948 * The parameter type of a particular action will never change but it is
11949 * possible for an action to be removed and for a new action to be added
11950 * with the same name but a different parameter type.
11952 * Returns: (nullable): the parameter type
11958 * g_action_group_get_action_state:
11959 * @action_group: a #GActionGroup
11960 * @action_name: the name of the action to query
11962 * Queries the current state of the named action within @action_group.
11964 * If the action is not stateful then %NULL will be returned. If the
11965 * action is stateful then the type of the return value is the type
11966 * given by g_action_group_get_action_state_type().
11968 * The return value (if non-%NULL) should be freed with
11969 * g_variant_unref() when it is no longer required.
11971 * Returns: (nullable): the current state of the action
11977 * g_action_group_get_action_state_hint:
11978 * @action_group: a #GActionGroup
11979 * @action_name: the name of the action to query
11981 * Requests a hint about the valid range of values for the state of the
11982 * named action within @action_group.
11984 * If %NULL is returned it either means that the action is not stateful
11985 * or that there is no hint about the valid range of values for the
11986 * state of the action.
11988 * If a #GVariant array is returned then each item in the array is a
11989 * possible value for the state. If a #GVariant pair (ie: two-tuple) is
11990 * returned then the tuple specifies the inclusive lower and upper bound
11991 * of valid values for the state.
11993 * In any case, the information is merely a hint. It may be possible to
11994 * have a state value outside of the hinted range and setting a value
11995 * within the range may fail.
11997 * The return value (if non-%NULL) should be freed with
11998 * g_variant_unref() when it is no longer required.
12000 * Returns: (nullable) (transfer full): the state range hint
12006 * g_action_group_get_action_state_type:
12007 * @action_group: a #GActionGroup
12008 * @action_name: the name of the action to query
12010 * Queries the type of the state of the named action within
12013 * If the action is stateful then this function returns the
12014 * #GVariantType of the state. All calls to
12015 * g_action_group_change_action_state() must give a #GVariant of this
12016 * type and g_action_group_get_action_state() will return a #GVariant
12017 * of the same type.
12019 * If the action is not stateful then this function will return %NULL.
12020 * In that case, g_action_group_get_action_state() will return %NULL
12021 * and you must not call g_action_group_change_action_state().
12023 * The state type of a particular action will never change but it is
12024 * possible for an action to be removed and for a new action to be added
12025 * with the same name but a different state type.
12027 * Returns: (nullable): the state type, if the action is stateful
12033 * g_action_group_has_action:
12034 * @action_group: a #GActionGroup
12035 * @action_name: the name of the action to check for
12037 * Checks if the named action exists within @action_group.
12039 * Returns: whether the named action exists
12045 * g_action_group_list_actions:
12046 * @action_group: a #GActionGroup
12048 * Lists the actions contained within @action_group.
12050 * The caller is responsible for freeing the list with g_strfreev() when
12051 * it is no longer required.
12053 * Returns: (transfer full): a %NULL-terminated array of the names of the
12054 * actions in the group
12060 * g_action_group_query_action:
12061 * @action_group: a #GActionGroup
12062 * @action_name: the name of an action in the group
12063 * @enabled: (out): if the action is presently enabled
12064 * @parameter_type: (out) (allow-none): the parameter type, or %NULL if none needed
12065 * @state_type: (out) (allow-none): the state type, or %NULL if stateless
12066 * @state_hint: (out) (allow-none): the state hint, or %NULL if none
12067 * @state: (out) (allow-none): the current state, or %NULL if stateless
12069 * Queries all aspects of the named action within an @action_group.
12071 * This function acquires the information available from
12072 * g_action_group_has_action(), g_action_group_get_action_enabled(),
12073 * g_action_group_get_action_parameter_type(),
12074 * g_action_group_get_action_state_type(),
12075 * g_action_group_get_action_state_hint() and
12076 * g_action_group_get_action_state() with a single function call.
12078 * This provides two main benefits.
12080 * The first is the improvement in efficiency that comes with not having
12081 * to perform repeated lookups of the action in order to discover
12082 * different things about it. The second is that implementing
12083 * #GActionGroup can now be done by only overriding this one virtual
12086 * The interface provides a default implementation of this function that
12087 * calls the individual functions, as required, to fetch the
12088 * information. The interface also provides default implementations of
12089 * those functions that call this function. All implementations,
12090 * therefore, must override either this function or all of the others.
12092 * If the action exists, %TRUE is returned and any of the requested
12093 * fields (as indicated by having a non-%NULL reference passed in) are
12094 * filled. If the action doesn't exist, %FALSE is returned and the
12095 * fields may or may not have been modified.
12097 * Returns: %TRUE if the action exists, else %FALSE
12103 * g_action_map_add_action:
12104 * @action_map: a #GActionMap
12105 * @action: a #GAction
12107 * Adds an action to the @action_map.
12109 * If the action map already contains an action with the same name
12110 * as @action then the old action is dropped from the action map.
12112 * The action map takes its own reference on @action.
12119 * g_action_map_add_action_entries:
12120 * @action_map: a #GActionMap
12121 * @entries: (array length=n_entries) (element-type GActionEntry): a pointer to
12122 * the first item in an array of #GActionEntry structs
12123 * @n_entries: the length of @entries, or -1 if @entries is %NULL-terminated
12124 * @user_data: the user data for signal connections
12126 * A convenience function for creating multiple #GSimpleAction instances
12127 * and adding them to a #GActionMap.
12129 * Each action is constructed as per one #GActionEntry.
12131 * |[<!-- language="C" -->
12133 * activate_quit (GSimpleAction *simple,
12134 * GVariant *parameter,
12135 * gpointer user_data)
12141 * activate_print_string (GSimpleAction *simple,
12142 * GVariant *parameter,
12143 * gpointer user_data)
12145 * g_print ("%s\n", g_variant_get_string (parameter, NULL));
12148 * static GActionGroup *
12149 * create_action_group (void)
12151 * const GActionEntry entries[] = {
12152 * { "quit", activate_quit },
12153 * { "print-string", activate_print_string, "s" }
12155 * GSimpleActionGroup *group;
12157 * group = g_simple_action_group_new ();
12158 * g_action_map_add_action_entries (G_ACTION_MAP (group), entries, G_N_ELEMENTS (entries), NULL);
12160 * return G_ACTION_GROUP (group);
12169 * g_action_map_lookup_action:
12170 * @action_map: a #GActionMap
12171 * @action_name: the name of an action
12173 * Looks up the action with the name @action_name in @action_map.
12175 * If no such action exists, returns %NULL.
12177 * Returns: (transfer none): a #GAction, or %NULL
12183 * g_action_map_remove_action:
12184 * @action_map: a #GActionMap
12185 * @action_name: the name of the action
12187 * Removes the named action from the action map.
12189 * If no action of this name is in the map then nothing happens.
12196 * g_action_name_is_valid:
12197 * @action_name: an potential action name
12199 * Checks if @action_name is valid.
12201 * @action_name is valid if it consists only of alphanumeric characters,
12202 * plus '-' and '.'. The empty string is not a valid action name.
12204 * It is an error to call this function with a non-utf8 @action_name.
12205 * @action_name must not be %NULL.
12207 * Returns: %TRUE if @action_name is valid
12213 * g_action_parse_detailed_name:
12214 * @detailed_name: a detailed action name
12215 * @action_name: (out): the action name
12216 * @target_value: (out): the target value, or %NULL for no target
12217 * @error: a pointer to a %NULL #GError, or %NULL
12219 * Parses a detailed action name into its separate name and target
12222 * Detailed action names can have three formats.
12224 * The first format is used to represent an action name with no target
12225 * value and consists of just an action name containing no whitespace
12226 * nor the characters ':', '(' or ')'. For example: "app.action".
12228 * The second format is used to represent an action with a target value
12229 * that is a non-empty string consisting only of alphanumerics, plus '-'
12230 * and '.'. In that case, the action name and target value are
12231 * separated by a double colon ("::"). For example:
12232 * "app.action::target".
12234 * The third format is used to represent an action with any type of
12235 * target value, including strings. The target value follows the action
12236 * name, surrounded in parens. For example: "app.action(42)". The
12237 * target value is parsed using g_variant_parse(). If a tuple-typed
12238 * value is desired, it must be specified in the same way, resulting in
12239 * two sets of parens, for example: "app.action((1,2,3))". A string
12240 * target can be specified this way as well: "app.action('target')".
12241 * For strings, this third format must be used if * target value is
12242 * empty or contains characters other than alphanumerics, '-' and '.'.
12244 * Returns: %TRUE if successful, else %FALSE with @error set
12250 * g_action_print_detailed_name:
12251 * @action_name: a valid action name
12252 * @target_value: (allow-none): a #GVariant target value, or %NULL
12254 * Formats a detailed action name from @action_name and @target_value.
12256 * It is an error to call this function with an invalid action name.
12258 * This function is the opposite of g_action_parse_detailed_name().
12259 * It will produce a string that can be parsed back to the @action_name
12260 * and @target_value by that function.
12262 * See that function for the types of strings that will be printed by
12265 * Returns: a detailed format string
12271 * g_app_info_add_supports_type:
12272 * @appinfo: a #GAppInfo.
12273 * @content_type: a string.
12274 * @error: a #GError.
12276 * Adds a content type to the application information to indicate the
12277 * application is capable of opening files with the given content type.
12279 * Returns: %TRUE on success, %FALSE on error.
12284 * g_app_info_can_delete:
12285 * @appinfo: a #GAppInfo
12287 * Obtains the information whether the #GAppInfo can be deleted.
12288 * See g_app_info_delete().
12290 * Returns: %TRUE if @appinfo can be deleted
12296 * g_app_info_can_remove_supports_type:
12297 * @appinfo: a #GAppInfo.
12299 * Checks if a supported content type can be removed from an application.
12301 * Returns: %TRUE if it is possible to remove supported
12302 * content types from a given @appinfo, %FALSE if not.
12307 * g_app_info_create_from_commandline:
12308 * @commandline: the commandline to use
12309 * @application_name: (allow-none): the application name, or %NULL to use @commandline
12310 * @flags: flags that can specify details of the created #GAppInfo
12311 * @error: a #GError location to store the error occurring, %NULL to ignore.
12313 * Creates a new #GAppInfo from the given information.
12315 * Note that for @commandline, the quoting rules of the Exec key of the
12316 * [freedesktop.org Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec)
12317 * are applied. For example, if the @commandline contains
12318 * percent-encoded URIs, the percent-character must be doubled in order to prevent it from
12319 * being swallowed by Exec key unquoting. See the specification for exact quoting rules.
12321 * Returns: (transfer full): new #GAppInfo for given command.
12326 * g_app_info_delete: (virtual do_delete)
12327 * @appinfo: a #GAppInfo
12329 * Tries to delete a #GAppInfo.
12331 * On some platforms, there may be a difference between user-defined
12332 * #GAppInfos which can be deleted, and system-wide ones which cannot.
12333 * See g_app_info_can_delete().
12335 * Returns: %TRUE if @appinfo has been deleted
12342 * @appinfo: a #GAppInfo.
12344 * Creates a duplicate of a #GAppInfo.
12346 * Returns: (transfer full): a duplicate of @appinfo.
12351 * g_app_info_equal:
12352 * @appinfo1: the first #GAppInfo.
12353 * @appinfo2: the second #GAppInfo.
12355 * Checks if two #GAppInfos are equal.
12357 * Returns: %TRUE if @appinfo1 is equal to @appinfo2. %FALSE otherwise.
12362 * g_app_info_get_all:
12364 * Gets a list of all of the applications currently registered
12367 * For desktop files, this includes applications that have
12368 * `NoDisplay=true` set or are excluded from display by means
12369 * of `OnlyShowIn` or `NotShowIn`. See g_app_info_should_show().
12370 * The returned list does not include applications which have
12371 * the `Hidden` key set.
12373 * Returns: (element-type GAppInfo) (transfer full): a newly allocated #GList of references to #GAppInfos.
12378 * g_app_info_get_all_for_type:
12379 * @content_type: the content type to find a #GAppInfo for
12381 * Gets a list of all #GAppInfos for a given content type,
12382 * including the recommended and fallback #GAppInfos. See
12383 * g_app_info_get_recommended_for_type() and
12384 * g_app_info_get_fallback_for_type().
12386 * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos
12387 * for given @content_type or %NULL on error.
12392 * g_app_info_get_commandline:
12393 * @appinfo: a #GAppInfo
12395 * Gets the commandline with which the application will be
12398 * Returns: (type filename): a string containing the @appinfo's commandline,
12399 * or %NULL if this information is not available
12405 * g_app_info_get_default_for_type:
12406 * @content_type: the content type to find a #GAppInfo for
12407 * @must_support_uris: if %TRUE, the #GAppInfo is expected to
12410 * Gets the default #GAppInfo for a given content type.
12412 * Returns: (transfer full): #GAppInfo for given @content_type or
12418 * g_app_info_get_default_for_uri_scheme:
12419 * @uri_scheme: a string containing a URI scheme.
12421 * Gets the default application for handling URIs with
12422 * the given URI scheme. A URI scheme is the initial part
12423 * of the URI, up to but not including the ':', e.g. "http",
12426 * Returns: (transfer full): #GAppInfo for given @uri_scheme or %NULL on error.
12431 * g_app_info_get_description:
12432 * @appinfo: a #GAppInfo.
12434 * Gets a human-readable description of an installed application.
12436 * Returns: a string containing a description of the
12437 * application @appinfo, or %NULL if none.
12442 * g_app_info_get_display_name:
12443 * @appinfo: a #GAppInfo.
12445 * Gets the display name of the application. The display name is often more
12446 * descriptive to the user than the name itself.
12448 * Returns: the display name of the application for @appinfo, or the name if
12449 * no display name is available.
12455 * g_app_info_get_executable:
12456 * @appinfo: a #GAppInfo
12458 * Gets the executable's name for the installed application.
12460 * Returns: (type filename): a string containing the @appinfo's application
12466 * g_app_info_get_fallback_for_type:
12467 * @content_type: the content type to find a #GAppInfo for
12469 * Gets a list of fallback #GAppInfos for a given content type, i.e.
12470 * those applications which claim to support the given content type
12471 * by MIME type subclassing and not directly.
12473 * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos
12474 * for given @content_type or %NULL on error.
12480 * g_app_info_get_icon:
12481 * @appinfo: a #GAppInfo.
12483 * Gets the icon for the application.
12485 * Returns: (transfer none): the default #GIcon for @appinfo or %NULL
12486 * if there is no default icon.
12491 * g_app_info_get_id:
12492 * @appinfo: a #GAppInfo.
12494 * Gets the ID of an application. An id is a string that
12495 * identifies the application. The exact format of the id is
12496 * platform dependent. For instance, on Unix this is the
12497 * desktop file id from the xdg menu specification.
12499 * Note that the returned ID may be %NULL, depending on how
12500 * the @appinfo has been constructed.
12502 * Returns: a string containing the application's ID.
12507 * g_app_info_get_name:
12508 * @appinfo: a #GAppInfo.
12510 * Gets the installed name of the application.
12512 * Returns: the name of the application for @appinfo.
12517 * g_app_info_get_recommended_for_type:
12518 * @content_type: the content type to find a #GAppInfo for
12520 * Gets a list of recommended #GAppInfos for a given content type, i.e.
12521 * those applications which claim to support the given content type exactly,
12522 * and not by MIME type subclassing.
12523 * Note that the first application of the list is the last used one, i.e.
12524 * the last one for which g_app_info_set_as_last_used_for_type() has been
12527 * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos
12528 * for given @content_type or %NULL on error.
12534 * g_app_info_get_supported_types:
12535 * @appinfo: a #GAppInfo that can handle files
12537 * Retrieves the list of content types that @app_info claims to support.
12538 * If this information is not provided by the environment, this function
12539 * will return %NULL.
12540 * This function does not take in consideration associations added with
12541 * g_app_info_add_supports_type(), but only those exported directly by
12544 * Returns: (transfer none) (array zero-terminated=1) (element-type utf8):
12545 * a list of content types.
12551 * g_app_info_launch:
12552 * @appinfo: a #GAppInfo
12553 * @files: (allow-none) (element-type GFile): a #GList of #GFile objects
12554 * @launch_context: (allow-none): a #GAppLaunchContext or %NULL
12555 * @error: a #GError
12557 * Launches the application. Passes @files to the launched application
12558 * as arguments, using the optional @launch_context to get information
12559 * about the details of the launcher (like what screen it is on).
12560 * On error, @error will be set accordingly.
12562 * To launch the application without arguments pass a %NULL @files list.
12564 * Note that even if the launch is successful the application launched
12565 * can fail to start if it runs into problems during startup. There is
12566 * no way to detect this.
12568 * Some URIs can be changed when passed through a GFile (for instance
12569 * unsupported URIs with strange formats like mailto:), so if you have
12570 * a textual URI you want to pass in as argument, consider using
12571 * g_app_info_launch_uris() instead.
12573 * The launched application inherits the environment of the launching
12574 * process, but it can be modified with g_app_launch_context_setenv()
12575 * and g_app_launch_context_unsetenv().
12577 * On UNIX, this function sets the `GIO_LAUNCHED_DESKTOP_FILE`
12578 * environment variable with the path of the launched desktop file and
12579 * `GIO_LAUNCHED_DESKTOP_FILE_PID` to the process id of the launched
12580 * process. This can be used to ignore `GIO_LAUNCHED_DESKTOP_FILE`,
12581 * should it be inherited by further processes. The `DISPLAY` and
12582 * `DESKTOP_STARTUP_ID` environment variables are also set, based
12583 * on information provided in @launch_context.
12585 * Returns: %TRUE on successful launch, %FALSE otherwise.
12590 * g_app_info_launch_default_for_uri:
12591 * @uri: the uri to show
12592 * @launch_context: (allow-none): an optional #GAppLaunchContext.
12593 * @error: a #GError.
12595 * Utility function that launches the default application
12596 * registered to handle the specified uri. Synchronous I/O
12597 * is done on the uri to detect the type of the file if
12600 * Returns: %TRUE on success, %FALSE on error.
12605 * g_app_info_launch_uris:
12606 * @appinfo: a #GAppInfo
12607 * @uris: (allow-none) (element-type utf8): a #GList containing URIs to launch.
12608 * @launch_context: (allow-none): a #GAppLaunchContext or %NULL
12609 * @error: a #GError
12611 * Launches the application. This passes the @uris to the launched application
12612 * as arguments, using the optional @launch_context to get information
12613 * about the details of the launcher (like what screen it is on).
12614 * On error, @error will be set accordingly.
12616 * To launch the application without arguments pass a %NULL @uris list.
12618 * Note that even if the launch is successful the application launched
12619 * can fail to start if it runs into problems during startup. There is
12620 * no way to detect this.
12622 * Returns: %TRUE on successful launch, %FALSE otherwise.
12627 * g_app_info_monitor_get:
12629 * Gets the #GAppInfoMonitor for the current thread-default main
12632 * The #GAppInfoMonitor will emit a "changed" signal in the
12633 * thread-default main context whenever the list of installed
12634 * applications (as reported by g_app_info_get_all()) may have changed.
12636 * You must only call g_object_unref() on the return value from under
12637 * the same main context as you created it.
12639 * Returns: (transfer full): a reference to a #GAppInfoMonitor
12645 * g_app_info_remove_supports_type:
12646 * @appinfo: a #GAppInfo.
12647 * @content_type: a string.
12648 * @error: a #GError.
12650 * Removes a supported type from an application, if possible.
12652 * Returns: %TRUE on success, %FALSE on error.
12657 * g_app_info_reset_type_associations:
12658 * @content_type: a content type
12660 * Removes all changes to the type associations done by
12661 * g_app_info_set_as_default_for_type(),
12662 * g_app_info_set_as_default_for_extension(),
12663 * g_app_info_add_supports_type() or
12664 * g_app_info_remove_supports_type().
12671 * g_app_info_set_as_default_for_extension:
12672 * @appinfo: a #GAppInfo.
12673 * @extension: (type filename): a string containing the file extension
12674 * (without the dot).
12675 * @error: a #GError.
12677 * Sets the application as the default handler for the given file extension.
12679 * Returns: %TRUE on success, %FALSE on error.
12684 * g_app_info_set_as_default_for_type:
12685 * @appinfo: a #GAppInfo.
12686 * @content_type: the content type.
12687 * @error: a #GError.
12689 * Sets the application as the default handler for a given type.
12691 * Returns: %TRUE on success, %FALSE on error.
12696 * g_app_info_set_as_last_used_for_type:
12697 * @appinfo: a #GAppInfo.
12698 * @content_type: the content type.
12699 * @error: a #GError.
12701 * Sets the application as the last used application for a given type.
12702 * This will make the application appear as first in the list returned
12703 * by g_app_info_get_recommended_for_type(), regardless of the default
12704 * application for that content type.
12706 * Returns: %TRUE on success, %FALSE on error.
12711 * g_app_info_should_show:
12712 * @appinfo: a #GAppInfo.
12714 * Checks if the application info should be shown in menus that
12715 * list available applications.
12717 * Returns: %TRUE if the @appinfo should be shown, %FALSE otherwise.
12722 * g_app_info_supports_files:
12723 * @appinfo: a #GAppInfo.
12725 * Checks if the application accepts files as arguments.
12727 * Returns: %TRUE if the @appinfo supports files.
12732 * g_app_info_supports_uris:
12733 * @appinfo: a #GAppInfo.
12735 * Checks if the application supports reading files and directories from URIs.
12737 * Returns: %TRUE if the @appinfo supports URIs.
12742 * g_app_launch_context_get_display:
12743 * @context: a #GAppLaunchContext
12744 * @info: a #GAppInfo
12745 * @files: (element-type GFile): a #GList of #GFile objects
12747 * Gets the display string for the @context. This is used to ensure new
12748 * applications are started on the same display as the launching
12749 * application, by setting the `DISPLAY` environment variable.
12751 * Returns: a display string for the display.
12756 * g_app_launch_context_get_environment:
12757 * @context: a #GAppLaunchContext
12759 * Gets the complete environment variable list to be passed to
12760 * the child process when @context is used to launch an application.
12761 * This is a %NULL-terminated array of strings, where each string has
12762 * the form `KEY=VALUE`.
12764 * Returns: (array zero-terminated=1) (transfer full): the
12765 * child's environment
12771 * g_app_launch_context_get_startup_notify_id:
12772 * @context: a #GAppLaunchContext
12773 * @info: a #GAppInfo
12774 * @files: (element-type GFile): a #GList of of #GFile objects
12776 * Initiates startup notification for the application and returns the
12777 * `DESKTOP_STARTUP_ID` for the launched operation, if supported.
12779 * Startup notification IDs are defined in the
12780 * [FreeDesktop.Org Startup Notifications standard](http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt").
12782 * Returns: a startup notification ID for the application, or %NULL if
12788 * g_app_launch_context_launch_failed:
12789 * @context: a #GAppLaunchContext.
12790 * @startup_notify_id: the startup notification id that was returned by g_app_launch_context_get_startup_notify_id().
12792 * Called when an application has failed to launch, so that it can cancel
12793 * the application startup notification started in g_app_launch_context_get_startup_notify_id().
12798 * g_app_launch_context_new:
12800 * Creates a new application launch context. This is not normally used,
12801 * instead you instantiate a subclass of this, such as #GdkAppLaunchContext.
12803 * Returns: a #GAppLaunchContext.
12808 * g_app_launch_context_setenv:
12809 * @context: a #GAppLaunchContext
12810 * @variable: the environment variable to set
12811 * @value: the value for to set the variable to.
12813 * Arranges for @variable to be set to @value in the child's
12814 * environment when @context is used to launch an application.
12821 * g_app_launch_context_unsetenv:
12822 * @context: a #GAppLaunchContext
12823 * @variable: the environment variable to remove
12825 * Arranges for @variable to be unset in the child's environment
12826 * when @context is used to launch an application.
12833 * g_application_activate:
12834 * @application: a #GApplication
12836 * Activates the application.
12838 * In essence, this results in the #GApplication::activate signal being
12839 * emitted in the primary instance.
12841 * The application must be registered before calling this function.
12848 * g_application_add_main_option:
12849 * @application: the #GApplication
12850 * @long_name: the long name of an option used to specify it in a commandline
12851 * @short_name: the short name of an option
12852 * @flags: flags from #GOptionFlags
12853 * @arg: the type of the option, as a #GOptionArg
12854 * @description: the description for the option in `--help` output
12855 * @arg_description: (nullable): the placeholder to use for the extra argument
12856 * parsed by the option in `--help` output
12858 * Add an option to be handled by @application.
12860 * Calling this function is the equivalent of calling
12861 * g_application_add_main_option_entries() with a single #GOptionEntry
12862 * that has its arg_data member set to %NULL.
12864 * The parsed arguments will be packed into a #GVariantDict which
12865 * is passed to #GApplication::handle-local-options. If
12866 * %G_APPLICATION_HANDLES_COMMAND_LINE is set, then it will also
12867 * be sent to the primary instance. See
12868 * g_application_add_main_option_entries() for more details.
12870 * See #GOptionEntry for more documentation of the arguments.
12877 * g_application_add_main_option_entries:
12878 * @application: a #GApplication
12879 * @entries: (array zero-terminated=1) (element-type GOptionEntry): a
12880 * %NULL-terminated list of #GOptionEntrys
12882 * Adds main option entries to be handled by @application.
12884 * This function is comparable to g_option_context_add_main_entries().
12886 * After the commandline arguments are parsed, the
12887 * #GApplication::handle-local-options signal will be emitted. At this
12888 * point, the application can inspect the values pointed to by @arg_data
12889 * in the given #GOptionEntrys.
12891 * Unlike #GOptionContext, #GApplication supports giving a %NULL
12892 * @arg_data for a non-callback #GOptionEntry. This results in the
12893 * argument in question being packed into a #GVariantDict which is also
12894 * passed to #GApplication::handle-local-options, where it can be
12895 * inspected and modified. If %G_APPLICATION_HANDLES_COMMAND_LINE is
12896 * set, then the resulting dictionary is sent to the primary instance,
12897 * where g_application_command_line_get_options_dict() will return it.
12898 * This "packing" is done according to the type of the argument --
12899 * booleans for normal flags, strings for strings, bytestrings for
12900 * filenames, etc. The packing only occurs if the flag is given (ie: we
12901 * do not pack a "false" #GVariant in the case that a flag is missing).
12903 * In general, it is recommended that all commandline arguments are
12904 * parsed locally. The options dictionary should then be used to
12905 * transmit the result of the parsing to the primary instance, where
12906 * g_variant_dict_lookup() can be used. For local options, it is
12907 * possible to either use @arg_data in the usual way, or to consult (and
12908 * potentially remove) the option from the options dictionary.
12910 * This function is new in GLib 2.40. Before then, the only real choice
12911 * was to send all of the commandline arguments (options and all) to the
12912 * primary instance for handling. #GApplication ignored them completely
12913 * on the local side. Calling this function "opts in" to the new
12914 * behaviour, and in particular, means that unrecognised options will be
12915 * treated as errors. Unrecognised options have never been ignored when
12916 * %G_APPLICATION_HANDLES_COMMAND_LINE is unset.
12918 * If #GApplication::handle-local-options needs to see the list of
12919 * filenames, then the use of %G_OPTION_REMAINING is recommended. If
12920 * @arg_data is %NULL then %G_OPTION_REMAINING can be used as a key into
12921 * the options dictionary. If you do use %G_OPTION_REMAINING then you
12922 * need to handle these arguments for yourself because once they are
12923 * consumed, they will no longer be visible to the default handling
12924 * (which treats them as filenames to be opened).
12926 * It is important to use the proper GVariant format when retrieving
12927 * the options with g_variant_dict_lookup():
12928 * - for %G_OPTION_ARG_NONE, use b
12929 * - for %G_OPTION_ARG_STRING, use &s
12930 * - for %G_OPTION_ARG_INT, use i
12931 * - for %G_OPTION_ARG_INT64, use x
12932 * - for %G_OPTION_ARG_DOUBLE, use d
12933 * - for %G_OPTION_ARG_FILENAME, use ^ay
12934 * - for %G_OPTION_ARG_STRING_ARRAY, use &as
12935 * - for %G_OPTION_ARG_FILENAME_ARRAY, use ^aay
12942 * g_application_add_option_group:
12943 * @application: the #GApplication
12944 * @group: (transfer full): a #GOptionGroup
12946 * Adds a #GOptionGroup to the commandline handling of @application.
12948 * This function is comparable to g_option_context_add_group().
12950 * Unlike g_application_add_main_option_entries(), this function does
12951 * not deal with %NULL @arg_data and never transmits options to the
12952 * primary instance.
12954 * The reason for that is because, by the time the options arrive at the
12955 * primary instance, it is typically too late to do anything with them.
12956 * Taking the GTK option group as an example: GTK will already have been
12957 * initialised by the time the #GApplication::command-line handler runs.
12958 * In the case that this is not the first-running instance of the
12959 * application, the existing instance may already have been running for
12960 * a very long time.
12962 * This means that the options from #GOptionGroup are only really usable
12963 * in the case that the instance of the application being run is the
12964 * first instance. Passing options like `--display=` or `--gdk-debug=`
12965 * on future runs will have no effect on the existing primary instance.
12967 * Calling this function will cause the options in the supplied option
12968 * group to be parsed, but it does not cause you to be "opted in" to the
12969 * new functionality whereby unrecognised options are rejected even if
12970 * %G_APPLICATION_HANDLES_COMMAND_LINE was given.
12977 * g_application_bind_busy_property:
12978 * @application: a #GApplication
12979 * @object: (type GObject.Object): a #GObject
12980 * @property: the name of a boolean property of @object
12982 * Marks @application as busy (see g_application_mark_busy()) while
12983 * @property on @object is %TRUE.
12985 * The binding holds a reference to @application while it is active, but
12986 * not to @object. Instead, the binding is destroyed when @object is
12994 * g_application_command_line_create_file_for_arg:
12995 * @cmdline: a #GApplicationCommandLine
12996 * @arg: an argument from @cmdline
12998 * Creates a #GFile corresponding to a filename that was given as part
12999 * of the invocation of @cmdline.
13001 * This differs from g_file_new_for_commandline_arg() in that it
13002 * resolves relative pathnames using the current working directory of
13003 * the invoking process rather than the local process.
13005 * Returns: (transfer full): a new #GFile
13011 * g_application_command_line_get_arguments:
13012 * @cmdline: a #GApplicationCommandLine
13013 * @argc: (out) (allow-none): the length of the arguments array, or %NULL
13015 * Gets the list of arguments that was passed on the command line.
13017 * The strings in the array may contain non-UTF-8 data on UNIX (such as
13018 * filenames or arguments given in the system locale) but are always in
13019 * UTF-8 on Windows.
13021 * If you wish to use the return value with #GOptionContext, you must
13022 * use g_option_context_parse_strv().
13024 * The return value is %NULL-terminated and should be freed using
13027 * Returns: (array length=argc) (transfer full): the string array
13028 * containing the arguments (the argv)
13034 * g_application_command_line_get_cwd:
13035 * @cmdline: a #GApplicationCommandLine
13037 * Gets the working directory of the command line invocation.
13038 * The string may contain non-utf8 data.
13040 * It is possible that the remote application did not send a working
13041 * directory, so this may be %NULL.
13043 * The return value should not be modified or freed and is valid for as
13044 * long as @cmdline exists.
13046 * Returns: (nullable) (type filename): the current directory, or %NULL
13052 * g_application_command_line_get_environ:
13053 * @cmdline: a #GApplicationCommandLine
13055 * Gets the contents of the 'environ' variable of the command line
13056 * invocation, as would be returned by g_get_environ(), ie as a
13057 * %NULL-terminated list of strings in the form 'NAME=VALUE'.
13058 * The strings may contain non-utf8 data.
13060 * The remote application usually does not send an environment. Use
13061 * %G_APPLICATION_SEND_ENVIRONMENT to affect that. Even with this flag
13062 * set it is possible that the environment is still not available (due
13063 * to invocation messages from other applications).
13065 * The return value should not be modified or freed and is valid for as
13066 * long as @cmdline exists.
13068 * See g_application_command_line_getenv() if you are only interested
13069 * in the value of a single environment variable.
13071 * Returns: (array zero-terminated=1) (transfer none): the environment
13072 * strings, or %NULL if they were not sent
13078 * g_application_command_line_get_exit_status:
13079 * @cmdline: a #GApplicationCommandLine
13081 * Gets the exit status of @cmdline. See
13082 * g_application_command_line_set_exit_status() for more information.
13084 * Returns: the exit status
13090 * g_application_command_line_get_is_remote:
13091 * @cmdline: a #GApplicationCommandLine
13093 * Determines if @cmdline represents a remote invocation.
13095 * Returns: %TRUE if the invocation was remote
13101 * g_application_command_line_get_options_dict:
13102 * @cmdline: a #GApplicationCommandLine
13104 * Gets the options there were passed to g_application_command_line().
13106 * If you did not override local_command_line() then these are the same
13107 * options that were parsed according to the #GOptionEntrys added to the
13108 * application with g_application_add_main_option_entries() and possibly
13109 * modified from your GApplication::handle-local-options handler.
13111 * If no options were sent then an empty dictionary is returned so that
13112 * you don't need to check for %NULL.
13114 * Returns: (transfer none): a #GVariantDict with the options
13120 * g_application_command_line_get_platform_data:
13121 * @cmdline: #GApplicationCommandLine
13123 * Gets the platform data associated with the invocation of @cmdline.
13125 * This is a #GVariant dictionary containing information about the
13126 * context in which the invocation occurred. It typically contains
13127 * information like the current working directory and the startup
13130 * For local invocation, it will be %NULL.
13132 * Returns: (nullable): the platform data, or %NULL
13138 * g_application_command_line_get_stdin:
13139 * @cmdline: a #GApplicationCommandLine
13141 * Gets the stdin of the invoking process.
13143 * The #GInputStream can be used to read data passed to the standard
13144 * input of the invoking process.
13145 * This doesn't work on all platforms. Presently, it is only available
13146 * on UNIX when using a DBus daemon capable of passing file descriptors.
13147 * If stdin is not available then %NULL will be returned. In the
13148 * future, support may be expanded to other platforms.
13150 * You must only call this function once per commandline invocation.
13152 * Returns: (transfer full): a #GInputStream for stdin
13158 * g_application_command_line_getenv:
13159 * @cmdline: a #GApplicationCommandLine
13160 * @name: the environment variable to get
13162 * Gets the value of a particular environment variable of the command
13163 * line invocation, as would be returned by g_getenv(). The strings may
13164 * contain non-utf8 data.
13166 * The remote application usually does not send an environment. Use
13167 * %G_APPLICATION_SEND_ENVIRONMENT to affect that. Even with this flag
13168 * set it is possible that the environment is still not available (due
13169 * to invocation messages from other applications).
13171 * The return value should not be modified or freed and is valid for as
13172 * long as @cmdline exists.
13174 * Returns: the value of the variable, or %NULL if unset or unsent
13180 * g_application_command_line_print:
13181 * @cmdline: a #GApplicationCommandLine
13182 * @format: a printf-style format string
13183 * @...: arguments, as per @format
13185 * Formats a message and prints it using the stdout print handler in the
13186 * invoking process.
13188 * If @cmdline is a local invocation then this is exactly equivalent to
13189 * g_print(). If @cmdline is remote then this is equivalent to calling
13190 * g_print() in the invoking process.
13197 * g_application_command_line_printerr:
13198 * @cmdline: a #GApplicationCommandLine
13199 * @format: a printf-style format string
13200 * @...: arguments, as per @format
13202 * Formats a message and prints it using the stderr print handler in the
13203 * invoking process.
13205 * If @cmdline is a local invocation then this is exactly equivalent to
13206 * g_printerr(). If @cmdline is remote then this is equivalent to
13207 * calling g_printerr() in the invoking process.
13214 * g_application_command_line_set_exit_status:
13215 * @cmdline: a #GApplicationCommandLine
13216 * @exit_status: the exit status
13218 * Sets the exit status that will be used when the invoking process
13221 * The return value of the #GApplication::command-line signal is
13222 * passed to this function when the handler returns. This is the usual
13223 * way of setting the exit status.
13225 * In the event that you want the remote invocation to continue running
13226 * and want to decide on the exit status in the future, you can use this
13227 * call. For the case of a remote invocation, the remote process will
13228 * typically exit when the last reference is dropped on @cmdline. The
13229 * exit status of the remote process will be equal to the last value
13230 * that was set with this function.
13232 * In the case that the commandline invocation is local, the situation
13233 * is slightly more complicated. If the commandline invocation results
13234 * in the mainloop running (ie: because the use-count of the application
13235 * increased to a non-zero value) then the application is considered to
13236 * have been 'successful' in a certain sense, and the exit status is
13237 * always zero. If the application use count is zero, though, the exit
13238 * status of the local #GApplicationCommandLine is used.
13245 * g_application_get_application_id:
13246 * @application: a #GApplication
13248 * Gets the unique identifier for @application.
13250 * Returns: the identifier for @application, owned by @application
13256 * g_application_get_dbus_connection:
13257 * @application: a #GApplication
13259 * Gets the #GDBusConnection being used by the application, or %NULL.
13261 * If #GApplication is using its D-Bus backend then this function will
13262 * return the #GDBusConnection being used for uniqueness and
13263 * communication with the desktop environment and other instances of the
13266 * If #GApplication is not using D-Bus then this function will return
13267 * %NULL. This includes the situation where the D-Bus backend would
13268 * normally be in use but we were unable to connect to the bus.
13270 * This function must not be called before the application has been
13271 * registered. See g_application_get_is_registered().
13273 * Returns: (transfer none): a #GDBusConnection, or %NULL
13279 * g_application_get_dbus_object_path:
13280 * @application: a #GApplication
13282 * Gets the D-Bus object path being used by the application, or %NULL.
13284 * If #GApplication is using its D-Bus backend then this function will
13285 * return the D-Bus object path that #GApplication is using. If the
13286 * application is the primary instance then there is an object published
13287 * at this path. If the application is not the primary instance then
13288 * the result of this function is undefined.
13290 * If #GApplication is not using D-Bus then this function will return
13291 * %NULL. This includes the situation where the D-Bus backend would
13292 * normally be in use but we were unable to connect to the bus.
13294 * This function must not be called before the application has been
13295 * registered. See g_application_get_is_registered().
13297 * Returns: the object path, or %NULL
13303 * g_application_get_default:
13305 * Returns the default #GApplication instance for this process.
13307 * Normally there is only one #GApplication per process and it becomes
13308 * the default when it is created. You can exercise more control over
13309 * this by using g_application_set_default().
13311 * If there is no default application then %NULL is returned.
13313 * Returns: (transfer none): the default application for this process, or %NULL
13319 * g_application_get_flags:
13320 * @application: a #GApplication
13322 * Gets the flags for @application.
13324 * See #GApplicationFlags.
13326 * Returns: the flags for @application
13332 * g_application_get_inactivity_timeout:
13333 * @application: a #GApplication
13335 * Gets the current inactivity timeout for the application.
13337 * This is the amount of time (in milliseconds) after the last call to
13338 * g_application_release() before the application stops running.
13340 * Returns: the timeout, in milliseconds
13346 * g_application_get_is_busy:
13347 * @application: a #GApplication
13349 * Gets the application's current busy state, as set through
13350 * g_application_mark_busy() or g_application_bind_busy_property().
13352 * Returns: %TRUE if @application is currenty marked as busy
13358 * g_application_get_is_registered:
13359 * @application: a #GApplication
13361 * Checks if @application is registered.
13363 * An application is registered if g_application_register() has been
13364 * successfully called.
13366 * Returns: %TRUE if @application is registered
13372 * g_application_get_is_remote:
13373 * @application: a #GApplication
13375 * Checks if @application is remote.
13377 * If @application is remote then it means that another instance of
13378 * application already exists (the 'primary' instance). Calls to
13379 * perform actions on @application will result in the actions being
13380 * performed by the primary instance.
13382 * The value of this property cannot be accessed before
13383 * g_application_register() has been called. See
13384 * g_application_get_is_registered().
13386 * Returns: %TRUE if @application is remote
13392 * g_application_get_resource_base_path:
13393 * @application: a #GApplication
13395 * Gets the resource base path of @application.
13397 * See g_application_set_resource_base_path() for more information.
13399 * Returns: (nullable): the base resource path, if one is set
13405 * g_application_hold:
13406 * @application: a #GApplication
13408 * Increases the use count of @application.
13410 * Use this function to indicate that the application has a reason to
13411 * continue to run. For example, g_application_hold() is called by GTK+
13412 * when a toplevel window is on the screen.
13414 * To cancel the hold, call g_application_release().
13419 * g_application_id_is_valid:
13420 * @application_id: a potential application identifier
13422 * Checks if @application_id is a valid application identifier.
13424 * A valid ID is required for calls to g_application_new() and
13425 * g_application_set_application_id().
13427 * For convenience, the restrictions on application identifiers are
13430 * - Application identifiers must contain only the ASCII characters
13431 * "[A-Z][a-z][0-9]_-." and must not begin with a digit.
13433 * - Application identifiers must contain at least one '.' (period)
13434 * character (and thus at least three elements).
13436 * - Application identifiers must not begin or end with a '.' (period)
13439 * - Application identifiers must not contain consecutive '.' (period)
13442 * - Application identifiers must not exceed 255 characters.
13444 * Returns: %TRUE if @application_id is valid
13449 * g_application_mark_busy:
13450 * @application: a #GApplication
13452 * Increases the busy count of @application.
13454 * Use this function to indicate that the application is busy, for instance
13455 * while a long running operation is pending.
13457 * The busy state will be exposed to other processes, so a session shell will
13458 * use that information to indicate the state to the user (e.g. with a
13461 * To cancel the busy indication, use g_application_unmark_busy().
13468 * g_application_new:
13469 * @application_id: (allow-none): the application id
13470 * @flags: the application flags
13472 * Creates a new #GApplication instance.
13474 * If non-%NULL, the application id must be valid. See
13475 * g_application_id_is_valid().
13477 * If no application ID is given then some features of #GApplication
13478 * (most notably application uniqueness) will be disabled.
13480 * Returns: a new #GApplication instance
13485 * g_application_open:
13486 * @application: a #GApplication
13487 * @files: (array length=n_files): an array of #GFiles to open
13488 * @n_files: the length of the @files array
13489 * @hint: a hint (or ""), but never %NULL
13491 * Opens the given files.
13493 * In essence, this results in the #GApplication::open signal being emitted
13494 * in the primary instance.
13496 * @n_files must be greater than zero.
13498 * @hint is simply passed through to the ::open signal. It is
13499 * intended to be used by applications that have multiple modes for
13500 * opening files (eg: "view" vs "edit", etc). Unless you have a need
13501 * for this functionality, you should use "".
13503 * The application must be registered before calling this function
13504 * and it must have the %G_APPLICATION_HANDLES_OPEN flag set.
13511 * g_application_quit:
13512 * @application: a #GApplication
13514 * Immediately quits the application.
13516 * Upon return to the mainloop, g_application_run() will return,
13517 * calling only the 'shutdown' function before doing so.
13519 * The hold count is ignored.
13521 * The result of calling g_application_run() again after it returns is
13529 * g_application_register:
13530 * @application: a #GApplication
13531 * @cancellable: (allow-none): a #GCancellable, or %NULL
13532 * @error: a pointer to a NULL #GError, or %NULL
13534 * Attempts registration of the application.
13536 * This is the point at which the application discovers if it is the
13537 * primary instance or merely acting as a remote for an already-existing
13538 * primary instance. This is implemented by attempting to acquire the
13539 * application identifier as a unique bus name on the session bus using
13542 * If there is no application ID or if %G_APPLICATION_NON_UNIQUE was
13543 * given, then this process will always become the primary instance.
13545 * Due to the internal architecture of GDBus, method calls can be
13546 * dispatched at any time (even if a main loop is not running). For
13547 * this reason, you must ensure that any object paths that you wish to
13548 * register are registered before calling this function.
13550 * If the application has already been registered then %TRUE is
13551 * returned with no work performed.
13553 * The #GApplication::startup signal is emitted if registration succeeds
13554 * and @application is the primary instance (including the non-unique
13557 * In the event of an error (such as @cancellable being cancelled, or a
13558 * failure to connect to the session bus), %FALSE is returned and @error
13559 * is set appropriately.
13561 * Note: the return value of this function is not an indicator that this
13562 * instance is or is not the primary instance of the application. See
13563 * g_application_get_is_remote() for that.
13565 * Returns: %TRUE if registration succeeded
13571 * g_application_release:
13572 * @application: a #GApplication
13574 * Decrease the use count of @application.
13576 * When the use count reaches zero, the application will stop running.
13578 * Never call this function except to cancel the effect of a previous
13579 * call to g_application_hold().
13584 * g_application_run:
13585 * @application: a #GApplication
13586 * @argc: the argc from main() (or 0 if @argv is %NULL)
13587 * @argv: (array length=argc) (allow-none): the argv from main(), or %NULL
13589 * Runs the application.
13591 * This function is intended to be run from main() and its return value
13592 * is intended to be returned by main(). Although you are expected to pass
13593 * the @argc, @argv parameters from main() to this function, it is possible
13594 * to pass %NULL if @argv is not available or commandline handling is not
13595 * required. Note that on Windows, @argc and @argv are ignored, and
13596 * g_win32_get_command_line() is called internally (for proper support
13597 * of Unicode commandline arguments).
13599 * #GApplication will attempt to parse the commandline arguments. You
13600 * can add commandline flags to the list of recognised options by way of
13601 * g_application_add_main_option_entries(). After this, the
13602 * #GApplication::handle-local-options signal is emitted, from which the
13603 * application can inspect the values of its #GOptionEntrys.
13605 * #GApplication::handle-local-options is a good place to handle options
13606 * such as `--version`, where an immediate reply from the local process is
13607 * desired (instead of communicating with an already-running instance).
13608 * A #GApplication::handle-local-options handler can stop further processing
13609 * by returning a non-negative value, which then becomes the exit status of
13612 * What happens next depends on the flags: if
13613 * %G_APPLICATION_HANDLES_COMMAND_LINE was specified then the remaining
13614 * commandline arguments are sent to the primary instance, where a
13615 * #GApplication::command-line signal is emitted. Otherwise, the
13616 * remaining commandline arguments are assumed to be a list of files.
13617 * If there are no files listed, the application is activated via the
13618 * #GApplication::activate signal. If there are one or more files, and
13619 * %G_APPLICATION_HANDLES_OPEN was specified then the files are opened
13620 * via the #GApplication::open signal.
13622 * If you are interested in doing more complicated local handling of the
13623 * commandline then you should implement your own #GApplication subclass
13624 * and override local_command_line(). In this case, you most likely want
13625 * to return %TRUE from your local_command_line() implementation to
13626 * suppress the default handling. See
13627 * [gapplication-example-cmdline2.c][gapplication-example-cmdline2]
13630 * If, after the above is done, the use count of the application is zero
13631 * then the exit status is returned immediately. If the use count is
13632 * non-zero then the default main context is iterated until the use count
13633 * falls to zero, at which point 0 is returned.
13635 * If the %G_APPLICATION_IS_SERVICE flag is set, then the service will
13636 * run for as much as 10 seconds with a use count of zero while waiting
13637 * for the message that caused the activation to arrive. After that,
13638 * if the use count falls to zero the application will exit immediately,
13639 * except in the case that g_application_set_inactivity_timeout() is in
13642 * This function sets the prgname (g_set_prgname()), if not already set,
13643 * to the basename of argv[0].
13645 * Much like g_main_loop_run(), this function will acquire the main context
13646 * for the duration that the application is running.
13648 * Since 2.40, applications that are not explicitly flagged as services
13649 * or launchers (ie: neither %G_APPLICATION_IS_SERVICE or
13650 * %G_APPLICATION_IS_LAUNCHER are given as flags) will check (from the
13651 * default handler for local_command_line) if "--gapplication-service"
13652 * was given in the command line. If this flag is present then normal
13653 * commandline processing is interrupted and the
13654 * %G_APPLICATION_IS_SERVICE flag is set. This provides a "compromise"
13655 * solution whereby running an application directly from the commandline
13656 * will invoke it in the normal way (which can be useful for debugging)
13657 * while still allowing applications to be D-Bus activated in service
13658 * mode. The D-Bus service file should invoke the executable with
13659 * "--gapplication-service" as the sole commandline argument. This
13660 * approach is suitable for use by most graphical applications but
13661 * should not be used from applications like editors that need precise
13662 * control over when processes invoked via the commandline will exit and
13663 * what their exit status will be.
13665 * Returns: the exit status
13671 * g_application_send_notification:
13672 * @application: a #GApplication
13673 * @id: (allow-none): id of the notification, or %NULL
13674 * @notification: the #GNotification to send
13676 * Sends a notification on behalf of @application to the desktop shell.
13677 * There is no guarantee that the notification is displayed immediately,
13680 * Notifications may persist after the application exits. It will be
13681 * D-Bus-activated when the notification or one of its actions is
13684 * Modifying @notification after this call has no effect. However, the
13685 * object can be reused for a later call to this function.
13687 * @id may be any string that uniquely identifies the event for the
13688 * application. It does not need to be in any special format. For
13689 * example, "new-message" might be appropriate for a notification about
13692 * If a previous notification was sent with the same @id, it will be
13693 * replaced with @notification and shown again as if it was a new
13694 * notification. This works even for notifications sent from a previous
13695 * execution of the application, as long as @id is the same string.
13697 * @id may be %NULL, but it is impossible to replace or withdraw
13698 * notifications without an id.
13700 * If @notification is no longer relevant, it can be withdrawn with
13701 * g_application_withdraw_notification().
13708 * g_application_set_action_group:
13709 * @application: a #GApplication
13710 * @action_group: (allow-none): a #GActionGroup, or %NULL
13712 * This used to be how actions were associated with a #GApplication.
13713 * Now there is #GActionMap for that.
13716 * Deprecated: 2.32: Use the #GActionMap interface instead. Never ever
13717 * mix use of this API with use of #GActionMap on the same @application
13718 * or things will go very badly wrong. This function is known to
13719 * introduce buggy behaviour (ie: signals not emitted on changes to the
13720 * action group), so you should really use #GActionMap instead.
13725 * g_application_set_application_id:
13726 * @application: a #GApplication
13727 * @application_id: (allow-none): the identifier for @application
13729 * Sets the unique identifier for @application.
13731 * The application id can only be modified if @application has not yet
13734 * If non-%NULL, the application id must be valid. See
13735 * g_application_id_is_valid().
13742 * g_application_set_default:
13743 * @application: (allow-none): the application to set as default, or %NULL
13745 * Sets or unsets the default application for the process, as returned
13746 * by g_application_get_default().
13748 * This function does not take its own reference on @application. If
13749 * @application is destroyed then the default application will revert
13757 * g_application_set_flags:
13758 * @application: a #GApplication
13759 * @flags: the flags for @application
13761 * Sets the flags for @application.
13763 * The flags can only be modified if @application has not yet been
13766 * See #GApplicationFlags.
13773 * g_application_set_inactivity_timeout:
13774 * @application: a #GApplication
13775 * @inactivity_timeout: the timeout, in milliseconds
13777 * Sets the current inactivity timeout for the application.
13779 * This is the amount of time (in milliseconds) after the last call to
13780 * g_application_release() before the application stops running.
13782 * This call has no side effects of its own. The value set here is only
13783 * used for next time g_application_release() drops the use count to
13784 * zero. Any timeouts currently in progress are not impacted.
13791 * g_application_set_resource_base_path:
13792 * @application: a #GApplication
13793 * @resource_path: (nullable): the resource path to use
13795 * Sets (or unsets) the base resource path of @application.
13797 * The path is used to automatically load various [application
13798 * resources][gresource] such as menu layouts and action descriptions.
13799 * The various types of resources will be found at fixed names relative
13800 * to the given base path.
13802 * By default, the resource base path is determined from the application
13803 * ID by prefixing '/' and replacing each '.' with '/'. This is done at
13804 * the time that the #GApplication object is constructed. Changes to
13805 * the application ID after that point will not have an impact on the
13806 * resource base path.
13808 * As an example, if the application has an ID of "org.example.app" then
13809 * the default resource base path will be "/org/example/app". If this
13810 * is a #GtkApplication (and you have not manually changed the path)
13811 * then Gtk will then search for the menus of the application at
13812 * "/org/example/app/gtk/menus.ui".
13814 * See #GResource for more information about adding resources to your
13817 * You can disable automatic resource loading functionality by setting
13818 * the path to %NULL.
13820 * Changing the resource base path once the application is running is
13821 * not recommended. The point at which the resource path is consulted
13822 * for forming paths for various purposes is unspecified. When writing
13823 * a sub-class of #GApplication you should either set the
13824 * #GApplication:resource-base-path property at construction time, or call
13825 * this function during the instance initialization. Alternatively, you
13826 * can call this function in the #GApplicationClass.startup virtual function,
13827 * before chaining up to the parent implementation.
13834 * g_application_unbind_busy_property:
13835 * @application: a #GApplication
13836 * @object: (type GObject.Object): a #GObject
13837 * @property: the name of a boolean property of @object
13839 * Destroys a binding between @property and the busy state of
13840 * @application that was previously created with
13841 * g_application_bind_busy_property().
13848 * g_application_unmark_busy:
13849 * @application: a #GApplication
13851 * Decreases the busy count of @application.
13853 * When the busy count reaches zero, the new state will be propagated
13854 * to other processes.
13856 * This function must only be called to cancel the effect of a previous
13857 * call to g_application_mark_busy().
13864 * g_application_withdraw_notification:
13865 * @application: a #GApplication
13866 * @id: id of a previously sent notification
13868 * Withdraws a notification that was sent with
13869 * g_application_send_notification().
13871 * This call does nothing if a notification with @id doesn't exist or
13872 * the notification was never sent.
13874 * This function works even for notifications sent in previous
13875 * executions of this application, as long @id is the same as it was for
13876 * the sent notification.
13878 * Note that notifications are dismissed when the user clicks on one
13879 * of the buttons in a notification or triggers its default action, so
13880 * there is no need to explicitly withdraw the notification in that case.
13887 * g_async_initable_init_async:
13888 * @initable: a #GAsyncInitable.
13889 * @io_priority: the [I/O priority][io-priority] of the operation
13890 * @cancellable: optional #GCancellable object, %NULL to ignore.
13891 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
13892 * @user_data: the data to pass to callback function
13894 * Starts asynchronous initialization of the object implementing the
13895 * interface. This must be done before any real use of the object after
13896 * initial construction. If the object also implements #GInitable you can
13897 * optionally call g_initable_init() instead.
13899 * When the initialization is finished, @callback will be called. You can
13900 * then call g_async_initable_init_finish() to get the result of the
13903 * Implementations may also support cancellation. If @cancellable is not
13904 * %NULL, then initialization can be cancelled by triggering the cancellable
13905 * object from another thread. If the operation was cancelled, the error
13906 * %G_IO_ERROR_CANCELLED will be returned. If @cancellable is not %NULL, and
13907 * the object doesn't support cancellable initialization, the error
13908 * %G_IO_ERROR_NOT_SUPPORTED will be returned.
13910 * As with #GInitable, if the object is not initialized, or initialization
13911 * returns with an error, then all operations on the object except
13912 * g_object_ref() and g_object_unref() are considered to be invalid, and
13913 * have undefined behaviour. They will often fail with g_critical() or
13914 * g_warning(), but this must not be relied on.
13916 * Implementations of this method must be idempotent: i.e. multiple calls
13917 * to this function with the same argument should return the same results.
13918 * Only the first call initializes the object; further calls return the result
13919 * of the first call. This is so that it's safe to implement the singleton
13920 * pattern in the GObject constructor function.
13922 * For classes that also support the #GInitable interface, the default
13923 * implementation of this method will run the g_initable_init() function
13924 * in a thread, so if you want to support asynchronous initialization via
13925 * threads, just implement the #GAsyncInitable interface without overriding
13926 * any interface methods.
13933 * g_async_initable_init_finish:
13934 * @initable: a #GAsyncInitable.
13935 * @res: a #GAsyncResult.
13936 * @error: a #GError location to store the error occurring, or %NULL to
13939 * Finishes asynchronous initialization and returns the result.
13940 * See g_async_initable_init_async().
13942 * Returns: %TRUE if successful. If an error has occurred, this function
13943 * will return %FALSE and set @error appropriately if present.
13949 * g_async_initable_new_async:
13950 * @object_type: a #GType supporting #GAsyncInitable.
13951 * @io_priority: the [I/O priority][io-priority] of the operation
13952 * @cancellable: optional #GCancellable object, %NULL to ignore.
13953 * @callback: a #GAsyncReadyCallback to call when the initialization is
13955 * @user_data: the data to pass to callback function
13956 * @first_property_name: (allow-none): the name of the first property, or %NULL if no
13958 * @...: the value of the first property, followed by other property
13959 * value pairs, and ended by %NULL.
13961 * Helper function for constructing #GAsyncInitable object. This is
13962 * similar to g_object_new() but also initializes the object asynchronously.
13964 * When the initialization is finished, @callback will be called. You can
13965 * then call g_async_initable_new_finish() to get the new object and check
13973 * g_async_initable_new_finish:
13974 * @initable: the #GAsyncInitable from the callback
13975 * @res: the #GAsyncResult from the callback
13976 * @error: return location for errors, or %NULL to ignore
13978 * Finishes the async construction for the various g_async_initable_new
13979 * calls, returning the created object or %NULL on error.
13981 * Returns: (type GObject.Object) (transfer full): a newly created #GObject,
13982 * or %NULL on error. Free with g_object_unref().
13988 * g_async_initable_new_valist_async:
13989 * @object_type: a #GType supporting #GAsyncInitable.
13990 * @first_property_name: the name of the first property, followed by
13991 * the value, and other property value pairs, and ended by %NULL.
13992 * @var_args: The var args list generated from @first_property_name.
13993 * @io_priority: the [I/O priority][io-priority] of the operation
13994 * @cancellable: optional #GCancellable object, %NULL to ignore.
13995 * @callback: a #GAsyncReadyCallback to call when the initialization is
13997 * @user_data: the data to pass to callback function
13999 * Helper function for constructing #GAsyncInitable object. This is
14000 * similar to g_object_new_valist() but also initializes the object
14003 * When the initialization is finished, @callback will be called. You can
14004 * then call g_async_initable_new_finish() to get the new object and check
14012 * g_async_initable_newv_async:
14013 * @object_type: a #GType supporting #GAsyncInitable.
14014 * @n_parameters: the number of parameters in @parameters
14015 * @parameters: the parameters to use to construct the object
14016 * @io_priority: the [I/O priority][io-priority] of the operation
14017 * @cancellable: optional #GCancellable object, %NULL to ignore.
14018 * @callback: a #GAsyncReadyCallback to call when the initialization is
14020 * @user_data: the data to pass to callback function
14022 * Helper function for constructing #GAsyncInitable object. This is
14023 * similar to g_object_newv() but also initializes the object asynchronously.
14025 * When the initialization is finished, @callback will be called. You can
14026 * then call g_async_initable_new_finish() to get the new object and check
14034 * g_async_result_get_source_object:
14035 * @res: a #GAsyncResult
14037 * Gets the source object from a #GAsyncResult.
14039 * Returns: (transfer full): a new reference to the source object for the @res,
14040 * or %NULL if there is none.
14045 * g_async_result_get_user_data:
14046 * @res: a #GAsyncResult.
14048 * Gets the user data from a #GAsyncResult.
14050 * Returns: (transfer full): the user data for @res.
14055 * g_async_result_is_tagged:
14056 * @res: a #GAsyncResult
14057 * @source_tag: an application-defined tag
14059 * Checks if @res has the given @source_tag (generally a function
14060 * pointer indicating the function @res was created by).
14062 * Returns: %TRUE if @res has the indicated @source_tag, %FALSE if
14069 * g_async_result_legacy_propagate_error:
14070 * @res: a #GAsyncResult
14071 * @error: (out): a location to propagate the error to.
14073 * If @res is a #GSimpleAsyncResult, this is equivalent to
14074 * g_simple_async_result_propagate_error(). Otherwise it returns
14077 * This can be used for legacy error handling in async *_finish()
14078 * wrapper functions that traditionally handled #GSimpleAsyncResult
14079 * error returns themselves rather than calling into the virtual method.
14080 * This should not be used in new code; #GAsyncResult errors that are
14081 * set by virtual methods should also be extracted by virtual methods,
14082 * to enable subclasses to chain up correctly.
14084 * Returns: %TRUE if @error is has been filled in with an error from
14085 * @res, %FALSE if not.
14091 * g_buffered_input_stream_fill:
14092 * @stream: a #GBufferedInputStream
14093 * @count: the number of bytes that will be read from the stream
14094 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
14095 * @error: location to store the error occurring, or %NULL to ignore
14097 * Tries to read @count bytes from the stream into the buffer.
14098 * Will block during this read.
14100 * If @count is zero, returns zero and does nothing. A value of @count
14101 * larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
14103 * On success, the number of bytes read into the buffer is returned.
14104 * It is not an error if this is not the same as the requested size, as it
14105 * can happen e.g. near the end of a file. Zero is returned on end of file
14106 * (or if @count is zero), but never otherwise.
14108 * If @count is -1 then the attempted read size is equal to the number of
14109 * bytes that are required to fill the buffer.
14111 * If @cancellable is not %NULL, then the operation can be cancelled by
14112 * triggering the cancellable object from another thread. If the operation
14113 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
14114 * operation was partially finished when the operation was cancelled the
14115 * partial result will be returned, without an error.
14117 * On error -1 is returned and @error is set accordingly.
14119 * For the asynchronous, non-blocking, version of this function, see
14120 * g_buffered_input_stream_fill_async().
14122 * Returns: the number of bytes read into @stream's buffer, up to @count,
14128 * g_buffered_input_stream_fill_async:
14129 * @stream: a #GBufferedInputStream
14130 * @count: the number of bytes that will be read from the stream
14131 * @io_priority: the [I/O priority][io-priority] of the request
14132 * @cancellable: (allow-none): optional #GCancellable object
14133 * @callback: (scope async): a #GAsyncReadyCallback
14134 * @user_data: (closure): a #gpointer
14136 * Reads data into @stream's buffer asynchronously, up to @count size.
14137 * @io_priority can be used to prioritize reads. For the synchronous
14138 * version of this function, see g_buffered_input_stream_fill().
14140 * If @count is -1 then the attempted read size is equal to the number
14141 * of bytes that are required to fill the buffer.
14146 * g_buffered_input_stream_fill_finish:
14147 * @stream: a #GBufferedInputStream
14148 * @result: a #GAsyncResult
14149 * @error: a #GError
14151 * Finishes an asynchronous read.
14153 * Returns: a #gssize of the read stream, or %-1 on an error.
14158 * g_buffered_input_stream_get_available:
14159 * @stream: #GBufferedInputStream
14161 * Gets the size of the available data within the stream.
14163 * Returns: size of the available stream.
14168 * g_buffered_input_stream_get_buffer_size:
14169 * @stream: a #GBufferedInputStream
14171 * Gets the size of the input buffer.
14173 * Returns: the current buffer size.
14178 * g_buffered_input_stream_new:
14179 * @base_stream: a #GInputStream
14181 * Creates a new #GInputStream from the given @base_stream, with
14182 * a buffer set to the default size (4 kilobytes).
14184 * Returns: a #GInputStream for the given @base_stream.
14189 * g_buffered_input_stream_new_sized:
14190 * @base_stream: a #GInputStream
14193 * Creates a new #GBufferedInputStream from the given @base_stream,
14194 * with a buffer set to @size.
14196 * Returns: a #GInputStream.
14201 * g_buffered_input_stream_peek:
14202 * @stream: a #GBufferedInputStream
14203 * @buffer: (array length=count) (element-type guint8): a pointer to
14204 * an allocated chunk of memory
14205 * @offset: a #gsize
14208 * Peeks in the buffer, copying data of size @count into @buffer,
14209 * offset @offset bytes.
14211 * Returns: a #gsize of the number of bytes peeked, or -1 on error.
14216 * g_buffered_input_stream_peek_buffer:
14217 * @stream: a #GBufferedInputStream
14218 * @count: (out): a #gsize to get the number of bytes available in the buffer
14220 * Returns the buffer with the currently available bytes. The returned
14221 * buffer must not be modified and will become invalid when reading from
14222 * the stream or filling the buffer.
14224 * Returns: (array length=count) (element-type guint8) (transfer none):
14230 * g_buffered_input_stream_read_byte:
14231 * @stream: a #GBufferedInputStream
14232 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
14233 * @error: location to store the error occurring, or %NULL to ignore
14235 * Tries to read a single byte from the stream or the buffer. Will block
14236 * during this read.
14238 * On success, the byte read from the stream is returned. On end of stream
14239 * -1 is returned but it's not an exceptional error and @error is not set.
14241 * If @cancellable is not %NULL, then the operation can be cancelled by
14242 * triggering the cancellable object from another thread. If the operation
14243 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
14244 * operation was partially finished when the operation was cancelled the
14245 * partial result will be returned, without an error.
14247 * On error -1 is returned and @error is set accordingly.
14249 * Returns: the byte read from the @stream, or -1 on end of stream or error.
14254 * g_buffered_input_stream_set_buffer_size:
14255 * @stream: a #GBufferedInputStream
14258 * Sets the size of the internal buffer of @stream to @size, or to the
14259 * size of the contents of the buffer. The buffer can never be resized
14260 * smaller than its current contents.
14265 * g_buffered_output_stream_get_auto_grow:
14266 * @stream: a #GBufferedOutputStream.
14268 * Checks if the buffer automatically grows as data is added.
14270 * Returns: %TRUE if the @stream's buffer automatically grows,
14271 * %FALSE otherwise.
14276 * g_buffered_output_stream_get_buffer_size:
14277 * @stream: a #GBufferedOutputStream.
14279 * Gets the size of the buffer in the @stream.
14281 * Returns: the current size of the buffer.
14286 * g_buffered_output_stream_new:
14287 * @base_stream: a #GOutputStream.
14289 * Creates a new buffered output stream for a base stream.
14291 * Returns: a #GOutputStream for the given @base_stream.
14296 * g_buffered_output_stream_new_sized:
14297 * @base_stream: a #GOutputStream.
14300 * Creates a new buffered output stream with a given buffer size.
14302 * Returns: a #GOutputStream with an internal buffer set to @size.
14307 * g_buffered_output_stream_set_auto_grow:
14308 * @stream: a #GBufferedOutputStream.
14309 * @auto_grow: a #gboolean.
14311 * Sets whether or not the @stream's buffer should automatically grow.
14312 * If @auto_grow is true, then each write will just make the buffer
14313 * larger, and you must manually flush the buffer to actually write out
14314 * the data to the underlying stream.
14319 * g_buffered_output_stream_set_buffer_size:
14320 * @stream: a #GBufferedOutputStream.
14323 * Sets the size of the internal buffer to @size.
14329 * @bus_type: a #GBusType
14330 * @cancellable: (allow-none): a #GCancellable or %NULL
14331 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
14332 * @user_data: the data to pass to @callback
14334 * Asynchronously connects to the message bus specified by @bus_type.
14336 * When the operation is finished, @callback will be invoked. You can
14337 * then call g_bus_get_finish() to get the result of the operation.
14339 * This is a asynchronous failable function. See g_bus_get_sync() for
14340 * the synchronous version.
14347 * g_bus_get_finish:
14348 * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed
14350 * @error: return location for error or %NULL
14352 * Finishes an operation started with g_bus_get().
14354 * The returned object is a singleton, that is, shared with other
14355 * callers of g_bus_get() and g_bus_get_sync() for @bus_type. In the
14356 * event that you need a private message bus connection, use
14357 * g_dbus_address_get_for_bus_sync() and
14358 * g_dbus_connection_new_for_address().
14360 * Note that the returned #GDBusConnection object will (usually) have
14361 * the #GDBusConnection:exit-on-close property set to %TRUE.
14363 * Returns: (transfer full): a #GDBusConnection or %NULL if @error is set.
14364 * Free with g_object_unref().
14371 * @bus_type: a #GBusType
14372 * @cancellable: (allow-none): a #GCancellable or %NULL
14373 * @error: return location for error or %NULL
14375 * Synchronously connects to the message bus specified by @bus_type.
14376 * Note that the returned object may shared with other callers,
14377 * e.g. if two separate parts of a process calls this function with
14378 * the same @bus_type, they will share the same object.
14380 * This is a synchronous failable function. See g_bus_get() and
14381 * g_bus_get_finish() for the asynchronous version.
14383 * The returned object is a singleton, that is, shared with other
14384 * callers of g_bus_get() and g_bus_get_sync() for @bus_type. In the
14385 * event that you need a private message bus connection, use
14386 * g_dbus_address_get_for_bus_sync() and
14387 * g_dbus_connection_new_for_address().
14389 * Note that the returned #GDBusConnection object will (usually) have
14390 * the #GDBusConnection:exit-on-close property set to %TRUE.
14392 * Returns: (transfer full): a #GDBusConnection or %NULL if @error is set.
14393 * Free with g_object_unref().
14400 * @bus_type: the type of bus to own a name on
14401 * @name: the well-known name to own
14402 * @flags: a set of flags from the #GBusNameOwnerFlags enumeration
14403 * @bus_acquired_handler: (allow-none): handler to invoke when connected to the bus of type @bus_type or %NULL
14404 * @name_acquired_handler: (allow-none): handler to invoke when @name is acquired or %NULL
14405 * @name_lost_handler: (allow-none): handler to invoke when @name is lost or %NULL
14406 * @user_data: user data to pass to handlers
14407 * @user_data_free_func: (allow-none): function for freeing @user_data or %NULL
14409 * Starts acquiring @name on the bus specified by @bus_type and calls
14410 * @name_acquired_handler and @name_lost_handler when the name is
14411 * acquired respectively lost. Callbacks will be invoked in the
14412 * [thread-default main context][g-main-context-push-thread-default]
14413 * of the thread you are calling this function from.
14415 * You are guaranteed that one of the @name_acquired_handler and @name_lost_handler
14416 * callbacks will be invoked after calling this function - there are three
14419 * - @name_lost_handler with a %NULL connection (if a connection to the bus
14422 * - @bus_acquired_handler then @name_lost_handler (if the name can't be
14425 * - @bus_acquired_handler then @name_acquired_handler (if the name was
14428 * When you are done owning the name, just call g_bus_unown_name()
14429 * with the owner id this function returns.
14431 * If the name is acquired or lost (for example another application
14432 * could acquire the name if you allow replacement or the application
14433 * currently owning the name exits), the handlers are also invoked.
14434 * If the #GDBusConnection that is used for attempting to own the name
14435 * closes, then @name_lost_handler is invoked since it is no longer
14436 * possible for other processes to access the process.
14438 * You cannot use g_bus_own_name() several times for the same name (unless
14439 * interleaved with calls to g_bus_unown_name()) - only the first call
14442 * Another guarantee is that invocations of @name_acquired_handler
14443 * and @name_lost_handler are guaranteed to alternate; that
14444 * is, if @name_acquired_handler is invoked then you are
14445 * guaranteed that the next time one of the handlers is invoked, it
14446 * will be @name_lost_handler. The reverse is also true.
14448 * If you plan on exporting objects (using e.g.
14449 * g_dbus_connection_register_object()), note that it is generally too late
14450 * to export the objects in @name_acquired_handler. Instead, you can do this
14451 * in @bus_acquired_handler since you are guaranteed that this will run
14452 * before @name is requested from the bus.
14454 * This behavior makes it very simple to write applications that wants
14455 * to [own names][gdbus-owning-names] and export objects.
14456 * Simply register objects to be exported in @bus_acquired_handler and
14457 * unregister the objects (if any) in @name_lost_handler.
14459 * Returns: an identifier (never 0) that an be used with
14460 * g_bus_unown_name() to stop owning the name.
14466 * g_bus_own_name_on_connection:
14467 * @connection: a #GDBusConnection
14468 * @name: the well-known name to own
14469 * @flags: a set of flags from the #GBusNameOwnerFlags enumeration
14470 * @name_acquired_handler: (allow-none): handler to invoke when @name is acquired or %NULL
14471 * @name_lost_handler: (allow-none): handler to invoke when @name is lost or %NULL
14472 * @user_data: user data to pass to handlers
14473 * @user_data_free_func: (allow-none): function for freeing @user_data or %NULL
14475 * Like g_bus_own_name() but takes a #GDBusConnection instead of a
14478 * Returns: an identifier (never 0) that an be used with
14479 * g_bus_unown_name() to stop owning the name
14485 * g_bus_own_name_on_connection_with_closures: (rename-to g_bus_own_name_on_connection)
14486 * @connection: a #GDBusConnection
14487 * @name: the well-known name to own
14488 * @flags: a set of flags from the #GBusNameOwnerFlags enumeration
14489 * @name_acquired_closure: (allow-none): #GClosure to invoke when @name is
14490 * acquired or %NULL
14491 * @name_lost_closure: (allow-none): #GClosure to invoke when @name is lost
14494 * Version of g_bus_own_name_on_connection() using closures instead of
14495 * callbacks for easier binding in other languages.
14497 * Returns: an identifier (never 0) that an be used with
14498 * g_bus_unown_name() to stop owning the name.
14504 * g_bus_own_name_with_closures: (rename-to g_bus_own_name)
14505 * @bus_type: the type of bus to own a name on
14506 * @name: the well-known name to own
14507 * @flags: a set of flags from the #GBusNameOwnerFlags enumeration
14508 * @bus_acquired_closure: (allow-none): #GClosure to invoke when connected to
14509 * the bus of type @bus_type or %NULL
14510 * @name_acquired_closure: (allow-none): #GClosure to invoke when @name is
14511 * acquired or %NULL
14512 * @name_lost_closure: (allow-none): #GClosure to invoke when @name is lost or
14515 * Version of g_bus_own_name() using closures instead of callbacks for
14516 * easier binding in other languages.
14518 * Returns: an identifier (never 0) that an be used with
14519 * g_bus_unown_name() to stop owning the name.
14525 * g_bus_unown_name:
14526 * @owner_id: an identifier obtained from g_bus_own_name()
14528 * Stops owning a name.
14535 * g_bus_unwatch_name:
14536 * @watcher_id: An identifier obtained from g_bus_watch_name()
14538 * Stops watching a name.
14545 * g_bus_watch_name:
14546 * @bus_type: The type of bus to watch a name on.
14547 * @name: The name (well-known or unique) to watch.
14548 * @flags: Flags from the #GBusNameWatcherFlags enumeration.
14549 * @name_appeared_handler: (allow-none): Handler to invoke when @name is known to exist or %NULL.
14550 * @name_vanished_handler: (allow-none): Handler to invoke when @name is known to not exist or %NULL.
14551 * @user_data: User data to pass to handlers.
14552 * @user_data_free_func: (allow-none): Function for freeing @user_data or %NULL.
14554 * Starts watching @name on the bus specified by @bus_type and calls
14555 * @name_appeared_handler and @name_vanished_handler when the name is
14556 * known to have a owner respectively known to lose its
14557 * owner. Callbacks will be invoked in the
14558 * [thread-default main context][g-main-context-push-thread-default]
14559 * of the thread you are calling this function from.
14561 * You are guaranteed that one of the handlers will be invoked after
14562 * calling this function. When you are done watching the name, just
14563 * call g_bus_unwatch_name() with the watcher id this function
14566 * If the name vanishes or appears (for example the application owning
14567 * the name could restart), the handlers are also invoked. If the
14568 * #GDBusConnection that is used for watching the name disconnects, then
14569 * @name_vanished_handler is invoked since it is no longer
14570 * possible to access the name.
14572 * Another guarantee is that invocations of @name_appeared_handler
14573 * and @name_vanished_handler are guaranteed to alternate; that
14574 * is, if @name_appeared_handler is invoked then you are
14575 * guaranteed that the next time one of the handlers is invoked, it
14576 * will be @name_vanished_handler. The reverse is also true.
14578 * This behavior makes it very simple to write applications that want
14579 * to take action when a certain [name exists][gdbus-watching-names].
14580 * Basically, the application should create object proxies in
14581 * @name_appeared_handler and destroy them again (if any) in
14582 * @name_vanished_handler.
14584 * Returns: An identifier (never 0) that an be used with
14585 * g_bus_unwatch_name() to stop watching the name.
14591 * g_bus_watch_name_on_connection:
14592 * @connection: A #GDBusConnection.
14593 * @name: The name (well-known or unique) to watch.
14594 * @flags: Flags from the #GBusNameWatcherFlags enumeration.
14595 * @name_appeared_handler: (allow-none): Handler to invoke when @name is known to exist or %NULL.
14596 * @name_vanished_handler: (allow-none): Handler to invoke when @name is known to not exist or %NULL.
14597 * @user_data: User data to pass to handlers.
14598 * @user_data_free_func: (allow-none): Function for freeing @user_data or %NULL.
14600 * Like g_bus_watch_name() but takes a #GDBusConnection instead of a
14603 * Returns: An identifier (never 0) that an be used with
14604 * g_bus_unwatch_name() to stop watching the name.
14610 * g_bus_watch_name_on_connection_with_closures: (rename-to g_bus_watch_name_on_connection)
14611 * @connection: A #GDBusConnection.
14612 * @name: The name (well-known or unique) to watch.
14613 * @flags: Flags from the #GBusNameWatcherFlags enumeration.
14614 * @name_appeared_closure: (allow-none): #GClosure to invoke when @name is known
14615 * to exist or %NULL.
14616 * @name_vanished_closure: (allow-none): #GClosure to invoke when @name is known
14617 * to not exist or %NULL.
14619 * Version of g_bus_watch_name_on_connection() using closures instead of callbacks for
14620 * easier binding in other languages.
14622 * Returns: An identifier (never 0) that an be used with
14623 * g_bus_unwatch_name() to stop watching the name.
14629 * g_bus_watch_name_with_closures: (rename-to g_bus_watch_name)
14630 * @bus_type: The type of bus to watch a name on.
14631 * @name: The name (well-known or unique) to watch.
14632 * @flags: Flags from the #GBusNameWatcherFlags enumeration.
14633 * @name_appeared_closure: (allow-none): #GClosure to invoke when @name is known
14634 * to exist or %NULL.
14635 * @name_vanished_closure: (allow-none): #GClosure to invoke when @name is known
14636 * to not exist or %NULL.
14638 * Version of g_bus_watch_name() using closures instead of callbacks for
14639 * easier binding in other languages.
14641 * Returns: An identifier (never 0) that an be used with
14642 * g_bus_unwatch_name() to stop watching the name.
14648 * g_bytes_icon_get_bytes:
14651 * Gets the #GBytes associated with the given @icon.
14653 * Returns: (transfer none): a #GBytes, or %NULL.
14659 * g_bytes_icon_new:
14660 * @bytes: a #GBytes.
14662 * Creates a new icon for a bytes.
14664 * Returns: (transfer full) (type GBytesIcon): a #GIcon for the given
14665 * @bytes, or %NULL on error.
14671 * g_cancellable_cancel:
14672 * @cancellable: (nullable): a #GCancellable object.
14674 * Will set @cancellable to cancelled, and will emit the
14675 * #GCancellable::cancelled signal. (However, see the warning about
14676 * race conditions in the documentation for that signal if you are
14677 * planning to connect to it.)
14679 * This function is thread-safe. In other words, you can safely call
14680 * it from a thread other than the one running the operation that was
14681 * passed the @cancellable.
14683 * If @cancellable is %NULL, this function returns immediately for convenience.
14685 * The convention within GIO is that cancelling an asynchronous
14686 * operation causes it to complete asynchronously. That is, if you
14687 * cancel the operation from the same thread in which it is running,
14688 * then the operation's #GAsyncReadyCallback will not be invoked until
14689 * the application returns to the main loop.
14694 * g_cancellable_connect:
14695 * @cancellable: A #GCancellable.
14696 * @callback: The #GCallback to connect.
14697 * @data: Data to pass to @callback.
14698 * @data_destroy_func: (allow-none): Free function for @data or %NULL.
14700 * Convenience function to connect to the #GCancellable::cancelled
14701 * signal. Also handles the race condition that may happen
14702 * if the cancellable is cancelled right before connecting.
14704 * @callback is called at most once, either directly at the
14705 * time of the connect if @cancellable is already cancelled,
14706 * or when @cancellable is cancelled in some thread.
14708 * @data_destroy_func will be called when the handler is
14709 * disconnected, or immediately if the cancellable is already
14712 * See #GCancellable::cancelled for details on how to use this.
14714 * Since GLib 2.40, the lock protecting @cancellable is not held when
14715 * @callback is invoked. This lifts a restriction in place for
14716 * earlier GLib versions which now makes it easier to write cleanup
14717 * code that unconditionally invokes e.g. g_cancellable_cancel().
14719 * Returns: The id of the signal handler or 0 if @cancellable has already
14726 * g_cancellable_disconnect:
14727 * @cancellable: (allow-none): A #GCancellable or %NULL.
14728 * @handler_id: Handler id of the handler to be disconnected, or %0.
14730 * Disconnects a handler from a cancellable instance similar to
14731 * g_signal_handler_disconnect(). Additionally, in the event that a
14732 * signal handler is currently running, this call will block until the
14733 * handler has finished. Calling this function from a
14734 * #GCancellable::cancelled signal handler will therefore result in a
14737 * This avoids a race condition where a thread cancels at the
14738 * same time as the cancellable operation is finished and the
14739 * signal handler is removed. See #GCancellable::cancelled for
14740 * details on how to use this.
14742 * If @cancellable is %NULL or @handler_id is %0 this function does
14750 * g_cancellable_get_current:
14752 * Gets the top cancellable from the stack.
14754 * Returns: (nullable) (transfer none): a #GCancellable from the top
14755 * of the stack, or %NULL if the stack is empty.
14760 * g_cancellable_get_fd:
14761 * @cancellable: a #GCancellable.
14763 * Gets the file descriptor for a cancellable job. This can be used to
14764 * implement cancellable operations on Unix systems. The returned fd will
14765 * turn readable when @cancellable is cancelled.
14767 * You are not supposed to read from the fd yourself, just check for
14768 * readable status. Reading to unset the readable status is done
14769 * with g_cancellable_reset().
14771 * After a successful return from this function, you should use
14772 * g_cancellable_release_fd() to free up resources allocated for
14773 * the returned file descriptor.
14775 * See also g_cancellable_make_pollfd().
14777 * Returns: A valid file descriptor. %-1 if the file descriptor
14778 * is not supported, or on errors.
14783 * g_cancellable_is_cancelled:
14784 * @cancellable: (allow-none): a #GCancellable or %NULL
14786 * Checks if a cancellable job has been cancelled.
14788 * Returns: %TRUE if @cancellable is cancelled,
14789 * FALSE if called with %NULL or if item is not cancelled.
14794 * g_cancellable_make_pollfd:
14795 * @cancellable: (allow-none): a #GCancellable or %NULL
14796 * @pollfd: a pointer to a #GPollFD
14798 * Creates a #GPollFD corresponding to @cancellable; this can be passed
14799 * to g_poll() and used to poll for cancellation. This is useful both
14800 * for unix systems without a native poll and for portability to
14803 * When this function returns %TRUE, you should use
14804 * g_cancellable_release_fd() to free up resources allocated for the
14805 * @pollfd. After a %FALSE return, do not call g_cancellable_release_fd().
14807 * If this function returns %FALSE, either no @cancellable was given or
14808 * resource limits prevent this function from allocating the necessary
14809 * structures for polling. (On Linux, you will likely have reached
14810 * the maximum number of file descriptors.) The suggested way to handle
14811 * these cases is to ignore the @cancellable.
14813 * You are not supposed to read from the fd yourself, just check for
14814 * readable status. Reading to unset the readable status is done
14815 * with g_cancellable_reset().
14817 * Returns: %TRUE if @pollfd was successfully initialized, %FALSE on
14818 * failure to prepare the cancellable.
14824 * g_cancellable_new:
14826 * Creates a new #GCancellable object.
14828 * Applications that want to start one or more operations
14829 * that should be cancellable should create a #GCancellable
14830 * and pass it to the operations.
14832 * One #GCancellable can be used in multiple consecutive
14833 * operations or in multiple concurrent operations.
14835 * Returns: a #GCancellable.
14840 * g_cancellable_pop_current:
14841 * @cancellable: a #GCancellable object
14843 * Pops @cancellable off the cancellable stack (verifying that @cancellable
14844 * is on the top of the stack).
14849 * g_cancellable_push_current:
14850 * @cancellable: a #GCancellable object
14852 * Pushes @cancellable onto the cancellable stack. The current
14853 * cancellable can then be received using g_cancellable_get_current().
14855 * This is useful when implementing cancellable operations in
14856 * code that does not allow you to pass down the cancellable object.
14858 * This is typically called automatically by e.g. #GFile operations,
14859 * so you rarely have to call this yourself.
14864 * g_cancellable_release_fd:
14865 * @cancellable: a #GCancellable
14867 * Releases a resources previously allocated by g_cancellable_get_fd()
14868 * or g_cancellable_make_pollfd().
14870 * For compatibility reasons with older releases, calling this function
14871 * is not strictly required, the resources will be automatically freed
14872 * when the @cancellable is finalized. However, the @cancellable will
14873 * block scarce file descriptors until it is finalized if this function
14874 * is not called. This can cause the application to run out of file
14875 * descriptors when many #GCancellables are used at the same time.
14882 * g_cancellable_reset:
14883 * @cancellable: a #GCancellable object.
14885 * Resets @cancellable to its uncancelled state.
14887 * If cancellable is currently in use by any cancellable operation
14888 * then the behavior of this function is undefined.
14890 * Note that it is generally not a good idea to reuse an existing
14891 * cancellable for more operations after it has been cancelled once,
14892 * as this function might tempt you to do. The recommended practice
14893 * is to drop the reference to a cancellable after cancelling it,
14894 * and let it die with the outstanding async operations. You should
14895 * create a fresh cancellable for further async operations.
14900 * g_cancellable_set_error_if_cancelled:
14901 * @cancellable: (allow-none): a #GCancellable or %NULL
14902 * @error: #GError to append error state to
14904 * If the @cancellable is cancelled, sets the error to notify
14905 * that the operation was cancelled.
14907 * Returns: %TRUE if @cancellable was cancelled, %FALSE if it was not
14912 * g_cancellable_source_new: (skip)
14913 * @cancellable: (allow-none): a #GCancellable, or %NULL
14915 * Creates a source that triggers if @cancellable is cancelled and
14916 * calls its callback of type #GCancellableSourceFunc. This is
14917 * primarily useful for attaching to another (non-cancellable) source
14918 * with g_source_add_child_source() to add cancellability to it.
14920 * For convenience, you can call this with a %NULL #GCancellable,
14921 * in which case the source will never trigger.
14923 * The new #GSource will hold a reference to the #GCancellable.
14925 * Returns: (transfer full): the new #GSource.
14931 * g_charset_converter_get_num_fallbacks:
14932 * @converter: a #GCharsetConverter
14934 * Gets the number of fallbacks that @converter has applied so far.
14936 * Returns: the number of fallbacks that @converter has applied
14942 * g_charset_converter_get_use_fallback:
14943 * @converter: a #GCharsetConverter
14945 * Gets the #GCharsetConverter:use-fallback property.
14947 * Returns: %TRUE if fallbacks are used by @converter
14953 * g_charset_converter_new:
14954 * @to_charset: destination charset
14955 * @from_charset: source charset
14956 * @error: #GError for error reporting, or %NULL to ignore.
14958 * Creates a new #GCharsetConverter.
14960 * Returns: a new #GCharsetConverter or %NULL on error.
14966 * g_charset_converter_set_use_fallback:
14967 * @converter: a #GCharsetConverter
14968 * @use_fallback: %TRUE to use fallbacks
14970 * Sets the #GCharsetConverter:use-fallback property.
14977 * g_content_type_can_be_executable:
14978 * @type: a content type string
14980 * Checks if a content type can be executable. Note that for instance
14981 * things like text files can be executables (i.e. scripts and batch files).
14983 * Returns: %TRUE if the file type corresponds to a type that
14984 * can be executable, %FALSE otherwise.
14989 * g_content_type_equals:
14990 * @type1: a content type string
14991 * @type2: a content type string
14993 * Compares two content types for equality.
14995 * Returns: %TRUE if the two strings are identical or equivalent,
14996 * %FALSE otherwise.
15001 * g_content_type_from_mime_type:
15002 * @mime_type: a mime type string
15004 * Tries to find a content type based on the mime type name.
15006 * Returns: (nullable): Newly allocated string with content type or
15007 * %NULL. Free with g_free()
15013 * g_content_type_get_description:
15014 * @type: a content type string
15016 * Gets the human readable description of the content type.
15018 * Returns: a short description of the content type @type. Free the
15019 * returned string with g_free()
15024 * g_content_type_get_generic_icon_name:
15025 * @type: a content type string
15027 * Gets the generic icon name for a content type.
15030 * [shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec)
15031 * specification for more on the generic icon name.
15033 * Returns: (allow-none): the registered generic icon name for the given @type,
15034 * or %NULL if unknown. Free with g_free()
15040 * g_content_type_get_icon:
15041 * @type: a content type string
15043 * Gets the icon for a content type.
15045 * Returns: (transfer full): #GIcon corresponding to the content type. Free the returned
15046 * object with g_object_unref()
15051 * g_content_type_get_mime_type:
15052 * @type: a content type string
15054 * Gets the mime type for the content type, if one is registered.
15056 * Returns: (nullable): the registered mime type for the given @type,
15057 * or %NULL if unknown.
15062 * g_content_type_get_symbolic_icon:
15063 * @type: a content type string
15065 * Gets the symbolic icon for a content type.
15067 * Returns: (transfer full): symbolic #GIcon corresponding to the content type.
15068 * Free the returned object with g_object_unref()
15074 * g_content_type_guess:
15075 * @filename: (allow-none): a string, or %NULL
15076 * @data: (allow-none) (array length=data_size): a stream of data, or %NULL
15077 * @data_size: the size of @data
15078 * @result_uncertain: (allow-none) (out): return location for the certainty
15079 * of the result, or %NULL
15081 * Guesses the content type based on example data. If the function is
15082 * uncertain, @result_uncertain will be set to %TRUE. Either @filename
15083 * or @data may be %NULL, in which case the guess will be based solely
15084 * on the other argument.
15086 * Returns: a string indicating a guessed content type for the
15087 * given data. Free with g_free()
15092 * g_content_type_guess_for_tree:
15093 * @root: the root of the tree to guess a type for
15095 * Tries to guess the type of the tree with root @root, by
15096 * looking at the files it contains. The result is an array
15097 * of content types, with the best guess coming first.
15099 * The types returned all have the form x-content/foo, e.g.
15100 * x-content/audio-cdda (for audio CDs) or x-content/image-dcf
15101 * (for a camera memory card). See the
15102 * [shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec)
15103 * specification for more on x-content types.
15105 * This function is useful in the implementation of
15106 * g_mount_guess_content_type().
15108 * Returns: (transfer full) (array zero-terminated=1): an %NULL-terminated
15109 * array of zero or more content types. Free with g_strfreev()
15115 * g_content_type_is_a:
15116 * @type: a content type string
15117 * @supertype: a content type string
15119 * Determines if @type is a subset of @supertype.
15121 * Returns: %TRUE if @type is a kind of @supertype,
15122 * %FALSE otherwise.
15127 * g_content_type_is_unknown:
15128 * @type: a content type string
15130 * Checks if the content type is the generic "unknown" type.
15131 * On UNIX this is the "application/octet-stream" mimetype,
15132 * while on win32 it is "*".
15134 * Returns: %TRUE if the type is the unknown type.
15139 * g_content_types_get_registered:
15141 * Gets a list of strings containing all the registered content types
15142 * known to the system. The list and its data should be freed using
15143 * g_list_free_full (list, g_free).
15145 * Returns: (element-type utf8) (transfer full): list of the registered
15151 * g_converter_convert:
15152 * @converter: a #GConverter.
15153 * @inbuf: (array length=inbuf_size) (element-type guint8): the buffer
15154 * containing the data to convert.
15155 * @inbuf_size: the number of bytes in @inbuf
15156 * @outbuf: (element-type guint8) (array length=outbuf_size): a buffer to write
15157 * converted data in.
15158 * @outbuf_size: the number of bytes in @outbuf, must be at least one
15159 * @flags: a #GConverterFlags controlling the conversion details
15160 * @bytes_read: (out): will be set to the number of bytes read from @inbuf on success
15161 * @bytes_written: (out): will be set to the number of bytes written to @outbuf on success
15162 * @error: location to store the error occurring, or %NULL to ignore
15164 * This is the main operation used when converting data. It is to be called
15165 * multiple times in a loop, and each time it will do some work, i.e.
15166 * producing some output (in @outbuf) or consuming some input (from @inbuf) or
15167 * both. If its not possible to do any work an error is returned.
15169 * Note that a single call may not consume all input (or any input at all).
15170 * Also a call may produce output even if given no input, due to state stored
15171 * in the converter producing output.
15173 * If any data was either produced or consumed, and then an error happens, then
15174 * only the successful conversion is reported and the error is returned on the
15177 * A full conversion loop involves calling this method repeatedly, each time
15178 * giving it new input and space output space. When there is no more input
15179 * data after the data in @inbuf, the flag %G_CONVERTER_INPUT_AT_END must be set.
15180 * The loop will be (unless some error happens) returning %G_CONVERTER_CONVERTED
15181 * each time until all data is consumed and all output is produced, then
15182 * %G_CONVERTER_FINISHED is returned instead. Note, that %G_CONVERTER_FINISHED
15183 * may be returned even if %G_CONVERTER_INPUT_AT_END is not set, for instance
15184 * in a decompression converter where the end of data is detectable from the
15185 * data (and there might even be other data after the end of the compressed data).
15187 * When some data has successfully been converted @bytes_read and is set to
15188 * the number of bytes read from @inbuf, and @bytes_written is set to indicate
15189 * how many bytes was written to @outbuf. If there are more data to output
15190 * or consume (i.e. unless the %G_CONVERTER_INPUT_AT_END is specified) then
15191 * %G_CONVERTER_CONVERTED is returned, and if no more data is to be output
15192 * then %G_CONVERTER_FINISHED is returned.
15194 * On error %G_CONVERTER_ERROR is returned and @error is set accordingly.
15195 * Some errors need special handling:
15197 * %G_IO_ERROR_NO_SPACE is returned if there is not enough space
15198 * to write the resulting converted data, the application should
15199 * call the function again with a larger @outbuf to continue.
15201 * %G_IO_ERROR_PARTIAL_INPUT is returned if there is not enough
15202 * input to fully determine what the conversion should produce,
15203 * and the %G_CONVERTER_INPUT_AT_END flag is not set. This happens for
15204 * example with an incomplete multibyte sequence when converting text,
15205 * or when a regexp matches up to the end of the input (and may match
15206 * further input). It may also happen when @inbuf_size is zero and
15207 * there is no more data to produce.
15209 * When this happens the application should read more input and then
15210 * call the function again. If further input shows that there is no
15211 * more data call the function again with the same data but with
15212 * the %G_CONVERTER_INPUT_AT_END flag set. This may cause the conversion
15213 * to finish as e.g. in the regexp match case (or, to fail again with
15214 * %G_IO_ERROR_PARTIAL_INPUT in e.g. a charset conversion where the
15215 * input is actually partial).
15217 * After g_converter_convert() has returned %G_CONVERTER_FINISHED the
15218 * converter object is in an invalid state where its not allowed
15219 * to call g_converter_convert() anymore. At this time you can only
15220 * free the object or call g_converter_reset() to reset it to the
15223 * If the flag %G_CONVERTER_FLUSH is set then conversion is modified
15224 * to try to write out all internal state to the output. The application
15225 * has to call the function multiple times with the flag set, and when
15226 * the available input has been consumed and all internal state has
15227 * been produced then %G_CONVERTER_FLUSHED (or %G_CONVERTER_FINISHED if
15228 * really at the end) is returned instead of %G_CONVERTER_CONVERTED.
15229 * This is somewhat similar to what happens at the end of the input stream,
15230 * but done in the middle of the data.
15232 * This has different meanings for different conversions. For instance
15233 * in a compression converter it would mean that we flush all the
15234 * compression state into output such that if you uncompress the
15235 * compressed data you get back all the input data. Doing this may
15236 * make the final file larger due to padding though. Another example
15237 * is a regexp conversion, where if you at the end of the flushed data
15238 * have a match, but there is also a potential longer match. In the
15239 * non-flushed case we would ask for more input, but when flushing we
15240 * treat this as the end of input and do the match.
15242 * Flushing is not always possible (like if a charset converter flushes
15243 * at a partial multibyte sequence). Converters are supposed to try
15244 * to produce as much output as possible and then return an error
15245 * (typically %G_IO_ERROR_PARTIAL_INPUT).
15247 * Returns: a #GConverterResult, %G_CONVERTER_ERROR on error.
15253 * g_converter_input_stream_get_converter:
15254 * @converter_stream: a #GConverterInputStream
15256 * Gets the #GConverter that is used by @converter_stream.
15258 * Returns: (transfer none): the converter of the converter input stream
15264 * g_converter_input_stream_new:
15265 * @base_stream: a #GInputStream
15266 * @converter: a #GConverter
15268 * Creates a new converter input stream for the @base_stream.
15270 * Returns: a new #GInputStream.
15275 * g_converter_output_stream_get_converter:
15276 * @converter_stream: a #GConverterOutputStream
15278 * Gets the #GConverter that is used by @converter_stream.
15280 * Returns: (transfer none): the converter of the converter output stream
15286 * g_converter_output_stream_new:
15287 * @base_stream: a #GOutputStream
15288 * @converter: a #GConverter
15290 * Creates a new converter output stream for the @base_stream.
15292 * Returns: a new #GOutputStream.
15297 * g_converter_reset:
15298 * @converter: a #GConverter.
15300 * Resets all internal state in the converter, making it behave
15301 * as if it was just created. If the converter has any internal
15302 * state that would produce output then that output is lost.
15309 * g_credentials_get_native: (skip)
15310 * @credentials: A #GCredentials.
15311 * @native_type: The type of native credentials to get.
15313 * Gets a pointer to native credentials of type @native_type from
15316 * It is a programming error (which will cause an warning to be
15317 * logged) to use this method if there is no #GCredentials support for
15318 * the OS or if @native_type isn't supported by the OS.
15320 * Returns: The pointer to native credentials or %NULL if the
15321 * operation there is no #GCredentials support for the OS or if
15322 * @native_type isn't supported by the OS. Do not free the returned
15323 * data, it is owned by @credentials.
15329 * g_credentials_get_unix_pid:
15330 * @credentials: A #GCredentials
15331 * @error: Return location for error or %NULL.
15333 * Tries to get the UNIX process identifier from @credentials. This
15334 * method is only available on UNIX platforms.
15336 * This operation can fail if #GCredentials is not supported on the
15337 * OS or if the native credentials type does not contain information
15338 * about the UNIX process ID.
15340 * Returns: The UNIX process ID, or -1 if @error is set.
15346 * g_credentials_get_unix_user:
15347 * @credentials: A #GCredentials
15348 * @error: Return location for error or %NULL.
15350 * Tries to get the UNIX user identifier from @credentials. This
15351 * method is only available on UNIX platforms.
15353 * This operation can fail if #GCredentials is not supported on the
15354 * OS or if the native credentials type does not contain information
15355 * about the UNIX user.
15357 * Returns: The UNIX user identifier or -1 if @error is set.
15363 * g_credentials_is_same_user:
15364 * @credentials: A #GCredentials.
15365 * @other_credentials: A #GCredentials.
15366 * @error: Return location for error or %NULL.
15368 * Checks if @credentials and @other_credentials is the same user.
15370 * This operation can fail if #GCredentials is not supported on the
15373 * Returns: %TRUE if @credentials and @other_credentials has the same
15374 * user, %FALSE otherwise or if @error is set.
15380 * g_credentials_new:
15382 * Creates a new #GCredentials object with credentials matching the
15383 * the current process.
15385 * Returns: A #GCredentials. Free with g_object_unref().
15391 * g_credentials_set_native:
15392 * @credentials: A #GCredentials.
15393 * @native_type: The type of native credentials to set.
15394 * @native: (not nullable): A pointer to native credentials.
15396 * Copies the native credentials of type @native_type from @native
15397 * into @credentials.
15399 * It is a programming error (which will cause an warning to be
15400 * logged) to use this method if there is no #GCredentials support for
15401 * the OS or if @native_type isn't supported by the OS.
15408 * g_credentials_set_unix_user:
15409 * @credentials: A #GCredentials.
15410 * @uid: The UNIX user identifier to set.
15411 * @error: Return location for error or %NULL.
15413 * Tries to set the UNIX user identifier on @credentials. This method
15414 * is only available on UNIX platforms.
15416 * This operation can fail if #GCredentials is not supported on the
15417 * OS or if the native credentials type does not contain information
15418 * about the UNIX user. It can also fail if the OS does not allow the
15419 * use of "spoofed" credentials.
15421 * Returns: %TRUE if @uid was set, %FALSE if error is set.
15427 * g_credentials_to_string:
15428 * @credentials: A #GCredentials object.
15430 * Creates a human-readable textual representation of @credentials
15431 * that can be used in logging and debug messages. The format of the
15432 * returned string may change in future GLib release.
15434 * Returns: A string that should be freed with g_free().
15440 * g_data_input_stream_get_byte_order:
15441 * @stream: a given #GDataInputStream.
15443 * Gets the byte order for the data input stream.
15445 * Returns: the @stream's current #GDataStreamByteOrder.
15450 * g_data_input_stream_get_newline_type:
15451 * @stream: a given #GDataInputStream.
15453 * Gets the current newline type for the @stream.
15455 * Returns: #GDataStreamNewlineType for the given @stream.
15460 * g_data_input_stream_new:
15461 * @base_stream: a #GInputStream.
15463 * Creates a new data input stream for the @base_stream.
15465 * Returns: a new #GDataInputStream.
15470 * g_data_input_stream_read_byte:
15471 * @stream: a given #GDataInputStream.
15472 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
15473 * @error: #GError for error reporting.
15475 * Reads an unsigned 8-bit/1-byte value from @stream.
15477 * Returns: an unsigned 8-bit/1-byte value read from the @stream or %0
15478 * if an error occurred.
15483 * g_data_input_stream_read_int16:
15484 * @stream: a given #GDataInputStream.
15485 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
15486 * @error: #GError for error reporting.
15488 * Reads a 16-bit/2-byte value from @stream.
15490 * In order to get the correct byte order for this read operation,
15491 * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().
15493 * Returns: a signed 16-bit/2-byte value read from @stream or %0 if
15494 * an error occurred.
15499 * g_data_input_stream_read_int32:
15500 * @stream: a given #GDataInputStream.
15501 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
15502 * @error: #GError for error reporting.
15504 * Reads a signed 32-bit/4-byte value from @stream.
15506 * In order to get the correct byte order for this read operation,
15507 * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().
15509 * If @cancellable is not %NULL, then the operation can be cancelled by
15510 * triggering the cancellable object from another thread. If the operation
15511 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
15513 * Returns: a signed 32-bit/4-byte value read from the @stream or %0 if
15514 * an error occurred.
15519 * g_data_input_stream_read_int64:
15520 * @stream: a given #GDataInputStream.
15521 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
15522 * @error: #GError for error reporting.
15524 * Reads a 64-bit/8-byte value from @stream.
15526 * In order to get the correct byte order for this read operation,
15527 * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().
15529 * If @cancellable is not %NULL, then the operation can be cancelled by
15530 * triggering the cancellable object from another thread. If the operation
15531 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
15533 * Returns: a signed 64-bit/8-byte value read from @stream or %0 if
15534 * an error occurred.
15539 * g_data_input_stream_read_line:
15540 * @stream: a given #GDataInputStream.
15541 * @length: (out): a #gsize to get the length of the data read in.
15542 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
15543 * @error: #GError for error reporting.
15545 * Reads a line from the data input stream. Note that no encoding
15546 * checks or conversion is performed; the input is not guaranteed to
15547 * be UTF-8, and may in fact have embedded NUL characters.
15549 * If @cancellable is not %NULL, then the operation can be cancelled by
15550 * triggering the cancellable object from another thread. If the operation
15551 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
15553 * Returns: (nullable) (transfer full) (array zero-terminated=1) (element-type guint8):
15554 * a NUL terminated byte array with the line that was read in
15555 * (without the newlines). Set @length to a #gsize to get the length
15556 * of the read line. On an error, it will return %NULL and @error
15557 * will be set. If there's no content to read, it will still return
15558 * %NULL, but @error won't be set.
15563 * g_data_input_stream_read_line_async:
15564 * @stream: a given #GDataInputStream.
15565 * @io_priority: the [I/O priority][io-priority] of the request
15566 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
15567 * @callback: (scope async): callback to call when the request is satisfied.
15568 * @user_data: (closure): the data to pass to callback function.
15570 * The asynchronous version of g_data_input_stream_read_line(). It is
15571 * an error to have two outstanding calls to this function.
15573 * When the operation is finished, @callback will be called. You
15574 * can then call g_data_input_stream_read_line_finish() to get
15575 * the result of the operation.
15582 * g_data_input_stream_read_line_finish:
15583 * @stream: a given #GDataInputStream.
15584 * @result: the #GAsyncResult that was provided to the callback.
15585 * @length: (out): a #gsize to get the length of the data read in.
15586 * @error: #GError for error reporting.
15588 * Finish an asynchronous call started by
15589 * g_data_input_stream_read_line_async(). Note the warning about
15590 * string encoding in g_data_input_stream_read_line() applies here as
15593 * Returns: (nullable) (transfer full) (array zero-terminated=1) (element-type guint8):
15594 * a NUL-terminated byte array with the line that was read in
15595 * (without the newlines). Set @length to a #gsize to get the length
15596 * of the read line. On an error, it will return %NULL and @error
15597 * will be set. If there's no content to read, it will still return
15598 * %NULL, but @error won't be set.
15604 * g_data_input_stream_read_line_finish_utf8:
15605 * @stream: a given #GDataInputStream.
15606 * @result: the #GAsyncResult that was provided to the callback.
15607 * @length: (out): a #gsize to get the length of the data read in.
15608 * @error: #GError for error reporting.
15610 * Finish an asynchronous call started by
15611 * g_data_input_stream_read_line_async().
15613 * Returns: (nullable) (transfer full): a string with the line that
15614 * was read in (without the newlines). Set @length to a #gsize to
15615 * get the length of the read line. On an error, it will return
15616 * %NULL and @error will be set. For UTF-8 conversion errors, the set
15617 * error domain is %G_CONVERT_ERROR. If there's no content to read,
15618 * it will still return %NULL, but @error won't be set.
15624 * g_data_input_stream_read_line_utf8:
15625 * @stream: a given #GDataInputStream.
15626 * @length: (out): a #gsize to get the length of the data read in.
15627 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
15628 * @error: #GError for error reporting.
15630 * Reads a UTF-8 encoded line from the data input stream.
15632 * If @cancellable is not %NULL, then the operation can be cancelled by
15633 * triggering the cancellable object from another thread. If the operation
15634 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
15636 * Returns: (nullable) (transfer full): a NUL terminated UTF-8 string
15637 * with the line that was read in (without the newlines). Set
15638 * @length to a #gsize to get the length of the read line. On an
15639 * error, it will return %NULL and @error will be set. For UTF-8
15640 * conversion errors, the set error domain is %G_CONVERT_ERROR. If
15641 * there's no content to read, it will still return %NULL, but @error
15648 * g_data_input_stream_read_uint16:
15649 * @stream: a given #GDataInputStream.
15650 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
15651 * @error: #GError for error reporting.
15653 * Reads an unsigned 16-bit/2-byte value from @stream.
15655 * In order to get the correct byte order for this read operation,
15656 * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().
15658 * Returns: an unsigned 16-bit/2-byte value read from the @stream or %0 if
15659 * an error occurred.
15664 * g_data_input_stream_read_uint32:
15665 * @stream: a given #GDataInputStream.
15666 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
15667 * @error: #GError for error reporting.
15669 * Reads an unsigned 32-bit/4-byte value from @stream.
15671 * In order to get the correct byte order for this read operation,
15672 * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().
15674 * If @cancellable is not %NULL, then the operation can be cancelled by
15675 * triggering the cancellable object from another thread. If the operation
15676 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
15678 * Returns: an unsigned 32-bit/4-byte value read from the @stream or %0 if
15679 * an error occurred.
15684 * g_data_input_stream_read_uint64:
15685 * @stream: a given #GDataInputStream.
15686 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
15687 * @error: #GError for error reporting.
15689 * Reads an unsigned 64-bit/8-byte value from @stream.
15691 * In order to get the correct byte order for this read operation,
15692 * see g_data_input_stream_get_byte_order().
15694 * If @cancellable is not %NULL, then the operation can be cancelled by
15695 * triggering the cancellable object from another thread. If the operation
15696 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
15698 * Returns: an unsigned 64-bit/8-byte read from @stream or %0 if
15699 * an error occurred.
15704 * g_data_input_stream_read_until:
15705 * @stream: a given #GDataInputStream.
15706 * @stop_chars: characters to terminate the read.
15707 * @length: (out): a #gsize to get the length of the data read in.
15708 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
15709 * @error: #GError for error reporting.
15711 * Reads a string from the data input stream, up to the first
15712 * occurrence of any of the stop characters.
15714 * Note that, in contrast to g_data_input_stream_read_until_async(),
15715 * this function consumes the stop character that it finds.
15717 * Don't use this function in new code. Its functionality is
15718 * inconsistent with g_data_input_stream_read_until_async(). Both
15719 * functions will be marked as deprecated in a future release. Use
15720 * g_data_input_stream_read_upto() instead, but note that that function
15721 * does not consume the stop character.
15723 * Returns: (transfer full): a string with the data that was read
15724 * before encountering any of the stop characters. Set @length to
15725 * a #gsize to get the length of the string. This function will
15726 * return %NULL on an error.
15731 * g_data_input_stream_read_until_async:
15732 * @stream: a given #GDataInputStream.
15733 * @stop_chars: characters to terminate the read.
15734 * @io_priority: the [I/O priority][io-priority] of the request
15735 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
15736 * @callback: (scope async): callback to call when the request is satisfied.
15737 * @user_data: (closure): the data to pass to callback function.
15739 * The asynchronous version of g_data_input_stream_read_until().
15740 * It is an error to have two outstanding calls to this function.
15742 * Note that, in contrast to g_data_input_stream_read_until(),
15743 * this function does not consume the stop character that it finds. You
15744 * must read it for yourself.
15746 * When the operation is finished, @callback will be called. You
15747 * can then call g_data_input_stream_read_until_finish() to get
15748 * the result of the operation.
15750 * Don't use this function in new code. Its functionality is
15751 * inconsistent with g_data_input_stream_read_until(). Both functions
15752 * will be marked as deprecated in a future release. Use
15753 * g_data_input_stream_read_upto_async() instead.
15760 * g_data_input_stream_read_until_finish:
15761 * @stream: a given #GDataInputStream.
15762 * @result: the #GAsyncResult that was provided to the callback.
15763 * @length: (out): a #gsize to get the length of the data read in.
15764 * @error: #GError for error reporting.
15766 * Finish an asynchronous call started by
15767 * g_data_input_stream_read_until_async().
15770 * Returns: (transfer full): a string with the data that was read
15771 * before encountering any of the stop characters. Set @length to
15772 * a #gsize to get the length of the string. This function will
15773 * return %NULL on an error.
15778 * g_data_input_stream_read_upto:
15779 * @stream: a #GDataInputStream
15780 * @stop_chars: characters to terminate the read
15781 * @stop_chars_len: length of @stop_chars. May be -1 if @stop_chars is
15783 * @length: (out): a #gsize to get the length of the data read in
15784 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
15785 * @error: #GError for error reporting
15787 * Reads a string from the data input stream, up to the first
15788 * occurrence of any of the stop characters.
15790 * In contrast to g_data_input_stream_read_until(), this function
15791 * does not consume the stop character. You have to use
15792 * g_data_input_stream_read_byte() to get it before calling
15793 * g_data_input_stream_read_upto() again.
15795 * Note that @stop_chars may contain '\0' if @stop_chars_len is
15798 * Returns: (transfer full): a string with the data that was read
15799 * before encountering any of the stop characters. Set @length to
15800 * a #gsize to get the length of the string. This function will
15801 * return %NULL on an error
15807 * g_data_input_stream_read_upto_async:
15808 * @stream: a #GDataInputStream
15809 * @stop_chars: characters to terminate the read
15810 * @stop_chars_len: length of @stop_chars. May be -1 if @stop_chars is
15812 * @io_priority: the [I/O priority][io-priority] of the request
15813 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
15814 * @callback: (scope async): callback to call when the request is satisfied
15815 * @user_data: (closure): the data to pass to callback function
15817 * The asynchronous version of g_data_input_stream_read_upto().
15818 * It is an error to have two outstanding calls to this function.
15820 * In contrast to g_data_input_stream_read_until(), this function
15821 * does not consume the stop character. You have to use
15822 * g_data_input_stream_read_byte() to get it before calling
15823 * g_data_input_stream_read_upto() again.
15825 * Note that @stop_chars may contain '\0' if @stop_chars_len is
15828 * When the operation is finished, @callback will be called. You
15829 * can then call g_data_input_stream_read_upto_finish() to get
15830 * the result of the operation.
15837 * g_data_input_stream_read_upto_finish:
15838 * @stream: a #GDataInputStream
15839 * @result: the #GAsyncResult that was provided to the callback
15840 * @length: (out): a #gsize to get the length of the data read in
15841 * @error: #GError for error reporting
15843 * Finish an asynchronous call started by
15844 * g_data_input_stream_read_upto_async().
15846 * Note that this function does not consume the stop character. You
15847 * have to use g_data_input_stream_read_byte() to get it before calling
15848 * g_data_input_stream_read_upto_async() again.
15850 * Returns: (transfer full): a string with the data that was read
15851 * before encountering any of the stop characters. Set @length to
15852 * a #gsize to get the length of the string. This function will
15853 * return %NULL on an error.
15859 * g_data_input_stream_set_byte_order:
15860 * @stream: a given #GDataInputStream.
15861 * @order: a #GDataStreamByteOrder to set.
15863 * This function sets the byte order for the given @stream. All subsequent
15864 * reads from the @stream will be read in the given @order.
15869 * g_data_input_stream_set_newline_type:
15870 * @stream: a #GDataInputStream.
15871 * @type: the type of new line return as #GDataStreamNewlineType.
15873 * Sets the newline type for the @stream.
15875 * Note that using G_DATA_STREAM_NEWLINE_TYPE_ANY is slightly unsafe. If a read
15876 * chunk ends in "CR" we must read an additional byte to know if this is "CR" or
15877 * "CR LF", and this might block if there is no more data available.
15882 * g_data_output_stream_get_byte_order:
15883 * @stream: a #GDataOutputStream.
15885 * Gets the byte order for the stream.
15887 * Returns: the #GDataStreamByteOrder for the @stream.
15892 * g_data_output_stream_new:
15893 * @base_stream: a #GOutputStream.
15895 * Creates a new data output stream for @base_stream.
15897 * Returns: #GDataOutputStream.
15902 * g_data_output_stream_put_byte:
15903 * @stream: a #GDataOutputStream.
15904 * @data: a #guchar.
15905 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
15906 * @error: a #GError, %NULL to ignore.
15908 * Puts a byte into the output stream.
15910 * Returns: %TRUE if @data was successfully added to the @stream.
15915 * g_data_output_stream_put_int16:
15916 * @stream: a #GDataOutputStream.
15917 * @data: a #gint16.
15918 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
15919 * @error: a #GError, %NULL to ignore.
15921 * Puts a signed 16-bit integer into the output stream.
15923 * Returns: %TRUE if @data was successfully added to the @stream.
15928 * g_data_output_stream_put_int32:
15929 * @stream: a #GDataOutputStream.
15930 * @data: a #gint32.
15931 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
15932 * @error: a #GError, %NULL to ignore.
15934 * Puts a signed 32-bit integer into the output stream.
15936 * Returns: %TRUE if @data was successfully added to the @stream.
15941 * g_data_output_stream_put_int64:
15942 * @stream: a #GDataOutputStream.
15943 * @data: a #gint64.
15944 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
15945 * @error: a #GError, %NULL to ignore.
15947 * Puts a signed 64-bit integer into the stream.
15949 * Returns: %TRUE if @data was successfully added to the @stream.
15954 * g_data_output_stream_put_string:
15955 * @stream: a #GDataOutputStream.
15957 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
15958 * @error: a #GError, %NULL to ignore.
15960 * Puts a string into the output stream.
15962 * Returns: %TRUE if @string was successfully added to the @stream.
15967 * g_data_output_stream_put_uint16:
15968 * @stream: a #GDataOutputStream.
15969 * @data: a #guint16.
15970 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
15971 * @error: a #GError, %NULL to ignore.
15973 * Puts an unsigned 16-bit integer into the output stream.
15975 * Returns: %TRUE if @data was successfully added to the @stream.
15980 * g_data_output_stream_put_uint32:
15981 * @stream: a #GDataOutputStream.
15982 * @data: a #guint32.
15983 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
15984 * @error: a #GError, %NULL to ignore.
15986 * Puts an unsigned 32-bit integer into the stream.
15988 * Returns: %TRUE if @data was successfully added to the @stream.
15993 * g_data_output_stream_put_uint64:
15994 * @stream: a #GDataOutputStream.
15995 * @data: a #guint64.
15996 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
15997 * @error: a #GError, %NULL to ignore.
15999 * Puts an unsigned 64-bit integer into the stream.
16001 * Returns: %TRUE if @data was successfully added to the @stream.
16006 * g_data_output_stream_set_byte_order:
16007 * @stream: a #GDataOutputStream.
16008 * @order: a %GDataStreamByteOrder.
16010 * Sets the byte order of the data output stream to @order.
16015 * g_datagram_based_condition_check:
16016 * @datagram_based: a #GDatagramBased
16017 * @condition: a #GIOCondition mask to check
16019 * Checks on the readiness of @datagram_based to perform operations. The
16020 * operations specified in @condition are checked for and masked against the
16021 * currently-satisfied conditions on @datagram_based. The result is returned.
16023 * %G_IO_IN will be set in the return value if data is available to read with
16024 * g_datagram_based_receive_messages(), or if the connection is closed remotely
16025 * (EOS); and if the datagram_based has not been closed locally using some
16026 * implementation-specific method (such as g_socket_close() or
16027 * g_socket_shutdown() with @shutdown_read set, if it’s a #GSocket).
16029 * If the connection is shut down or closed (by calling g_socket_close() or
16030 * g_socket_shutdown() with @shutdown_read set, if it’s a #GSocket, for
16031 * example), all calls to this function will return %G_IO_ERROR_CLOSED.
16033 * %G_IO_OUT will be set if it is expected that at least one byte can be sent
16034 * using g_datagram_based_send_messages() without blocking. It will not be set
16035 * if the datagram_based has been closed locally.
16037 * %G_IO_HUP will be set if the connection has been closed locally.
16039 * %G_IO_ERR will be set if there was an asynchronous error in transmitting data
16040 * previously enqueued using g_datagram_based_send_messages().
16042 * Note that on Windows, it is possible for an operation to return
16043 * %G_IO_ERROR_WOULD_BLOCK even immediately after
16044 * g_datagram_based_condition_check() has claimed that the #GDatagramBased is
16045 * ready for writing. Rather than calling g_datagram_based_condition_check() and
16046 * then writing to the #GDatagramBased if it succeeds, it is generally better to
16047 * simply try writing right away, and try again later if the initial attempt
16048 * returns %G_IO_ERROR_WOULD_BLOCK.
16050 * It is meaningless to specify %G_IO_ERR or %G_IO_HUP in @condition; these
16051 * conditions will always be set in the output if they are true. Apart from
16052 * these flags, the output is guaranteed to be masked by @condition.
16054 * This call never blocks.
16056 * Returns: the #GIOCondition mask of the current state
16062 * g_datagram_based_condition_wait:
16063 * @datagram_based: a #GDatagramBased
16064 * @condition: a #GIOCondition mask to wait for
16065 * @timeout: the maximum time (in microseconds) to wait, 0 to not block, or -1
16066 * to block indefinitely
16067 * @cancellable: (nullable): a #GCancellable
16068 * @error: return location for a #GError
16070 * Waits for up to @timeout microseconds for condition to become true on
16071 * @datagram_based. If the condition is met, %TRUE is returned.
16073 * If @cancellable is cancelled before the condition is met, or if @timeout is
16074 * reached before the condition is met, then %FALSE is returned and @error is
16075 * set appropriately (%G_IO_ERROR_CANCELLED or %G_IO_ERROR_TIMED_OUT).
16077 * Returns: %TRUE if the condition was met, %FALSE otherwise
16083 * g_datagram_based_create_source:
16084 * @datagram_based: a #GDatagramBased
16085 * @condition: a #GIOCondition mask to monitor
16086 * @cancellable: (nullable): a #GCancellable
16088 * Creates a #GSource that can be attached to a #GMainContext to monitor for
16089 * the availability of the specified @condition on the #GDatagramBased. The
16090 * #GSource keeps a reference to the @datagram_based.
16092 * The callback on the source is of the #GDatagramBasedSourceFunc type.
16094 * It is meaningless to specify %G_IO_ERR or %G_IO_HUP in @condition; these
16095 * conditions will always be reported in the callback if they are true.
16097 * If non-%NULL, @cancellable can be used to cancel the source, which will
16098 * cause the source to trigger, reporting the current condition (which is
16099 * likely 0 unless cancellation happened at the same time as a condition
16100 * change). You can check for this in the callback using
16101 * g_cancellable_is_cancelled().
16103 * Returns: (transfer full): a newly allocated #GSource
16109 * g_datagram_based_receive_messages:
16110 * @datagram_based: a #GDatagramBased
16111 * @messages: (array length=num_messages): an array of #GInputMessage structs
16112 * @num_messages: the number of elements in @messages
16113 * @flags: an int containing #GSocketMsgFlags flags for the overall operation
16114 * @timeout: the maximum time (in microseconds) to wait, 0 to not block, or -1
16115 * to block indefinitely
16116 * @cancellable: (allow-none): a %GCancellable
16117 * @error: return location for a #GError
16119 * Receive one or more data messages from @datagram_based in one go.
16121 * @messages must point to an array of #GInputMessage structs and
16122 * @num_messages must be the length of this array. Each #GInputMessage
16123 * contains a pointer to an array of #GInputVector structs describing the
16124 * buffers that the data received in each message will be written to.
16126 * @flags modify how all messages are received. The commonly available
16127 * arguments for this are available in the #GSocketMsgFlags enum, but the
16128 * values there are the same as the system values, and the flags
16129 * are passed in as-is, so you can pass in system-specific flags too. These
16130 * flags affect the overall receive operation. Flags affecting individual
16131 * messages are returned in #GInputMessage.flags.
16133 * The other members of #GInputMessage are treated as described in its
16136 * If @timeout is negative the call will block until @num_messages have been
16137 * received, the connection is closed remotely (EOS), @cancellable is cancelled,
16138 * or an error occurs.
16140 * If @timeout is 0 the call will return up to @num_messages without blocking,
16141 * or %G_IO_ERROR_WOULD_BLOCK if no messages are queued in the operating system
16144 * If @timeout is positive the call will block on the same conditions as if
16145 * @timeout were negative. If the timeout is reached
16146 * before any messages are received, %G_IO_ERROR_TIMED_OUT is returned,
16147 * otherwise it will return the number of messages received before timing out.
16148 * (Note: This is effectively the behaviour of `MSG_WAITFORONE` with
16151 * To be notified when messages are available, wait for the %G_IO_IN condition.
16152 * Note though that you may still receive %G_IO_ERROR_WOULD_BLOCK from
16153 * g_datagram_based_receive_messages() even if you were previously notified of a
16154 * %G_IO_IN condition.
16156 * If the remote peer closes the connection, any messages queued in the
16157 * underlying receive buffer will be returned, and subsequent calls to
16158 * g_datagram_based_receive_messages() will return 0 (with no error set).
16160 * If the connection is shut down or closed (by calling g_socket_close() or
16161 * g_socket_shutdown() with @shutdown_read set, if it’s a #GSocket, for
16162 * example), all calls to this function will return %G_IO_ERROR_CLOSED.
16164 * On error -1 is returned and @error is set accordingly. An error will only
16165 * be returned if zero messages could be received; otherwise the number of
16166 * messages successfully received before the error will be returned. If
16167 * @cancellable is cancelled, %G_IO_ERROR_CANCELLED is returned as with any
16170 * Returns: number of messages received, or -1 on error. Note that the number
16171 * of messages received may be smaller than @num_messages if @timeout is
16172 * zero or positive, if the peer closed the connection, or if @num_messages
16173 * was larger than `UIO_MAXIOV` (1024), in which case the caller may re-try
16174 * to receive the remaining messages.
16180 * g_datagram_based_send_messages:
16181 * @datagram_based: a #GDatagramBased
16182 * @messages: (array length=num_messages): an array of #GOutputMessage structs
16183 * @num_messages: the number of elements in @messages
16184 * @flags: an int containing #GSocketMsgFlags flags
16185 * @timeout: the maximum time (in microseconds) to wait, 0 to not block, or -1
16186 * to block indefinitely
16187 * @cancellable: (nullable): a %GCancellable
16188 * @error: return location for a #GError
16190 * Send one or more data messages from @datagram_based in one go.
16192 * @messages must point to an array of #GOutputMessage structs and
16193 * @num_messages must be the length of this array. Each #GOutputMessage
16194 * contains an address to send the data to, and a pointer to an array of
16195 * #GOutputVector structs to describe the buffers that the data to be sent
16196 * for each message will be gathered from.
16198 * @flags modify how the message is sent. The commonly available arguments
16199 * for this are available in the #GSocketMsgFlags enum, but the
16200 * values there are the same as the system values, and the flags
16201 * are passed in as-is, so you can pass in system-specific flags too.
16203 * The other members of #GOutputMessage are treated as described in its
16206 * If @timeout is negative the call will block until @num_messages have been
16207 * sent, @cancellable is cancelled, or an error occurs.
16209 * If @timeout is 0 the call will send up to @num_messages without blocking,
16210 * or will return %G_IO_ERROR_WOULD_BLOCK if there is no space to send messages.
16212 * If @timeout is positive the call will block on the same conditions as if
16213 * @timeout were negative. If the timeout is reached before any messages are
16214 * sent, %G_IO_ERROR_TIMED_OUT is returned, otherwise it will return the number
16215 * of messages sent before timing out.
16217 * To be notified when messages can be sent, wait for the %G_IO_OUT condition.
16218 * Note though that you may still receive %G_IO_ERROR_WOULD_BLOCK from
16219 * g_datagram_based_send_messages() even if you were previously notified of a
16220 * %G_IO_OUT condition. (On Windows in particular, this is very common due to
16221 * the way the underlying APIs work.)
16223 * If the connection is shut down or closed (by calling g_socket_close() or
16224 * g_socket_shutdown() with @shutdown_write set, if it’s a #GSocket, for
16225 * example), all calls to this function will return %G_IO_ERROR_CLOSED.
16227 * On error -1 is returned and @error is set accordingly. An error will only
16228 * be returned if zero messages could be sent; otherwise the number of messages
16229 * successfully sent before the error will be returned. If @cancellable is
16230 * cancelled, %G_IO_ERROR_CANCELLED is returned as with any other error.
16232 * Returns: number of messages sent, or -1 on error. Note that the number of
16233 * messages sent may be smaller than @num_messages if @timeout is zero
16234 * or positive, or if @num_messages was larger than `UIO_MAXIOV` (1024), in
16235 * which case the caller may re-try to send the remaining messages.
16241 * g_dbus_action_group_get:
16242 * @connection: A #GDBusConnection
16243 * @bus_name: the bus name which exports the action group
16244 * @object_path: the object path at which the action group is exported
16246 * Obtains a #GDBusActionGroup for the action group which is exported at
16247 * the given @bus_name and @object_path.
16249 * The thread default main context is taken at the time of this call.
16250 * All signals on the menu model (and any linked models) are reported
16251 * with respect to this context. All calls on the returned menu model
16252 * (and linked models) must also originate from this same context, with
16253 * the thread default main context unchanged.
16255 * This call is non-blocking. The returned action group may or may not
16256 * already be filled in. The correct thing to do is connect the signals
16257 * for the action group to monitor for changes and then to call
16258 * g_action_group_list_actions() to get the initial list.
16260 * Returns: (transfer full): a #GDBusActionGroup
16266 * g_dbus_address_escape_value:
16267 * @string: an unescaped string to be included in a D-Bus address
16268 * as the value in a key-value pair
16270 * Escape @string so it can appear in a D-Bus address as the value
16271 * part of a key-value pair.
16273 * For instance, if @string is "/run/bus-for-:0",
16274 * this function would return "/run/bus-for-%3A0",
16275 * which could be used in a D-Bus address like
16276 * "unix:nonce-tcp:host=127.0.0.1,port=42,noncefile=/run/bus-for-%3A0".
16278 * Returns: (transfer full): a copy of @string with all
16279 * non-optionally-escaped bytes escaped
16285 * g_dbus_address_get_for_bus_sync:
16286 * @bus_type: a #GBusType
16287 * @cancellable: (allow-none): a #GCancellable or %NULL
16288 * @error: return location for error or %NULL
16290 * Synchronously looks up the D-Bus address for the well-known message
16291 * bus instance specified by @bus_type. This may involve using various
16292 * platform specific mechanisms.
16294 * Returns: a valid D-Bus address string for @bus_type or %NULL if
16301 * g_dbus_address_get_stream:
16302 * @address: A valid D-Bus address.
16303 * @cancellable: (allow-none): A #GCancellable or %NULL.
16304 * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
16305 * @user_data: Data to pass to @callback.
16307 * Asynchronously connects to an endpoint specified by @address and
16308 * sets up the connection so it is in a state to run the client-side
16309 * of the D-Bus authentication conversation.
16311 * When the operation is finished, @callback will be invoked. You can
16312 * then call g_dbus_address_get_stream_finish() to get the result of
16315 * This is an asynchronous failable function. See
16316 * g_dbus_address_get_stream_sync() for the synchronous version.
16323 * g_dbus_address_get_stream_finish:
16324 * @res: A #GAsyncResult obtained from the GAsyncReadyCallback passed to g_dbus_address_get_stream().
16325 * @out_guid: (optional) (out): %NULL or return location to store the GUID extracted from @address, if any.
16326 * @error: Return location for error or %NULL.
16328 * Finishes an operation started with g_dbus_address_get_stream().
16330 * Returns: (transfer full): A #GIOStream or %NULL if @error is set.
16336 * g_dbus_address_get_stream_sync:
16337 * @address: A valid D-Bus address.
16338 * @out_guid: (optional) (out): %NULL or return location to store the GUID extracted from @address, if any.
16339 * @cancellable: (allow-none): A #GCancellable or %NULL.
16340 * @error: Return location for error or %NULL.
16342 * Synchronously connects to an endpoint specified by @address and
16343 * sets up the connection so it is in a state to run the client-side
16344 * of the D-Bus authentication conversation.
16346 * This is a synchronous failable function. See
16347 * g_dbus_address_get_stream() for the asynchronous version.
16349 * Returns: (transfer full): A #GIOStream or %NULL if @error is set.
16355 * g_dbus_annotation_info_lookup:
16356 * @annotations: (array zero-terminated=1) (allow-none): A %NULL-terminated array of annotations or %NULL.
16357 * @name: The name of the annotation to look up.
16359 * Looks up the value of an annotation.
16361 * The cost of this function is O(n) in number of annotations.
16363 * Returns: The value or %NULL if not found. Do not free, it is owned by @annotations.
16369 * g_dbus_annotation_info_ref:
16370 * @info: A #GDBusNodeInfo
16372 * If @info is statically allocated does nothing. Otherwise increases
16373 * the reference count.
16375 * Returns: The same @info.
16381 * g_dbus_annotation_info_unref:
16382 * @info: A #GDBusAnnotationInfo.
16384 * If @info is statically allocated, does nothing. Otherwise decreases
16385 * the reference count of @info. When its reference count drops to 0,
16386 * the memory used is freed.
16393 * g_dbus_arg_info_ref:
16394 * @info: A #GDBusArgInfo
16396 * If @info is statically allocated does nothing. Otherwise increases
16397 * the reference count.
16399 * Returns: The same @info.
16405 * g_dbus_arg_info_unref:
16406 * @info: A #GDBusArgInfo.
16408 * If @info is statically allocated, does nothing. Otherwise decreases
16409 * the reference count of @info. When its reference count drops to 0,
16410 * the memory used is freed.
16417 * g_dbus_auth_observer_allow_mechanism:
16418 * @observer: A #GDBusAuthObserver.
16419 * @mechanism: The name of the mechanism, e.g. `DBUS_COOKIE_SHA1`.
16421 * Emits the #GDBusAuthObserver::allow-mechanism signal on @observer.
16423 * Returns: %TRUE if @mechanism can be used to authenticate the other peer, %FALSE if not.
16429 * g_dbus_auth_observer_authorize_authenticated_peer:
16430 * @observer: A #GDBusAuthObserver.
16431 * @stream: A #GIOStream for the #GDBusConnection.
16432 * @credentials: (allow-none): Credentials received from the peer or %NULL.
16434 * Emits the #GDBusAuthObserver::authorize-authenticated-peer signal on @observer.
16436 * Returns: %TRUE if the peer is authorized, %FALSE if not.
16442 * g_dbus_auth_observer_new:
16444 * Creates a new #GDBusAuthObserver object.
16446 * Returns: A #GDBusAuthObserver. Free with g_object_unref().
16452 * g_dbus_connection_add_filter:
16453 * @connection: a #GDBusConnection
16454 * @filter_function: a filter function
16455 * @user_data: user data to pass to @filter_function
16456 * @user_data_free_func: function to free @user_data with when filter
16457 * is removed or %NULL
16459 * Adds a message filter. Filters are handlers that are run on all
16460 * incoming and outgoing messages, prior to standard dispatch. Filters
16461 * are run in the order that they were added. The same handler can be
16462 * added as a filter more than once, in which case it will be run more
16463 * than once. Filters added during a filter callback won't be run on
16464 * the message being processed. Filter functions are allowed to modify
16465 * and even drop messages.
16467 * Note that filters are run in a dedicated message handling thread so
16468 * they can't block and, generally, can't do anything but signal a
16469 * worker thread. Also note that filters are rarely needed - use API
16470 * such as g_dbus_connection_send_message_with_reply(),
16471 * g_dbus_connection_signal_subscribe() or g_dbus_connection_call() instead.
16473 * If a filter consumes an incoming message the message is not
16474 * dispatched anywhere else - not even the standard dispatch machinery
16475 * (that API such as g_dbus_connection_signal_subscribe() and
16476 * g_dbus_connection_send_message_with_reply() relies on) will see the
16477 * message. Similary, if a filter consumes an outgoing message, the
16478 * message will not be sent to the other peer.
16480 * If @user_data_free_func is non-%NULL, it will be called (in the
16481 * thread-default main context of the thread you are calling this
16482 * method from) at some point after @user_data is no longer
16483 * needed. (It is not guaranteed to be called synchronously when the
16484 * filter is removed, and may be called after @connection has been
16487 * Returns: a filter identifier that can be used with
16488 * g_dbus_connection_remove_filter()
16494 * g_dbus_connection_call:
16495 * @connection: a #GDBusConnection
16496 * @bus_name: (allow-none): a unique or well-known bus name or %NULL if
16497 * @connection is not a message bus connection
16498 * @object_path: path of remote object
16499 * @interface_name: D-Bus interface to invoke method on
16500 * @method_name: the name of the method to invoke
16501 * @parameters: (allow-none): a #GVariant tuple with parameters for the method
16502 * or %NULL if not passing parameters
16503 * @reply_type: (allow-none): the expected type of the reply, or %NULL
16504 * @flags: flags from the #GDBusCallFlags enumeration
16505 * @timeout_msec: the timeout in milliseconds, -1 to use the default
16506 * timeout or %G_MAXINT for no timeout
16507 * @cancellable: (allow-none): a #GCancellable or %NULL
16508 * @callback: (allow-none): a #GAsyncReadyCallback to call when the request
16509 * is satisfied or %NULL if you don't care about the result of the
16510 * method invocation
16511 * @user_data: the data to pass to @callback
16513 * Asynchronously invokes the @method_name method on the
16514 * @interface_name D-Bus interface on the remote object at
16515 * @object_path owned by @bus_name.
16517 * If @connection is closed then the operation will fail with
16518 * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will
16519 * fail with %G_IO_ERROR_CANCELLED. If @parameters contains a value
16520 * not compatible with the D-Bus protocol, the operation fails with
16521 * %G_IO_ERROR_INVALID_ARGUMENT.
16523 * If @reply_type is non-%NULL then the reply will be checked for having this type and an
16524 * error will be raised if it does not match. Said another way, if you give a @reply_type
16525 * then any non-%NULL return value will be of this type.
16527 * If the @parameters #GVariant is floating, it is consumed. This allows
16528 * convenient 'inline' use of g_variant_new(), e.g.:
16529 * |[<!-- language="C" -->
16530 * g_dbus_connection_call (connection,
16531 * "org.freedesktop.StringThings",
16532 * "/org/freedesktop/StringThings",
16533 * "org.freedesktop.StringThings",
16535 * g_variant_new ("(ss)",
16539 * G_DBUS_CALL_FLAGS_NONE,
16542 * (GAsyncReadyCallback) two_strings_done,
16546 * This is an asynchronous method. When the operation is finished,
16547 * @callback will be invoked in the
16548 * [thread-default main context][g-main-context-push-thread-default]
16549 * of the thread you are calling this method from. You can then call
16550 * g_dbus_connection_call_finish() to get the result of the operation.
16551 * See g_dbus_connection_call_sync() for the synchronous version of this
16554 * If @callback is %NULL then the D-Bus method call message will be sent with
16555 * the %G_DBUS_MESSAGE_FLAGS_NO_REPLY_EXPECTED flag set.
16562 * g_dbus_connection_call_finish:
16563 * @connection: a #GDBusConnection
16564 * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_call()
16565 * @error: return location for error or %NULL
16567 * Finishes an operation started with g_dbus_connection_call().
16569 * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
16570 * return values. Free with g_variant_unref().
16576 * g_dbus_connection_call_sync:
16577 * @connection: a #GDBusConnection
16578 * @bus_name: (allow-none): a unique or well-known bus name or %NULL if
16579 * @connection is not a message bus connection
16580 * @object_path: path of remote object
16581 * @interface_name: D-Bus interface to invoke method on
16582 * @method_name: the name of the method to invoke
16583 * @parameters: (allow-none): a #GVariant tuple with parameters for the method
16584 * or %NULL if not passing parameters
16585 * @reply_type: (allow-none): the expected type of the reply, or %NULL
16586 * @flags: flags from the #GDBusCallFlags enumeration
16587 * @timeout_msec: the timeout in milliseconds, -1 to use the default
16588 * timeout or %G_MAXINT for no timeout
16589 * @cancellable: (allow-none): a #GCancellable or %NULL
16590 * @error: return location for error or %NULL
16592 * Synchronously invokes the @method_name method on the
16593 * @interface_name D-Bus interface on the remote object at
16594 * @object_path owned by @bus_name.
16596 * If @connection is closed then the operation will fail with
16597 * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the
16598 * operation will fail with %G_IO_ERROR_CANCELLED. If @parameters
16599 * contains a value not compatible with the D-Bus protocol, the operation
16600 * fails with %G_IO_ERROR_INVALID_ARGUMENT.
16602 * If @reply_type is non-%NULL then the reply will be checked for having
16603 * this type and an error will be raised if it does not match. Said
16604 * another way, if you give a @reply_type then any non-%NULL return
16605 * value will be of this type.
16607 * If the @parameters #GVariant is floating, it is consumed.
16608 * This allows convenient 'inline' use of g_variant_new(), e.g.:
16609 * |[<!-- language="C" -->
16610 * g_dbus_connection_call_sync (connection,
16611 * "org.freedesktop.StringThings",
16612 * "/org/freedesktop/StringThings",
16613 * "org.freedesktop.StringThings",
16615 * g_variant_new ("(ss)",
16619 * G_DBUS_CALL_FLAGS_NONE,
16625 * The calling thread is blocked until a reply is received. See
16626 * g_dbus_connection_call() for the asynchronous version of
16629 * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
16630 * return values. Free with g_variant_unref().
16636 * g_dbus_connection_call_with_unix_fd_list:
16637 * @connection: a #GDBusConnection
16638 * @bus_name: (allow-none): a unique or well-known bus name or %NULL if
16639 * @connection is not a message bus connection
16640 * @object_path: path of remote object
16641 * @interface_name: D-Bus interface to invoke method on
16642 * @method_name: the name of the method to invoke
16643 * @parameters: (allow-none): a #GVariant tuple with parameters for the method
16644 * or %NULL if not passing parameters
16645 * @reply_type: (allow-none): the expected type of the reply, or %NULL
16646 * @flags: flags from the #GDBusCallFlags enumeration
16647 * @timeout_msec: the timeout in milliseconds, -1 to use the default
16648 * timeout or %G_MAXINT for no timeout
16649 * @fd_list: (allow-none): a #GUnixFDList or %NULL
16650 * @cancellable: (allow-none): a #GCancellable or %NULL
16651 * @callback: (allow-none): a #GAsyncReadyCallback to call when the request is
16652 * satisfied or %NULL if you don't * care about the result of the
16653 * method invocation
16654 * @user_data: The data to pass to @callback.
16656 * Like g_dbus_connection_call() but also takes a #GUnixFDList object.
16658 * This method is only available on UNIX.
16665 * g_dbus_connection_call_with_unix_fd_list_finish:
16666 * @connection: a #GDBusConnection
16667 * @out_fd_list: (out) (allow-none): return location for a #GUnixFDList or %NULL
16668 * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed to
16669 * g_dbus_connection_call_with_unix_fd_list()
16670 * @error: return location for error or %NULL
16672 * Finishes an operation started with g_dbus_connection_call_with_unix_fd_list().
16674 * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
16675 * return values. Free with g_variant_unref().
16681 * g_dbus_connection_call_with_unix_fd_list_sync:
16682 * @connection: a #GDBusConnection
16683 * @bus_name: (allow-none): a unique or well-known bus name or %NULL
16684 * if @connection is not a message bus connection
16685 * @object_path: path of remote object
16686 * @interface_name: D-Bus interface to invoke method on
16687 * @method_name: the name of the method to invoke
16688 * @parameters: (allow-none): a #GVariant tuple with parameters for
16689 * the method or %NULL if not passing parameters
16690 * @reply_type: (allow-none): the expected type of the reply, or %NULL
16691 * @flags: flags from the #GDBusCallFlags enumeration
16692 * @timeout_msec: the timeout in milliseconds, -1 to use the default
16693 * timeout or %G_MAXINT for no timeout
16694 * @fd_list: (allow-none): a #GUnixFDList or %NULL
16695 * @out_fd_list: (out) (allow-none): return location for a #GUnixFDList or %NULL
16696 * @cancellable: (allow-none): a #GCancellable or %NULL
16697 * @error: return location for error or %NULL
16699 * Like g_dbus_connection_call_sync() but also takes and returns #GUnixFDList objects.
16701 * This method is only available on UNIX.
16703 * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
16704 * return values. Free with g_variant_unref().
16710 * g_dbus_connection_close:
16711 * @connection: a #GDBusConnection
16712 * @cancellable: (allow-none): a #GCancellable or %NULL
16713 * @callback: (allow-none): a #GAsyncReadyCallback to call when the request is
16714 * satisfied or %NULL if you don't care about the result
16715 * @user_data: The data to pass to @callback
16717 * Closes @connection. Note that this never causes the process to
16718 * exit (this might only happen if the other end of a shared message
16719 * bus connection disconnects, see #GDBusConnection:exit-on-close).
16721 * Once the connection is closed, operations such as sending a message
16722 * will return with the error %G_IO_ERROR_CLOSED. Closing a connection
16723 * will not automatically flush the connection so queued messages may
16724 * be lost. Use g_dbus_connection_flush() if you need such guarantees.
16726 * If @connection is already closed, this method fails with
16727 * %G_IO_ERROR_CLOSED.
16729 * When @connection has been closed, the #GDBusConnection::closed
16730 * signal is emitted in the
16731 * [thread-default main context][g-main-context-push-thread-default]
16732 * of the thread that @connection was constructed in.
16734 * This is an asynchronous method. When the operation is finished,
16735 * @callback will be invoked in the
16736 * [thread-default main context][g-main-context-push-thread-default]
16737 * of the thread you are calling this method from. You can
16738 * then call g_dbus_connection_close_finish() to get the result of the
16739 * operation. See g_dbus_connection_close_sync() for the synchronous
16747 * g_dbus_connection_close_finish:
16748 * @connection: a #GDBusConnection
16749 * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed
16750 * to g_dbus_connection_close()
16751 * @error: return location for error or %NULL
16753 * Finishes an operation started with g_dbus_connection_close().
16755 * Returns: %TRUE if the operation succeeded, %FALSE if @error is set
16761 * g_dbus_connection_close_sync:
16762 * @connection: a #GDBusConnection
16763 * @cancellable: (allow-none): a #GCancellable or %NULL
16764 * @error: return location for error or %NULL
16766 * Synchronously closees @connection. The calling thread is blocked
16767 * until this is done. See g_dbus_connection_close() for the
16768 * asynchronous version of this method and more details about what it
16771 * Returns: %TRUE if the operation succeeded, %FALSE if @error is set
16777 * g_dbus_connection_emit_signal:
16778 * @connection: a #GDBusConnection
16779 * @destination_bus_name: (allow-none): the unique bus name for the destination
16780 * for the signal or %NULL to emit to all listeners
16781 * @object_path: path of remote object
16782 * @interface_name: D-Bus interface to emit a signal on
16783 * @signal_name: the name of the signal to emit
16784 * @parameters: (allow-none): a #GVariant tuple with parameters for the signal
16785 * or %NULL if not passing parameters
16786 * @error: Return location for error or %NULL
16790 * If the parameters GVariant is floating, it is consumed.
16792 * This can only fail if @parameters is not compatible with the D-Bus protocol.
16794 * Returns: %TRUE unless @error is set
16800 * g_dbus_connection_export_action_group:
16801 * @connection: a #GDBusConnection
16802 * @object_path: a D-Bus object path
16803 * @action_group: a #GActionGroup
16804 * @error: a pointer to a %NULL #GError, or %NULL
16806 * Exports @action_group on @connection at @object_path.
16808 * The implemented D-Bus API should be considered private. It is
16809 * subject to change in the future.
16811 * A given object path can only have one action group exported on it.
16812 * If this constraint is violated, the export will fail and 0 will be
16813 * returned (with @error set accordingly).
16815 * You can unexport the action group using
16816 * g_dbus_connection_unexport_action_group() with the return value of
16819 * The thread default main context is taken at the time of this call.
16820 * All incoming action activations and state change requests are
16821 * reported from this context. Any changes on the action group that
16822 * cause it to emit signals must also come from this same context.
16823 * Since incoming action activations and state change requests are
16824 * rather likely to cause changes on the action group, this effectively
16825 * limits a given action group to being exported from only one main
16828 * Returns: the ID of the export (never zero), or 0 in case of failure
16834 * g_dbus_connection_export_menu_model:
16835 * @connection: a #GDBusConnection
16836 * @object_path: a D-Bus object path
16837 * @menu: a #GMenuModel
16838 * @error: return location for an error, or %NULL
16840 * Exports @menu on @connection at @object_path.
16842 * The implemented D-Bus API should be considered private.
16843 * It is subject to change in the future.
16845 * An object path can only have one menu model exported on it. If this
16846 * constraint is violated, the export will fail and 0 will be
16847 * returned (with @error set accordingly).
16849 * You can unexport the menu model using
16850 * g_dbus_connection_unexport_menu_model() with the return value of
16853 * Returns: the ID of the export (never zero), or 0 in case of failure
16859 * g_dbus_connection_flush:
16860 * @connection: a #GDBusConnection
16861 * @cancellable: (allow-none): a #GCancellable or %NULL
16862 * @callback: (allow-none): a #GAsyncReadyCallback to call when the
16863 * request is satisfied or %NULL if you don't care about the result
16864 * @user_data: The data to pass to @callback
16866 * Asynchronously flushes @connection, that is, writes all queued
16867 * outgoing message to the transport and then flushes the transport
16868 * (using g_output_stream_flush_async()). This is useful in programs
16869 * that wants to emit a D-Bus signal and then exit immediately. Without
16870 * flushing the connection, there is no guaranteed that the message has
16871 * been sent to the networking buffers in the OS kernel.
16873 * This is an asynchronous method. When the operation is finished,
16874 * @callback will be invoked in the
16875 * [thread-default main context][g-main-context-push-thread-default]
16876 * of the thread you are calling this method from. You can
16877 * then call g_dbus_connection_flush_finish() to get the result of the
16878 * operation. See g_dbus_connection_flush_sync() for the synchronous
16886 * g_dbus_connection_flush_finish:
16887 * @connection: a #GDBusConnection
16888 * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed
16889 * to g_dbus_connection_flush()
16890 * @error: return location for error or %NULL
16892 * Finishes an operation started with g_dbus_connection_flush().
16894 * Returns: %TRUE if the operation succeeded, %FALSE if @error is set
16900 * g_dbus_connection_flush_sync:
16901 * @connection: a #GDBusConnection
16902 * @cancellable: (allow-none): a #GCancellable or %NULL
16903 * @error: return location for error or %NULL
16905 * Synchronously flushes @connection. The calling thread is blocked
16906 * until this is done. See g_dbus_connection_flush() for the
16907 * asynchronous version of this method and more details about what it
16910 * Returns: %TRUE if the operation succeeded, %FALSE if @error is set
16916 * g_dbus_connection_get_capabilities:
16917 * @connection: a #GDBusConnection
16919 * Gets the capabilities negotiated with the remote peer
16921 * Returns: zero or more flags from the #GDBusCapabilityFlags enumeration
16927 * g_dbus_connection_get_exit_on_close:
16928 * @connection: a #GDBusConnection
16930 * Gets whether the process is terminated when @connection is
16931 * closed by the remote peer. See
16932 * #GDBusConnection:exit-on-close for more details.
16934 * Returns: whether the process is terminated when @connection is
16935 * closed by the remote peer
16941 * g_dbus_connection_get_guid:
16942 * @connection: a #GDBusConnection
16944 * The GUID of the peer performing the role of server when
16945 * authenticating. See #GDBusConnection:guid for more details.
16947 * Returns: The GUID. Do not free this string, it is owned by
16954 * g_dbus_connection_get_last_serial:
16955 * @connection: a #GDBusConnection
16957 * Retrieves the last serial number assigned to a #GDBusMessage on
16958 * the current thread. This includes messages sent via both low-level
16959 * API such as g_dbus_connection_send_message() as well as
16960 * high-level API such as g_dbus_connection_emit_signal(),
16961 * g_dbus_connection_call() or g_dbus_proxy_call().
16963 * Returns: the last used serial or zero when no message has been sent
16964 * within the current thread
16970 * g_dbus_connection_get_peer_credentials:
16971 * @connection: a #GDBusConnection
16973 * Gets the credentials of the authenticated peer. This will always
16974 * return %NULL unless @connection acted as a server
16975 * (e.g. %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER was passed)
16976 * when set up and the client passed credentials as part of the
16977 * authentication process.
16979 * In a message bus setup, the message bus is always the server and
16980 * each application is a client. So this method will always return
16981 * %NULL for message bus clients.
16983 * Returns: (transfer none) (nullable): a #GCredentials or %NULL if not
16984 * available. Do not free this object, it is owned by @connection.
16990 * g_dbus_connection_get_stream:
16991 * @connection: a #GDBusConnection
16993 * Gets the underlying stream used for IO.
16995 * While the #GDBusConnection is active, it will interact with this
16996 * stream from a worker thread, so it is not safe to interact with
16997 * the stream directly.
16999 * Returns: (transfer none): the stream used for IO
17005 * g_dbus_connection_get_unique_name:
17006 * @connection: a #GDBusConnection
17008 * Gets the unique name of @connection as assigned by the message
17009 * bus. This can also be used to figure out if @connection is a
17010 * message bus connection.
17012 * Returns: the unique name or %NULL if @connection is not a message
17013 * bus connection. Do not free this string, it is owned by
17020 * g_dbus_connection_is_closed:
17021 * @connection: a #GDBusConnection
17023 * Gets whether @connection is closed.
17025 * Returns: %TRUE if the connection is closed, %FALSE otherwise
17031 * g_dbus_connection_new:
17032 * @stream: a #GIOStream
17033 * @guid: (allow-none): the GUID to use if a authenticating as a server or %NULL
17034 * @flags: flags describing how to make the connection
17035 * @observer: (allow-none): a #GDBusAuthObserver or %NULL
17036 * @cancellable: (allow-none): a #GCancellable or %NULL
17037 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
17038 * @user_data: the data to pass to @callback
17040 * Asynchronously sets up a D-Bus connection for exchanging D-Bus messages
17041 * with the end represented by @stream.
17043 * If @stream is a #GSocketConnection, then the corresponding #GSocket
17044 * will be put into non-blocking mode.
17046 * The D-Bus connection will interact with @stream from a worker thread.
17047 * As a result, the caller should not interact with @stream after this
17048 * method has been called, except by calling g_object_unref() on it.
17050 * If @observer is not %NULL it may be used to control the
17051 * authentication process.
17053 * When the operation is finished, @callback will be invoked. You can
17054 * then call g_dbus_connection_new_finish() to get the result of the
17057 * This is a asynchronous failable constructor. See
17058 * g_dbus_connection_new_sync() for the synchronous
17066 * g_dbus_connection_new_finish:
17067 * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback
17068 * passed to g_dbus_connection_new().
17069 * @error: return location for error or %NULL
17071 * Finishes an operation started with g_dbus_connection_new().
17073 * Returns: a #GDBusConnection or %NULL if @error is set. Free
17074 * with g_object_unref().
17080 * g_dbus_connection_new_for_address:
17081 * @address: a D-Bus address
17082 * @flags: flags describing how to make the connection
17083 * @observer: (allow-none): a #GDBusAuthObserver or %NULL
17084 * @cancellable: (allow-none): a #GCancellable or %NULL
17085 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
17086 * @user_data: the data to pass to @callback
17088 * Asynchronously connects and sets up a D-Bus client connection for
17089 * exchanging D-Bus messages with an endpoint specified by @address
17090 * which must be in the D-Bus address format.
17092 * This constructor can only be used to initiate client-side
17093 * connections - use g_dbus_connection_new() if you need to act as the
17094 * server. In particular, @flags cannot contain the
17095 * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER or
17096 * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS flags.
17098 * When the operation is finished, @callback will be invoked. You can
17099 * then call g_dbus_connection_new_finish() to get the result of the
17102 * If @observer is not %NULL it may be used to control the
17103 * authentication process.
17105 * This is a asynchronous failable constructor. See
17106 * g_dbus_connection_new_for_address_sync() for the synchronous
17114 * g_dbus_connection_new_for_address_finish:
17115 * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed
17116 * to g_dbus_connection_new()
17117 * @error: return location for error or %NULL
17119 * Finishes an operation started with g_dbus_connection_new_for_address().
17121 * Returns: a #GDBusConnection or %NULL if @error is set. Free with
17122 * g_object_unref().
17128 * g_dbus_connection_new_for_address_sync:
17129 * @address: a D-Bus address
17130 * @flags: flags describing how to make the connection
17131 * @observer: (allow-none): a #GDBusAuthObserver or %NULL
17132 * @cancellable: (allow-none): a #GCancellable or %NULL
17133 * @error: return location for error or %NULL
17135 * Synchronously connects and sets up a D-Bus client connection for
17136 * exchanging D-Bus messages with an endpoint specified by @address
17137 * which must be in the D-Bus address format.
17139 * This constructor can only be used to initiate client-side
17140 * connections - use g_dbus_connection_new_sync() if you need to act
17141 * as the server. In particular, @flags cannot contain the
17142 * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER or
17143 * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS flags.
17145 * This is a synchronous failable constructor. See
17146 * g_dbus_connection_new_for_address() for the asynchronous version.
17148 * If @observer is not %NULL it may be used to control the
17149 * authentication process.
17151 * Returns: a #GDBusConnection or %NULL if @error is set. Free with
17152 * g_object_unref().
17158 * g_dbus_connection_new_sync:
17159 * @stream: a #GIOStream
17160 * @guid: (allow-none): the GUID to use if a authenticating as a server or %NULL
17161 * @flags: flags describing how to make the connection
17162 * @observer: (allow-none): a #GDBusAuthObserver or %NULL
17163 * @cancellable: (allow-none): a #GCancellable or %NULL
17164 * @error: return location for error or %NULL
17166 * Synchronously sets up a D-Bus connection for exchanging D-Bus messages
17167 * with the end represented by @stream.
17169 * If @stream is a #GSocketConnection, then the corresponding #GSocket
17170 * will be put into non-blocking mode.
17172 * The D-Bus connection will interact with @stream from a worker thread.
17173 * As a result, the caller should not interact with @stream after this
17174 * method has been called, except by calling g_object_unref() on it.
17176 * If @observer is not %NULL it may be used to control the
17177 * authentication process.
17179 * This is a synchronous failable constructor. See
17180 * g_dbus_connection_new() for the asynchronous version.
17182 * Returns: a #GDBusConnection or %NULL if @error is set. Free with g_object_unref().
17188 * g_dbus_connection_register_object:
17189 * @connection: a #GDBusConnection
17190 * @object_path: the object path to register at
17191 * @interface_info: introspection data for the interface
17192 * @vtable: (allow-none): a #GDBusInterfaceVTable to call into or %NULL
17193 * @user_data: (allow-none): data to pass to functions in @vtable
17194 * @user_data_free_func: function to call when the object path is unregistered
17195 * @error: return location for error or %NULL
17197 * Registers callbacks for exported objects at @object_path with the
17198 * D-Bus interface that is described in @interface_info.
17200 * Calls to functions in @vtable (and @user_data_free_func) will happen
17202 * [thread-default main context][g-main-context-push-thread-default]
17203 * of the thread you are calling this method from.
17205 * Note that all #GVariant values passed to functions in @vtable will match
17206 * the signature given in @interface_info - if a remote caller passes
17207 * incorrect values, the `org.freedesktop.DBus.Error.InvalidArgs`
17208 * is returned to the remote caller.
17210 * Additionally, if the remote caller attempts to invoke methods or
17211 * access properties not mentioned in @interface_info the
17212 * `org.freedesktop.DBus.Error.UnknownMethod` resp.
17213 * `org.freedesktop.DBus.Error.InvalidArgs` errors
17214 * are returned to the caller.
17216 * It is considered a programming error if the
17217 * #GDBusInterfaceGetPropertyFunc function in @vtable returns a
17218 * #GVariant of incorrect type.
17220 * If an existing callback is already registered at @object_path and
17221 * @interface_name, then @error is set to #G_IO_ERROR_EXISTS.
17223 * GDBus automatically implements the standard D-Bus interfaces
17224 * org.freedesktop.DBus.Properties, org.freedesktop.DBus.Introspectable
17225 * and org.freedesktop.Peer, so you don't have to implement those for the
17226 * objects you export. You can implement org.freedesktop.DBus.Properties
17227 * yourself, e.g. to handle getting and setting of properties asynchronously.
17229 * Note that the reference count on @interface_info will be
17230 * incremented by 1 (unless allocated statically, e.g. if the
17231 * reference count is -1, see g_dbus_interface_info_ref()) for as long
17232 * as the object is exported. Also note that @vtable will be copied.
17234 * See this [server][gdbus-server] for an example of how to use this method.
17236 * Returns: 0 if @error is set, otherwise a registration id (never 0)
17237 * that can be used with g_dbus_connection_unregister_object()
17243 * g_dbus_connection_register_object_with_closures: (rename-to g_dbus_connection_register_object)
17244 * @connection: A #GDBusConnection.
17245 * @object_path: The object path to register at.
17246 * @interface_info: Introspection data for the interface.
17247 * @method_call_closure: (nullable): #GClosure for handling incoming method calls.
17248 * @get_property_closure: (nullable): #GClosure for getting a property.
17249 * @set_property_closure: (nullable): #GClosure for setting a property.
17250 * @error: Return location for error or %NULL.
17252 * Version of g_dbus_connection_register_object() using closures instead of a
17253 * #GDBusInterfaceVTable for easier binding in other languages.
17255 * Returns: 0 if @error is set, otherwise a registration id (never 0)
17256 * that can be used with g_dbus_connection_unregister_object() .
17262 * g_dbus_connection_register_subtree:
17263 * @connection: a #GDBusConnection
17264 * @object_path: the object path to register the subtree at
17265 * @vtable: a #GDBusSubtreeVTable to enumerate, introspect and
17266 * dispatch nodes in the subtree
17267 * @flags: flags used to fine tune the behavior of the subtree
17268 * @user_data: data to pass to functions in @vtable
17269 * @user_data_free_func: function to call when the subtree is unregistered
17270 * @error: return location for error or %NULL
17272 * Registers a whole subtree of dynamic objects.
17274 * The @enumerate and @introspection functions in @vtable are used to
17275 * convey, to remote callers, what nodes exist in the subtree rooted
17278 * When handling remote calls into any node in the subtree, first the
17279 * @enumerate function is used to check if the node exists. If the node exists
17280 * or the #G_DBUS_SUBTREE_FLAGS_DISPATCH_TO_UNENUMERATED_NODES flag is set
17281 * the @introspection function is used to check if the node supports the
17282 * requested method. If so, the @dispatch function is used to determine
17283 * where to dispatch the call. The collected #GDBusInterfaceVTable and
17284 * #gpointer will be used to call into the interface vtable for processing
17287 * All calls into user-provided code will be invoked in the
17288 * [thread-default main context][g-main-context-push-thread-default]
17289 * of the thread you are calling this method from.
17291 * If an existing subtree is already registered at @object_path or
17292 * then @error is set to #G_IO_ERROR_EXISTS.
17294 * Note that it is valid to register regular objects (using
17295 * g_dbus_connection_register_object()) in a subtree registered with
17296 * g_dbus_connection_register_subtree() - if so, the subtree handler
17297 * is tried as the last resort. One way to think about a subtree
17298 * handler is to consider it a fallback handler for object paths not
17299 * registered via g_dbus_connection_register_object() or other bindings.
17301 * Note that @vtable will be copied so you cannot change it after
17304 * See this [server][gdbus-subtree-server] for an example of how to use
17307 * Returns: 0 if @error is set, otherwise a subtree registration id (never 0)
17308 * that can be used with g_dbus_connection_unregister_subtree() .
17314 * g_dbus_connection_remove_filter:
17315 * @connection: a #GDBusConnection
17316 * @filter_id: an identifier obtained from g_dbus_connection_add_filter()
17318 * Removes a filter.
17320 * Note that since filters run in a different thread, there is a race
17321 * condition where it is possible that the filter will be running even
17322 * after calling g_dbus_connection_remove_filter(), so you cannot just
17323 * free data that the filter might be using. Instead, you should pass
17324 * a #GDestroyNotify to g_dbus_connection_add_filter(), which will be
17325 * called when it is guaranteed that the data is no longer needed.
17332 * g_dbus_connection_send_message:
17333 * @connection: a #GDBusConnection
17334 * @message: a #GDBusMessage
17335 * @flags: flags affecting how the message is sent
17336 * @out_serial: (out) (allow-none): return location for serial number assigned
17337 * to @message when sending it or %NULL
17338 * @error: Return location for error or %NULL
17340 * Asynchronously sends @message to the peer represented by @connection.
17342 * Unless @flags contain the
17343 * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number
17344 * will be assigned by @connection and set on @message via
17345 * g_dbus_message_set_serial(). If @out_serial is not %NULL, then the
17346 * serial number used will be written to this location prior to
17347 * submitting the message to the underlying transport.
17349 * If @connection is closed then the operation will fail with
17350 * %G_IO_ERROR_CLOSED. If @message is not well-formed,
17351 * the operation fails with %G_IO_ERROR_INVALID_ARGUMENT.
17353 * See this [server][gdbus-server] and [client][gdbus-unix-fd-client]
17354 * for an example of how to use this low-level API to send and receive
17355 * UNIX file descriptors.
17357 * Note that @message must be unlocked, unless @flags contain the
17358 * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag.
17360 * Returns: %TRUE if the message was well-formed and queued for
17361 * transmission, %FALSE if @error is set
17367 * g_dbus_connection_send_message_with_reply:
17368 * @connection: a #GDBusConnection
17369 * @message: a #GDBusMessage
17370 * @flags: flags affecting how the message is sent
17371 * @timeout_msec: the timeout in milliseconds, -1 to use the default
17372 * timeout or %G_MAXINT for no timeout
17373 * @out_serial: (out) (allow-none): return location for serial number assigned
17374 * to @message when sending it or %NULL
17375 * @cancellable: (allow-none): a #GCancellable or %NULL
17376 * @callback: (allow-none): a #GAsyncReadyCallback to call when the request
17377 * is satisfied or %NULL if you don't care about the result
17378 * @user_data: The data to pass to @callback
17380 * Asynchronously sends @message to the peer represented by @connection.
17382 * Unless @flags contain the
17383 * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number
17384 * will be assigned by @connection and set on @message via
17385 * g_dbus_message_set_serial(). If @out_serial is not %NULL, then the
17386 * serial number used will be written to this location prior to
17387 * submitting the message to the underlying transport.
17389 * If @connection is closed then the operation will fail with
17390 * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will
17391 * fail with %G_IO_ERROR_CANCELLED. If @message is not well-formed,
17392 * the operation fails with %G_IO_ERROR_INVALID_ARGUMENT.
17394 * This is an asynchronous method. When the operation is finished, @callback
17395 * will be invoked in the
17396 * [thread-default main context][g-main-context-push-thread-default]
17397 * of the thread you are calling this method from. You can then call
17398 * g_dbus_connection_send_message_with_reply_finish() to get the result of the operation.
17399 * See g_dbus_connection_send_message_with_reply_sync() for the synchronous version.
17401 * Note that @message must be unlocked, unless @flags contain the
17402 * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag.
17404 * See this [server][gdbus-server] and [client][gdbus-unix-fd-client]
17405 * for an example of how to use this low-level API to send and receive
17406 * UNIX file descriptors.
17413 * g_dbus_connection_send_message_with_reply_finish:
17414 * @connection: a #GDBusConnection
17415 * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed to
17416 * g_dbus_connection_send_message_with_reply()
17417 * @error: teturn location for error or %NULL
17419 * Finishes an operation started with g_dbus_connection_send_message_with_reply().
17421 * Note that @error is only set if a local in-process error
17422 * occurred. That is to say that the returned #GDBusMessage object may
17423 * be of type %G_DBUS_MESSAGE_TYPE_ERROR. Use
17424 * g_dbus_message_to_gerror() to transcode this to a #GError.
17426 * See this [server][gdbus-server] and [client][gdbus-unix-fd-client]
17427 * for an example of how to use this low-level API to send and receive
17428 * UNIX file descriptors.
17430 * Returns: (transfer full): a locked #GDBusMessage or %NULL if @error is set
17436 * g_dbus_connection_send_message_with_reply_sync:
17437 * @connection: a #GDBusConnection
17438 * @message: a #GDBusMessage
17439 * @flags: flags affecting how the message is sent.
17440 * @timeout_msec: the timeout in milliseconds, -1 to use the default
17441 * timeout or %G_MAXINT for no timeout
17442 * @out_serial: (out) (allow-none): return location for serial number
17443 * assigned to @message when sending it or %NULL
17444 * @cancellable: (allow-none): a #GCancellable or %NULL
17445 * @error: return location for error or %NULL
17447 * Synchronously sends @message to the peer represented by @connection
17448 * and blocks the calling thread until a reply is received or the
17449 * timeout is reached. See g_dbus_connection_send_message_with_reply()
17450 * for the asynchronous version of this method.
17452 * Unless @flags contain the
17453 * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number
17454 * will be assigned by @connection and set on @message via
17455 * g_dbus_message_set_serial(). If @out_serial is not %NULL, then the
17456 * serial number used will be written to this location prior to
17457 * submitting the message to the underlying transport.
17459 * If @connection is closed then the operation will fail with
17460 * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will
17461 * fail with %G_IO_ERROR_CANCELLED. If @message is not well-formed,
17462 * the operation fails with %G_IO_ERROR_INVALID_ARGUMENT.
17464 * Note that @error is only set if a local in-process error
17465 * occurred. That is to say that the returned #GDBusMessage object may
17466 * be of type %G_DBUS_MESSAGE_TYPE_ERROR. Use
17467 * g_dbus_message_to_gerror() to transcode this to a #GError.
17469 * See this [server][gdbus-server] and [client][gdbus-unix-fd-client]
17470 * for an example of how to use this low-level API to send and receive
17471 * UNIX file descriptors.
17473 * Note that @message must be unlocked, unless @flags contain the
17474 * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag.
17476 * Returns: (transfer full): a locked #GDBusMessage that is the reply
17477 * to @message or %NULL if @error is set
17483 * g_dbus_connection_set_exit_on_close:
17484 * @connection: a #GDBusConnection
17485 * @exit_on_close: whether the process should be terminated
17486 * when @connection is closed by the remote peer
17488 * Sets whether the process should be terminated when @connection is
17489 * closed by the remote peer. See #GDBusConnection:exit-on-close for
17492 * Note that this function should be used with care. Most modern UNIX
17493 * desktops tie the notion of a user session the session bus, and expect
17494 * all of a users applications to quit when their bus connection goes away.
17495 * If you are setting @exit_on_close to %FALSE for the shared session
17496 * bus connection, you should make sure that your application exits
17497 * when the user session ends.
17504 * g_dbus_connection_signal_subscribe:
17505 * @connection: a #GDBusConnection
17506 * @sender: (allow-none): sender name to match on (unique or well-known name)
17507 * or %NULL to listen from all senders
17508 * @interface_name: (allow-none): D-Bus interface name to match on or %NULL to
17509 * match on all interfaces
17510 * @member: (allow-none): D-Bus signal name to match on or %NULL to match on
17512 * @object_path: (allow-none): object path to match on or %NULL to match on
17514 * @arg0: (allow-none): contents of first string argument to match on or %NULL
17515 * to match on all kinds of arguments
17516 * @flags: #GDBusSignalFlags describing how arg0 is used in subscribing to the
17518 * @callback: callback to invoke when there is a signal matching the requested data
17519 * @user_data: user data to pass to @callback
17520 * @user_data_free_func: (allow-none): function to free @user_data with when
17521 * subscription is removed or %NULL
17523 * Subscribes to signals on @connection and invokes @callback with a whenever
17524 * the signal is received. Note that @callback will be invoked in the
17525 * [thread-default main context][g-main-context-push-thread-default]
17526 * of the thread you are calling this method from.
17528 * If @connection is not a message bus connection, @sender must be
17531 * If @sender is a well-known name note that @callback is invoked with
17532 * the unique name for the owner of @sender, not the well-known name
17533 * as one would expect. This is because the message bus rewrites the
17534 * name. As such, to avoid certain race conditions, users should be
17535 * tracking the name owner of the well-known name and use that when
17536 * processing the received signal.
17538 * If one of %G_DBUS_SIGNAL_FLAGS_MATCH_ARG0_NAMESPACE or
17539 * %G_DBUS_SIGNAL_FLAGS_MATCH_ARG0_PATH are given, @arg0 is
17540 * interpreted as part of a namespace or path. The first argument
17541 * of a signal is matched against that part as specified by D-Bus.
17543 * If @user_data_free_func is non-%NULL, it will be called (in the
17544 * thread-default main context of the thread you are calling this
17545 * method from) at some point after @user_data is no longer
17546 * needed. (It is not guaranteed to be called synchronously when the
17547 * signal is unsubscribed from, and may be called after @connection
17548 * has been destroyed.)
17550 * Returns: a subscription identifier that can be used with g_dbus_connection_signal_unsubscribe()
17556 * g_dbus_connection_signal_unsubscribe:
17557 * @connection: a #GDBusConnection
17558 * @subscription_id: a subscription id obtained from
17559 * g_dbus_connection_signal_subscribe()
17561 * Unsubscribes from signals.
17568 * g_dbus_connection_start_message_processing:
17569 * @connection: a #GDBusConnection
17571 * If @connection was created with
17572 * %G_DBUS_CONNECTION_FLAGS_DELAY_MESSAGE_PROCESSING, this method
17573 * starts processing messages. Does nothing on if @connection wasn't
17574 * created with this flag or if the method has already been called.
17581 * g_dbus_connection_unexport_action_group:
17582 * @connection: a #GDBusConnection
17583 * @export_id: the ID from g_dbus_connection_export_action_group()
17585 * Reverses the effect of a previous call to
17586 * g_dbus_connection_export_action_group().
17588 * It is an error to call this function with an ID that wasn't returned
17589 * from g_dbus_connection_export_action_group() or to call it with the
17590 * same ID more than once.
17597 * g_dbus_connection_unexport_menu_model:
17598 * @connection: a #GDBusConnection
17599 * @export_id: the ID from g_dbus_connection_export_menu_model()
17601 * Reverses the effect of a previous call to
17602 * g_dbus_connection_export_menu_model().
17604 * It is an error to call this function with an ID that wasn't returned
17605 * from g_dbus_connection_export_menu_model() or to call it with the
17606 * same ID more than once.
17613 * g_dbus_connection_unregister_object:
17614 * @connection: a #GDBusConnection
17615 * @registration_id: a registration id obtained from
17616 * g_dbus_connection_register_object()
17618 * Unregisters an object.
17620 * Returns: %TRUE if the object was unregistered, %FALSE otherwise
17626 * g_dbus_connection_unregister_subtree:
17627 * @connection: a #GDBusConnection
17628 * @registration_id: a subtree registration id obtained from
17629 * g_dbus_connection_register_subtree()
17631 * Unregisters a subtree.
17633 * Returns: %TRUE if the subtree was unregistered, %FALSE otherwise
17639 * g_dbus_error_encode_gerror:
17640 * @error: A #GError.
17642 * Creates a D-Bus error name to use for @error. If @error matches
17643 * a registered error (cf. g_dbus_error_register_error()), the corresponding
17644 * D-Bus error name will be returned.
17646 * Otherwise the a name of the form
17647 * `org.gtk.GDBus.UnmappedGError.Quark._ESCAPED_QUARK_NAME.Code_ERROR_CODE`
17648 * will be used. This allows other GDBus applications to map the error
17649 * on the wire back to a #GError using g_dbus_error_new_for_dbus_error().
17651 * This function is typically only used in object mappings to put a
17652 * #GError on the wire. Regular applications should not use it.
17654 * Returns: A D-Bus error name (never %NULL). Free with g_free().
17660 * g_dbus_error_get_remote_error:
17661 * @error: a #GError
17663 * Gets the D-Bus error name used for @error, if any.
17665 * This function is guaranteed to return a D-Bus error name for all
17666 * #GErrors returned from functions handling remote method calls
17667 * (e.g. g_dbus_connection_call_finish()) unless
17668 * g_dbus_error_strip_remote_error() has been used on @error.
17670 * Returns: an allocated string or %NULL if the D-Bus error name
17671 * could not be found. Free with g_free().
17677 * g_dbus_error_is_remote_error:
17678 * @error: A #GError.
17680 * Checks if @error represents an error received via D-Bus from a remote peer. If so,
17681 * use g_dbus_error_get_remote_error() to get the name of the error.
17683 * Returns: %TRUE if @error represents an error from a remote peer,
17684 * %FALSE otherwise.
17690 * g_dbus_error_new_for_dbus_error:
17691 * @dbus_error_name: D-Bus error name.
17692 * @dbus_error_message: D-Bus error message.
17694 * Creates a #GError based on the contents of @dbus_error_name and
17695 * @dbus_error_message.
17697 * Errors registered with g_dbus_error_register_error() will be looked
17698 * up using @dbus_error_name and if a match is found, the error domain
17699 * and code is used. Applications can use g_dbus_error_get_remote_error()
17700 * to recover @dbus_error_name.
17702 * If a match against a registered error is not found and the D-Bus
17703 * error name is in a form as returned by g_dbus_error_encode_gerror()
17704 * the error domain and code encoded in the name is used to
17705 * create the #GError. Also, @dbus_error_name is added to the error message
17706 * such that it can be recovered with g_dbus_error_get_remote_error().
17708 * Otherwise, a #GError with the error code %G_IO_ERROR_DBUS_ERROR
17709 * in the #G_IO_ERROR error domain is returned. Also, @dbus_error_name is
17710 * added to the error message such that it can be recovered with
17711 * g_dbus_error_get_remote_error().
17713 * In all three cases, @dbus_error_name can always be recovered from the
17714 * returned #GError using the g_dbus_error_get_remote_error() function
17715 * (unless g_dbus_error_strip_remote_error() hasn't been used on the returned error).
17717 * This function is typically only used in object mappings to prepare
17718 * #GError instances for applications. Regular applications should not use
17721 * Returns: An allocated #GError. Free with g_error_free().
17727 * g_dbus_error_register_error:
17728 * @error_domain: A #GQuark for a error domain.
17729 * @error_code: An error code.
17730 * @dbus_error_name: A D-Bus error name.
17732 * Creates an association to map between @dbus_error_name and
17733 * #GErrors specified by @error_domain and @error_code.
17735 * This is typically done in the routine that returns the #GQuark for
17738 * Returns: %TRUE if the association was created, %FALSE if it already
17745 * g_dbus_error_register_error_domain:
17746 * @error_domain_quark_name: The error domain name.
17747 * @quark_volatile: A pointer where to store the #GQuark.
17748 * @entries: A pointer to @num_entries #GDBusErrorEntry struct items.
17749 * @num_entries: Number of items to register.
17751 * Helper function for associating a #GError error domain with D-Bus error names.
17758 * g_dbus_error_set_dbus_error:
17759 * @error: A pointer to a #GError or %NULL.
17760 * @dbus_error_name: D-Bus error name.
17761 * @dbus_error_message: D-Bus error message.
17762 * @format: (allow-none): printf()-style format to prepend to @dbus_error_message or %NULL.
17763 * @...: Arguments for @format.
17765 * Does nothing if @error is %NULL. Otherwise sets *@error to
17766 * a new #GError created with g_dbus_error_new_for_dbus_error()
17767 * with @dbus_error_message prepend with @format (unless %NULL).
17774 * g_dbus_error_set_dbus_error_valist:
17775 * @error: A pointer to a #GError or %NULL.
17776 * @dbus_error_name: D-Bus error name.
17777 * @dbus_error_message: D-Bus error message.
17778 * @format: (allow-none): printf()-style format to prepend to @dbus_error_message or %NULL.
17779 * @var_args: Arguments for @format.
17781 * Like g_dbus_error_set_dbus_error() but intended for language bindings.
17788 * g_dbus_error_strip_remote_error:
17789 * @error: A #GError.
17791 * Looks for extra information in the error message used to recover
17792 * the D-Bus error name and strips it if found. If stripped, the
17793 * message field in @error will correspond exactly to what was
17794 * received on the wire.
17796 * This is typically used when presenting errors to the end user.
17798 * Returns: %TRUE if information was stripped, %FALSE otherwise.
17804 * g_dbus_error_unregister_error:
17805 * @error_domain: A #GQuark for a error domain.
17806 * @error_code: An error code.
17807 * @dbus_error_name: A D-Bus error name.
17809 * Destroys an association previously set up with g_dbus_error_register_error().
17811 * Returns: %TRUE if the association was destroyed, %FALSE if it wasn't found.
17817 * g_dbus_generate_guid:
17819 * Generate a D-Bus GUID that can be used with
17820 * e.g. g_dbus_connection_new().
17822 * See the D-Bus specification regarding what strings are valid D-Bus
17823 * GUID (for example, D-Bus GUIDs are not RFC-4122 compliant).
17825 * Returns: A valid D-Bus GUID. Free with g_free().
17831 * g_dbus_gvalue_to_gvariant:
17832 * @gvalue: A #GValue to convert to a #GVariant
17833 * @type: A #GVariantType
17835 * Converts a #GValue to a #GVariant of the type indicated by the @type
17838 * The conversion is using the following rules:
17840 * - #G_TYPE_STRING: 's', 'o', 'g' or 'ay'
17841 * - #G_TYPE_STRV: 'as', 'ao' or 'aay'
17842 * - #G_TYPE_BOOLEAN: 'b'
17843 * - #G_TYPE_UCHAR: 'y'
17844 * - #G_TYPE_INT: 'i', 'n'
17845 * - #G_TYPE_UINT: 'u', 'q'
17846 * - #G_TYPE_INT64 'x'
17847 * - #G_TYPE_UINT64: 't'
17848 * - #G_TYPE_DOUBLE: 'd'
17849 * - #G_TYPE_VARIANT: Any #GVariantType
17851 * This can fail if e.g. @gvalue is of type #G_TYPE_STRING and @type
17852 * is ['i'][G-VARIANT-TYPE-INT32:CAPS]. It will also fail for any #GType
17853 * (including e.g. #G_TYPE_OBJECT and #G_TYPE_BOXED derived-types) not
17854 * in the table above.
17856 * Note that if @gvalue is of type #G_TYPE_VARIANT and its value is
17857 * %NULL, the empty #GVariant instance (never %NULL) for @type is
17858 * returned (e.g. 0 for scalar types, the empty string for string types,
17859 * '/' for object path types, the empty array for any array type and so on).
17861 * See the g_dbus_gvariant_to_gvalue() function for how to convert a
17862 * #GVariant to a #GValue.
17864 * Returns: A #GVariant (never floating) of #GVariantType @type holding
17865 * the data from @gvalue or %NULL in case of failure. Free with
17866 * g_variant_unref().
17872 * g_dbus_gvariant_to_gvalue:
17873 * @value: A #GVariant.
17874 * @out_gvalue: (out): Return location pointing to a zero-filled (uninitialized) #GValue.
17876 * Converts a #GVariant to a #GValue. If @value is floating, it is consumed.
17878 * The rules specified in the g_dbus_gvalue_to_gvariant() function are
17879 * used - this function is essentially its reverse form.
17881 * The conversion never fails - a valid #GValue is always returned in
17889 * g_dbus_interface_dup_object: (rename-to g_dbus_interface_get_object)
17890 * @interface_: An exported D-Bus interface.
17892 * Gets the #GDBusObject that @interface_ belongs to, if any.
17894 * Returns: (transfer full): A #GDBusObject or %NULL. The returned
17895 * reference should be freed with g_object_unref().
17901 * g_dbus_interface_get_info:
17902 * @interface_: An exported D-Bus interface.
17904 * Gets D-Bus introspection information for the D-Bus interface
17905 * implemented by @interface_.
17907 * Returns: (transfer none): A #GDBusInterfaceInfo. Do not free.
17913 * g_dbus_interface_get_object: (skip)
17914 * @interface_: An exported D-Bus interface
17916 * Gets the #GDBusObject that @interface_ belongs to, if any.
17918 * It is not safe to use the returned object if @interface_ or
17919 * the returned object is being used from other threads. See
17920 * g_dbus_interface_dup_object() for a thread-safe alternative.
17922 * Returns: (transfer none): A #GDBusObject or %NULL. The returned
17923 * reference belongs to @interface_ and should not be freed.
17929 * g_dbus_interface_info_cache_build:
17930 * @info: A #GDBusInterfaceInfo.
17932 * Builds a lookup-cache to speed up
17933 * g_dbus_interface_info_lookup_method(),
17934 * g_dbus_interface_info_lookup_signal() and
17935 * g_dbus_interface_info_lookup_property().
17937 * If this has already been called with @info, the existing cache is
17938 * used and its use count is increased.
17940 * Note that @info cannot be modified until
17941 * g_dbus_interface_info_cache_release() is called.
17948 * g_dbus_interface_info_cache_release:
17949 * @info: A GDBusInterfaceInfo
17951 * Decrements the usage count for the cache for @info built by
17952 * g_dbus_interface_info_cache_build() (if any) and frees the
17953 * resources used by the cache if the usage count drops to zero.
17960 * g_dbus_interface_info_generate_xml:
17961 * @info: A #GDBusNodeInfo
17962 * @indent: Indentation level.
17963 * @string_builder: (out): A #GString to to append XML data to.
17965 * Appends an XML representation of @info (and its children) to @string_builder.
17967 * This function is typically used for generating introspection XML
17968 * documents at run-time for handling the
17969 * `org.freedesktop.DBus.Introspectable.Introspect`
17977 * g_dbus_interface_info_lookup_method:
17978 * @info: A #GDBusInterfaceInfo.
17979 * @name: A D-Bus method name (typically in CamelCase)
17981 * Looks up information about a method.
17983 * The cost of this function is O(n) in number of methods unless
17984 * g_dbus_interface_info_cache_build() has been used on @info.
17986 * Returns: (transfer none): A #GDBusMethodInfo or %NULL if not found. Do not free, it is owned by @info.
17992 * g_dbus_interface_info_lookup_property:
17993 * @info: A #GDBusInterfaceInfo.
17994 * @name: A D-Bus property name (typically in CamelCase).
17996 * Looks up information about a property.
17998 * The cost of this function is O(n) in number of properties unless
17999 * g_dbus_interface_info_cache_build() has been used on @info.
18001 * Returns: (transfer none): A #GDBusPropertyInfo or %NULL if not found. Do not free, it is owned by @info.
18007 * g_dbus_interface_info_lookup_signal:
18008 * @info: A #GDBusInterfaceInfo.
18009 * @name: A D-Bus signal name (typically in CamelCase)
18011 * Looks up information about a signal.
18013 * The cost of this function is O(n) in number of signals unless
18014 * g_dbus_interface_info_cache_build() has been used on @info.
18016 * Returns: (transfer none): A #GDBusSignalInfo or %NULL if not found. Do not free, it is owned by @info.
18022 * g_dbus_interface_info_ref:
18023 * @info: A #GDBusInterfaceInfo
18025 * If @info is statically allocated does nothing. Otherwise increases
18026 * the reference count.
18028 * Returns: The same @info.
18034 * g_dbus_interface_info_unref:
18035 * @info: A #GDBusInterfaceInfo.
18037 * If @info is statically allocated, does nothing. Otherwise decreases
18038 * the reference count of @info. When its reference count drops to 0,
18039 * the memory used is freed.
18046 * g_dbus_interface_set_object:
18047 * @interface_: An exported D-Bus interface.
18048 * @object: (allow-none): A #GDBusObject or %NULL.
18050 * Sets the #GDBusObject for @interface_ to @object.
18052 * Note that @interface_ will hold a weak reference to @object.
18059 * g_dbus_interface_skeleton_export:
18060 * @interface_: The D-Bus interface to export.
18061 * @connection: A #GDBusConnection to export @interface_ on.
18062 * @object_path: The path to export the interface at.
18063 * @error: Return location for error or %NULL.
18065 * Exports @interface_ at @object_path on @connection.
18067 * This can be called multiple times to export the same @interface_
18068 * onto multiple connections however the @object_path provided must be
18069 * the same for all connections.
18071 * Use g_dbus_interface_skeleton_unexport() to unexport the object.
18073 * Returns: %TRUE if the interface was exported on @connection, otherwise %FALSE with
18080 * g_dbus_interface_skeleton_flush:
18081 * @interface_: A #GDBusInterfaceSkeleton.
18083 * If @interface_ has outstanding changes, request for these changes to be
18084 * emitted immediately.
18086 * For example, an exported D-Bus interface may queue up property
18087 * changes and emit the
18088 * `org.freedesktop.DBus.Properties::Propert``
18089 * signal later (e.g. in an idle handler). This technique is useful
18090 * for collapsing multiple property changes into one.
18097 * g_dbus_interface_skeleton_get_connection:
18098 * @interface_: A #GDBusInterfaceSkeleton.
18100 * Gets the first connection that @interface_ is exported on, if any.
18102 * Returns: (transfer none): A #GDBusConnection or %NULL if @interface_ is
18103 * not exported anywhere. Do not free, the object belongs to @interface_.
18109 * g_dbus_interface_skeleton_get_connections:
18110 * @interface_: A #GDBusInterfaceSkeleton.
18112 * Gets a list of the connections that @interface_ is exported on.
18114 * Returns: (element-type GDBusConnection) (transfer full): A list of
18115 * all the connections that @interface_ is exported on. The returned
18116 * list should be freed with g_list_free() after each element has
18117 * been freed with g_object_unref().
18123 * g_dbus_interface_skeleton_get_flags:
18124 * @interface_: A #GDBusInterfaceSkeleton.
18126 * Gets the #GDBusInterfaceSkeletonFlags that describes what the behavior
18129 * Returns: One or more flags from the #GDBusInterfaceSkeletonFlags enumeration.
18135 * g_dbus_interface_skeleton_get_info:
18136 * @interface_: A #GDBusInterfaceSkeleton.
18138 * Gets D-Bus introspection information for the D-Bus interface
18139 * implemented by @interface_.
18141 * Returns: (transfer none): A #GDBusInterfaceInfo (never %NULL). Do not free.
18147 * g_dbus_interface_skeleton_get_object_path:
18148 * @interface_: A #GDBusInterfaceSkeleton.
18150 * Gets the object path that @interface_ is exported on, if any.
18152 * Returns: A string owned by @interface_ or %NULL if @interface_ is not exported
18153 * anywhere. Do not free, the string belongs to @interface_.
18159 * g_dbus_interface_skeleton_get_properties:
18160 * @interface_: A #GDBusInterfaceSkeleton.
18162 * Gets all D-Bus properties for @interface_.
18164 * Returns: (transfer full): A #GVariant of type
18165 * ['a{sv}'][G-VARIANT-TYPE-VARDICT:CAPS].
18166 * Free with g_variant_unref().
18172 * g_dbus_interface_skeleton_get_vtable: (skip)
18173 * @interface_: A #GDBusInterfaceSkeleton.
18175 * Gets the interface vtable for the D-Bus interface implemented by
18176 * @interface_. The returned function pointers should expect @interface_
18177 * itself to be passed as @user_data.
18179 * Returns: A #GDBusInterfaceVTable (never %NULL).
18185 * g_dbus_interface_skeleton_has_connection:
18186 * @interface_: A #GDBusInterfaceSkeleton.
18187 * @connection: A #GDBusConnection.
18189 * Checks if @interface_ is exported on @connection.
18191 * Returns: %TRUE if @interface_ is exported on @connection, %FALSE otherwise.
18197 * g_dbus_interface_skeleton_set_flags:
18198 * @interface_: A #GDBusInterfaceSkeleton.
18199 * @flags: Flags from the #GDBusInterfaceSkeletonFlags enumeration.
18201 * Sets flags describing what the behavior of @skeleton should be.
18208 * g_dbus_interface_skeleton_unexport:
18209 * @interface_: A #GDBusInterfaceSkeleton.
18211 * Stops exporting @interface_ on all connections it is exported on.
18213 * To unexport @interface_ from only a single connection, use
18214 * g_dbus_interface_skeleton_unexport_from_connection()
18221 * g_dbus_interface_skeleton_unexport_from_connection:
18222 * @interface_: A #GDBusInterfaceSkeleton.
18223 * @connection: A #GDBusConnection.
18225 * Stops exporting @interface_ on @connection.
18227 * To stop exporting on all connections the interface is exported on,
18228 * use g_dbus_interface_skeleton_unexport().
18235 * g_dbus_is_address:
18236 * @string: A string.
18238 * Checks if @string is a D-Bus address.
18240 * This doesn't check if @string is actually supported by #GDBusServer
18241 * or #GDBusConnection - use g_dbus_is_supported_address() to do more
18244 * Returns: %TRUE if @string is a valid D-Bus address, %FALSE otherwise.
18251 * @string: The string to check.
18253 * Checks if @string is a D-Bus GUID.
18255 * See the D-Bus specification regarding what strings are valid D-Bus
18256 * GUID (for example, D-Bus GUIDs are not RFC-4122 compliant).
18258 * Returns: %TRUE if @string is a guid, %FALSE otherwise.
18264 * g_dbus_is_interface_name:
18265 * @string: The string to check.
18267 * Checks if @string is a valid D-Bus interface name.
18269 * Returns: %TRUE if valid, %FALSE otherwise.
18275 * g_dbus_is_member_name:
18276 * @string: The string to check.
18278 * Checks if @string is a valid D-Bus member (e.g. signal or method) name.
18280 * Returns: %TRUE if valid, %FALSE otherwise.
18287 * @string: The string to check.
18289 * Checks if @string is a valid D-Bus bus name (either unique or well-known).
18291 * Returns: %TRUE if valid, %FALSE otherwise.
18297 * g_dbus_is_supported_address:
18298 * @string: A string.
18299 * @error: Return location for error or %NULL.
18301 * Like g_dbus_is_address() but also checks if the library suppors the
18302 * transports in @string and that key/value pairs for each transport
18305 * Returns: %TRUE if @string is a valid D-Bus address that is
18306 * supported by this library, %FALSE if @error is set.
18312 * g_dbus_is_unique_name:
18313 * @string: The string to check.
18315 * Checks if @string is a valid D-Bus unique bus name.
18317 * Returns: %TRUE if valid, %FALSE otherwise.
18323 * g_dbus_menu_model_get:
18324 * @connection: a #GDBusConnection
18325 * @bus_name: the bus name which exports the menu model
18326 * @object_path: the object path at which the menu model is exported
18328 * Obtains a #GDBusMenuModel for the menu model which is exported
18329 * at the given @bus_name and @object_path.
18331 * The thread default main context is taken at the time of this call.
18332 * All signals on the menu model (and any linked models) are reported
18333 * with respect to this context. All calls on the returned menu model
18334 * (and linked models) must also originate from this same context, with
18335 * the thread default main context unchanged.
18337 * Returns: (transfer full): a #GDBusMenuModel object. Free with
18338 * g_object_unref().
18344 * g_dbus_message_bytes_needed:
18345 * @blob: (array length=blob_len) (element-type guint8): A blob represent a binary D-Bus message.
18346 * @blob_len: The length of @blob (must be at least 16).
18347 * @error: Return location for error or %NULL.
18349 * Utility function to calculate how many bytes are needed to
18350 * completely deserialize the D-Bus message stored at @blob.
18352 * Returns: Number of bytes needed or -1 if @error is set (e.g. if
18353 * @blob contains invalid data or not enough data is available to
18354 * determine the size).
18360 * g_dbus_message_copy:
18361 * @message: A #GDBusMessage.
18362 * @error: Return location for error or %NULL.
18364 * Copies @message. The copy is a deep copy and the returned
18365 * #GDBusMessage is completely identical except that it is guaranteed
18366 * to not be locked.
18368 * This operation can fail if e.g. @message contains file descriptors
18369 * and the per-process or system-wide open files limit is reached.
18371 * Returns: (transfer full): A new #GDBusMessage or %NULL if @error is set.
18372 * Free with g_object_unref().
18378 * g_dbus_message_get_arg0:
18379 * @message: A #GDBusMessage.
18381 * Convenience to get the first item in the body of @message.
18383 * Returns: The string item or %NULL if the first item in the body of
18384 * @message is not a string.
18390 * g_dbus_message_get_body:
18391 * @message: A #GDBusMessage.
18393 * Gets the body of a message.
18395 * Returns: (transfer none): A #GVariant or %NULL if the body is
18396 * empty. Do not free, it is owned by @message.
18402 * g_dbus_message_get_byte_order:
18403 * @message: A #GDBusMessage.
18405 * Gets the byte order of @message.
18407 * Returns: The byte order.
18412 * g_dbus_message_get_destination:
18413 * @message: A #GDBusMessage.
18415 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field.
18417 * Returns: The value.
18423 * g_dbus_message_get_error_name:
18424 * @message: A #GDBusMessage.
18426 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field.
18428 * Returns: The value.
18434 * g_dbus_message_get_flags:
18435 * @message: A #GDBusMessage.
18437 * Gets the flags for @message.
18439 * Returns: Flags that are set (typically values from the #GDBusMessageFlags enumeration bitwise ORed together).
18445 * g_dbus_message_get_header:
18446 * @message: A #GDBusMessage.
18447 * @header_field: A 8-bit unsigned integer (typically a value from the #GDBusMessageHeaderField enumeration)
18449 * Gets a header field on @message.
18451 * Returns: A #GVariant with the value if the header was found, %NULL
18452 * otherwise. Do not free, it is owned by @message.
18458 * g_dbus_message_get_header_fields:
18459 * @message: A #GDBusMessage.
18461 * Gets an array of all header fields on @message that are set.
18463 * Returns: (array zero-terminated=1): An array of header fields
18464 * terminated by %G_DBUS_MESSAGE_HEADER_FIELD_INVALID. Each element
18465 * is a #guchar. Free with g_free().
18471 * g_dbus_message_get_interface:
18472 * @message: A #GDBusMessage.
18474 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE header field.
18476 * Returns: The value.
18482 * g_dbus_message_get_locked:
18483 * @message: A #GDBusMessage.
18485 * Checks whether @message is locked. To monitor changes to this
18486 * value, conncet to the #GObject::notify signal to listen for changes
18487 * on the #GDBusMessage:locked property.
18489 * Returns: %TRUE if @message is locked, %FALSE otherwise.
18495 * g_dbus_message_get_member:
18496 * @message: A #GDBusMessage.
18498 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_MEMBER header field.
18500 * Returns: The value.
18506 * g_dbus_message_get_message_type:
18507 * @message: A #GDBusMessage.
18509 * Gets the type of @message.
18511 * Returns: A 8-bit unsigned integer (typically a value from the #GDBusMessageType enumeration).
18517 * g_dbus_message_get_num_unix_fds:
18518 * @message: A #GDBusMessage.
18520 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header field.
18522 * Returns: The value.
18528 * g_dbus_message_get_path:
18529 * @message: A #GDBusMessage.
18531 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_PATH header field.
18533 * Returns: The value.
18539 * g_dbus_message_get_reply_serial:
18540 * @message: A #GDBusMessage.
18542 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL header field.
18544 * Returns: The value.
18550 * g_dbus_message_get_sender:
18551 * @message: A #GDBusMessage.
18553 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_SENDER header field.
18555 * Returns: The value.
18561 * g_dbus_message_get_serial:
18562 * @message: A #GDBusMessage.
18564 * Gets the serial for @message.
18566 * Returns: A #guint32.
18572 * g_dbus_message_get_signature:
18573 * @message: A #GDBusMessage.
18575 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field.
18577 * Returns: The value.
18583 * g_dbus_message_get_unix_fd_list:
18584 * @message: A #GDBusMessage.
18586 * Gets the UNIX file descriptors associated with @message, if any.
18588 * This method is only available on UNIX.
18590 * Returns: (transfer none): A #GUnixFDList or %NULL if no file descriptors are
18591 * associated. Do not free, this object is owned by @message.
18597 * g_dbus_message_lock:
18598 * @message: A #GDBusMessage.
18600 * If @message is locked, does nothing. Otherwise locks the message.
18607 * g_dbus_message_new:
18609 * Creates a new empty #GDBusMessage.
18611 * Returns: A #GDBusMessage. Free with g_object_unref().
18617 * g_dbus_message_new_from_blob:
18618 * @blob: (array length=blob_len) (element-type guint8): A blob represent a binary D-Bus message.
18619 * @blob_len: The length of @blob.
18620 * @capabilities: A #GDBusCapabilityFlags describing what protocol features are supported.
18621 * @error: Return location for error or %NULL.
18623 * Creates a new #GDBusMessage from the data stored at @blob. The byte
18624 * order that the message was in can be retrieved using
18625 * g_dbus_message_get_byte_order().
18627 * Returns: A new #GDBusMessage or %NULL if @error is set. Free with
18628 * g_object_unref().
18634 * g_dbus_message_new_method_call:
18635 * @name: (allow-none): A valid D-Bus name or %NULL.
18636 * @path: A valid object path.
18637 * @interface_: (allow-none): A valid D-Bus interface name or %NULL.
18638 * @method: A valid method name.
18640 * Creates a new #GDBusMessage for a method call.
18642 * Returns: A #GDBusMessage. Free with g_object_unref().
18648 * g_dbus_message_new_method_error:
18649 * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to
18650 * create a reply message to.
18651 * @error_name: A valid D-Bus error name.
18652 * @error_message_format: The D-Bus error message in a printf() format.
18653 * @...: Arguments for @error_message_format.
18655 * Creates a new #GDBusMessage that is an error reply to @method_call_message.
18657 * Returns: (transfer full): A #GDBusMessage. Free with g_object_unref().
18663 * g_dbus_message_new_method_error_literal:
18664 * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to
18665 * create a reply message to.
18666 * @error_name: A valid D-Bus error name.
18667 * @error_message: The D-Bus error message.
18669 * Creates a new #GDBusMessage that is an error reply to @method_call_message.
18671 * Returns: (transfer full): A #GDBusMessage. Free with g_object_unref().
18677 * g_dbus_message_new_method_error_valist:
18678 * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to
18679 * create a reply message to.
18680 * @error_name: A valid D-Bus error name.
18681 * @error_message_format: The D-Bus error message in a printf() format.
18682 * @var_args: Arguments for @error_message_format.
18684 * Like g_dbus_message_new_method_error() but intended for language bindings.
18686 * Returns: (transfer full): A #GDBusMessage. Free with g_object_unref().
18692 * g_dbus_message_new_method_reply:
18693 * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to
18694 * create a reply message to.
18696 * Creates a new #GDBusMessage that is a reply to @method_call_message.
18698 * Returns: (transfer full): #GDBusMessage. Free with g_object_unref().
18704 * g_dbus_message_new_signal:
18705 * @path: A valid object path.
18706 * @interface_: A valid D-Bus interface name.
18707 * @signal: A valid signal name.
18709 * Creates a new #GDBusMessage for a signal emission.
18711 * Returns: A #GDBusMessage. Free with g_object_unref().
18717 * g_dbus_message_print: (type method-return)
18718 * @message: A #GDBusMessage.
18719 * @indent: Indentation level.
18721 * Produces a human-readable multi-line description of @message.
18723 * The contents of the description has no ABI guarantees, the contents
18724 * and formatting is subject to change at any time. Typical output
18725 * looks something like this:
18731 * path -> objectpath '/org/gtk/GDBus/TestObject'
18732 * interface -> 'org.gtk.GDBus.TestInterface'
18733 * member -> 'GimmeStdout'
18734 * destination -> ':1.146'
18736 * UNIX File Descriptors:
18741 * Flags: no-reply-expected
18745 * reply-serial -> uint32 4
18746 * destination -> ':1.159'
18747 * sender -> ':1.146'
18748 * num-unix-fds -> uint32 1
18750 * UNIX File Descriptors:
18751 * fd 12: dev=0:10,mode=020620,ino=5,uid=500,gid=5,rdev=136:2,size=0,atime=1273085037,mtime=1273085851,ctime=1272982635
18754 * Returns: A string that should be freed with g_free().
18760 * g_dbus_message_set_body:
18761 * @message: A #GDBusMessage.
18762 * @body: Either %NULL or a #GVariant that is a tuple.
18764 * Sets the body @message. As a side-effect the
18765 * %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field is set to the
18766 * type string of @body (or cleared if @body is %NULL).
18768 * If @body is floating, @message assumes ownership of @body.
18775 * g_dbus_message_set_byte_order:
18776 * @message: A #GDBusMessage.
18777 * @byte_order: The byte order.
18779 * Sets the byte order of @message.
18784 * g_dbus_message_set_destination:
18785 * @message: A #GDBusMessage.
18786 * @value: The value to set.
18788 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field.
18795 * g_dbus_message_set_error_name:
18796 * @message: A #GDBusMessage.
18797 * @value: The value to set.
18799 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field.
18806 * g_dbus_message_set_flags:
18807 * @message: A #GDBusMessage.
18808 * @flags: Flags for @message that are set (typically values from the #GDBusMessageFlags
18809 * enumeration bitwise ORed together).
18811 * Sets the flags to set on @message.
18818 * g_dbus_message_set_header:
18819 * @message: A #GDBusMessage.
18820 * @header_field: A 8-bit unsigned integer (typically a value from the #GDBusMessageHeaderField enumeration)
18821 * @value: (allow-none): A #GVariant to set the header field or %NULL to clear the header field.
18823 * Sets a header field on @message.
18825 * If @value is floating, @message assumes ownership of @value.
18832 * g_dbus_message_set_interface:
18833 * @message: A #GDBusMessage.
18834 * @value: The value to set.
18836 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE header field.
18843 * g_dbus_message_set_member:
18844 * @message: A #GDBusMessage.
18845 * @value: The value to set.
18847 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_MEMBER header field.
18854 * g_dbus_message_set_message_type:
18855 * @message: A #GDBusMessage.
18856 * @type: A 8-bit unsigned integer (typically a value from the #GDBusMessageType enumeration).
18858 * Sets @message to be of @type.
18865 * g_dbus_message_set_num_unix_fds:
18866 * @message: A #GDBusMessage.
18867 * @value: The value to set.
18869 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header field.
18876 * g_dbus_message_set_path:
18877 * @message: A #GDBusMessage.
18878 * @value: The value to set.
18880 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_PATH header field.
18887 * g_dbus_message_set_reply_serial:
18888 * @message: A #GDBusMessage.
18889 * @value: The value to set.
18891 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL header field.
18898 * g_dbus_message_set_sender:
18899 * @message: A #GDBusMessage.
18900 * @value: The value to set.
18902 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_SENDER header field.
18909 * g_dbus_message_set_serial:
18910 * @message: A #GDBusMessage.
18911 * @serial: A #guint32.
18913 * Sets the serial for @message.
18920 * g_dbus_message_set_signature:
18921 * @message: A #GDBusMessage.
18922 * @value: The value to set.
18924 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field.
18931 * g_dbus_message_set_unix_fd_list:
18932 * @message: A #GDBusMessage.
18933 * @fd_list: (allow-none): A #GUnixFDList or %NULL.
18935 * Sets the UNIX file descriptors associated with @message. As a
18936 * side-effect the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header
18937 * field is set to the number of fds in @fd_list (or cleared if
18938 * @fd_list is %NULL).
18940 * This method is only available on UNIX.
18947 * g_dbus_message_to_blob:
18948 * @message: A #GDBusMessage.
18949 * @out_size: Return location for size of generated blob.
18950 * @capabilities: A #GDBusCapabilityFlags describing what protocol features are supported.
18951 * @error: Return location for error.
18953 * Serializes @message to a blob. The byte order returned by
18954 * g_dbus_message_get_byte_order() will be used.
18956 * Returns: (array length=out_size) (transfer full): A pointer to a
18957 * valid binary D-Bus message of @out_size bytes generated by @message
18958 * or %NULL if @error is set. Free with g_free().
18964 * g_dbus_message_to_gerror:
18965 * @message: A #GDBusMessage.
18966 * @error: The #GError to set.
18968 * If @message is not of type %G_DBUS_MESSAGE_TYPE_ERROR does
18969 * nothing and returns %FALSE.
18971 * Otherwise this method encodes the error in @message as a #GError
18972 * using g_dbus_error_set_dbus_error() using the information in the
18973 * %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field of @message as
18974 * well as the first string item in @message's body.
18976 * Returns: %TRUE if @error was set, %FALSE otherwise.
18982 * g_dbus_method_info_ref:
18983 * @info: A #GDBusMethodInfo
18985 * If @info is statically allocated does nothing. Otherwise increases
18986 * the reference count.
18988 * Returns: The same @info.
18994 * g_dbus_method_info_unref:
18995 * @info: A #GDBusMethodInfo.
18997 * If @info is statically allocated, does nothing. Otherwise decreases
18998 * the reference count of @info. When its reference count drops to 0,
18999 * the memory used is freed.
19006 * g_dbus_method_invocation_get_connection:
19007 * @invocation: A #GDBusMethodInvocation.
19009 * Gets the #GDBusConnection the method was invoked on.
19011 * Returns: (transfer none): A #GDBusConnection. Do not free, it is owned by @invocation.
19017 * g_dbus_method_invocation_get_interface_name:
19018 * @invocation: A #GDBusMethodInvocation.
19020 * Gets the name of the D-Bus interface the method was invoked on.
19022 * If this method call is a property Get, Set or GetAll call that has
19023 * been redirected to the method call handler then
19024 * "org.freedesktop.DBus.Properties" will be returned. See
19025 * #GDBusInterfaceVTable for more information.
19027 * Returns: A string. Do not free, it is owned by @invocation.
19033 * g_dbus_method_invocation_get_message:
19034 * @invocation: A #GDBusMethodInvocation.
19036 * Gets the #GDBusMessage for the method invocation. This is useful if
19037 * you need to use low-level protocol features, such as UNIX file
19038 * descriptor passing, that cannot be properly expressed in the
19041 * See this [server][gdbus-server] and [client][gdbus-unix-fd-client]
19042 * for an example of how to use this low-level API to send and receive
19043 * UNIX file descriptors.
19045 * Returns: (transfer none): #GDBusMessage. Do not free, it is owned by @invocation.
19051 * g_dbus_method_invocation_get_method_info:
19052 * @invocation: A #GDBusMethodInvocation.
19054 * Gets information about the method call, if any.
19056 * If this method invocation is a property Get, Set or GetAll call that
19057 * has been redirected to the method call handler then %NULL will be
19058 * returned. See g_dbus_method_invocation_get_property_info() and
19059 * #GDBusInterfaceVTable for more information.
19061 * Returns: A #GDBusMethodInfo or %NULL. Do not free, it is owned by @invocation.
19067 * g_dbus_method_invocation_get_method_name:
19068 * @invocation: A #GDBusMethodInvocation.
19070 * Gets the name of the method that was invoked.
19072 * Returns: A string. Do not free, it is owned by @invocation.
19078 * g_dbus_method_invocation_get_object_path:
19079 * @invocation: A #GDBusMethodInvocation.
19081 * Gets the object path the method was invoked on.
19083 * Returns: A string. Do not free, it is owned by @invocation.
19089 * g_dbus_method_invocation_get_parameters:
19090 * @invocation: A #GDBusMethodInvocation.
19092 * Gets the parameters of the method invocation. If there are no input
19093 * parameters then this will return a GVariant with 0 children rather than NULL.
19095 * Returns: (transfer none): A #GVariant tuple. Do not unref this because it is owned by @invocation.
19101 * g_dbus_method_invocation_get_property_info:
19102 * @invocation: A #GDBusMethodInvocation
19104 * Gets information about the property that this method call is for, if
19107 * This will only be set in the case of an invocation in response to a
19108 * property Get or Set call that has been directed to the method call
19109 * handler for an object on account of its property_get() or
19110 * property_set() vtable pointers being unset.
19112 * See #GDBusInterfaceVTable for more information.
19114 * If the call was GetAll, %NULL will be returned.
19116 * Returns: (transfer none): a #GDBusPropertyInfo or %NULL
19122 * g_dbus_method_invocation_get_sender:
19123 * @invocation: A #GDBusMethodInvocation.
19125 * Gets the bus name that invoked the method.
19127 * Returns: A string. Do not free, it is owned by @invocation.
19133 * g_dbus_method_invocation_get_user_data: (skip)
19134 * @invocation: A #GDBusMethodInvocation.
19136 * Gets the @user_data #gpointer passed to g_dbus_connection_register_object().
19138 * Returns: A #gpointer.
19144 * g_dbus_method_invocation_return_dbus_error:
19145 * @invocation: (transfer full): A #GDBusMethodInvocation.
19146 * @error_name: A valid D-Bus error name.
19147 * @error_message: A valid D-Bus error message.
19149 * Finishes handling a D-Bus method call by returning an error.
19151 * This method will free @invocation, you cannot use it afterwards.
19158 * g_dbus_method_invocation_return_error:
19159 * @invocation: (transfer full): A #GDBusMethodInvocation.
19160 * @domain: A #GQuark for the #GError error domain.
19161 * @code: The error code.
19162 * @format: printf()-style format.
19163 * @...: Parameters for @format.
19165 * Finishes handling a D-Bus method call by returning an error.
19167 * See g_dbus_error_encode_gerror() for details about what error name
19168 * will be returned on the wire. In a nutshell, if the given error is
19169 * registered using g_dbus_error_register_error() the name given
19170 * during registration is used. Otherwise, a name of the form
19171 * `org.gtk.GDBus.UnmappedGError.Quark...` is used. This provides
19172 * transparent mapping of #GError between applications using GDBus.
19174 * If you are writing an application intended to be portable,
19175 * always register errors with g_dbus_error_register_error()
19176 * or use g_dbus_method_invocation_return_dbus_error().
19178 * This method will free @invocation, you cannot use it afterwards.
19180 * Since 2.48, if the method call requested for a reply not to be sent
19181 * then this call will free @invocation but otherwise do nothing (as per
19182 * the recommendations of the D-Bus specification).
19189 * g_dbus_method_invocation_return_error_literal:
19190 * @invocation: (transfer full): A #GDBusMethodInvocation.
19191 * @domain: A #GQuark for the #GError error domain.
19192 * @code: The error code.
19193 * @message: The error message.
19195 * Like g_dbus_method_invocation_return_error() but without printf()-style formatting.
19197 * This method will free @invocation, you cannot use it afterwards.
19204 * g_dbus_method_invocation_return_error_valist:
19205 * @invocation: (transfer full): A #GDBusMethodInvocation.
19206 * @domain: A #GQuark for the #GError error domain.
19207 * @code: The error code.
19208 * @format: printf()-style format.
19209 * @var_args: #va_list of parameters for @format.
19211 * Like g_dbus_method_invocation_return_error() but intended for
19212 * language bindings.
19214 * This method will free @invocation, you cannot use it afterwards.
19221 * g_dbus_method_invocation_return_gerror:
19222 * @invocation: (transfer full): A #GDBusMethodInvocation.
19223 * @error: A #GError.
19225 * Like g_dbus_method_invocation_return_error() but takes a #GError
19226 * instead of the error domain, error code and message.
19228 * This method will free @invocation, you cannot use it afterwards.
19235 * g_dbus_method_invocation_return_value:
19236 * @invocation: (transfer full): A #GDBusMethodInvocation.
19237 * @parameters: (allow-none): A #GVariant tuple with out parameters for the method or %NULL if not passing any parameters.
19239 * Finishes handling a D-Bus method call by returning @parameters.
19240 * If the @parameters GVariant is floating, it is consumed.
19242 * It is an error if @parameters is not of the right format.
19244 * This method will free @invocation, you cannot use it afterwards.
19246 * Since 2.48, if the method call requested for a reply not to be sent
19247 * then this call will sink @parameters and free @invocation, but
19248 * otherwise do nothing (as per the recommendations of the D-Bus
19256 * g_dbus_method_invocation_return_value_with_unix_fd_list:
19257 * @invocation: (transfer full): A #GDBusMethodInvocation.
19258 * @parameters: (allow-none): A #GVariant tuple with out parameters for the method or %NULL if not passing any parameters.
19259 * @fd_list: (allow-none): A #GUnixFDList or %NULL.
19261 * Like g_dbus_method_invocation_return_value() but also takes a #GUnixFDList.
19263 * This method is only available on UNIX.
19265 * This method will free @invocation, you cannot use it afterwards.
19272 * g_dbus_method_invocation_take_error: (skip)
19273 * @invocation: (transfer full): A #GDBusMethodInvocation.
19274 * @error: (transfer full): A #GError.
19276 * Like g_dbus_method_invocation_return_gerror() but takes ownership
19277 * of @error so the caller does not need to free it.
19279 * This method will free @invocation, you cannot use it afterwards.
19286 * g_dbus_node_info_generate_xml:
19287 * @info: A #GDBusNodeInfo.
19288 * @indent: Indentation level.
19289 * @string_builder: (out): A #GString to to append XML data to.
19291 * Appends an XML representation of @info (and its children) to @string_builder.
19293 * This function is typically used for generating introspection XML documents at run-time for
19294 * handling the `org.freedesktop.DBus.Introspectable.Introspect` method.
19301 * g_dbus_node_info_lookup_interface:
19302 * @info: A #GDBusNodeInfo.
19303 * @name: A D-Bus interface name.
19305 * Looks up information about an interface.
19307 * The cost of this function is O(n) in number of interfaces.
19309 * Returns: (transfer none): A #GDBusInterfaceInfo or %NULL if not found. Do not free, it is owned by @info.
19315 * g_dbus_node_info_new_for_xml:
19316 * @xml_data: Valid D-Bus introspection XML.
19317 * @error: Return location for error.
19319 * Parses @xml_data and returns a #GDBusNodeInfo representing the data.
19321 * The introspection XML must contain exactly one top-level
19324 * Note that this routine is using a
19325 * [GMarkup][glib-Simple-XML-Subset-Parser.description]-based
19326 * parser that only accepts a subset of valid XML documents.
19328 * Returns: A #GDBusNodeInfo structure or %NULL if @error is set. Free
19329 * with g_dbus_node_info_unref().
19335 * g_dbus_node_info_ref:
19336 * @info: A #GDBusNodeInfo
19338 * If @info is statically allocated does nothing. Otherwise increases
19339 * the reference count.
19341 * Returns: The same @info.
19347 * g_dbus_node_info_unref:
19348 * @info: A #GDBusNodeInfo.
19350 * If @info is statically allocated, does nothing. Otherwise decreases
19351 * the reference count of @info. When its reference count drops to 0,
19352 * the memory used is freed.
19359 * g_dbus_object_get_interface:
19360 * @object: A #GDBusObject.
19361 * @interface_name: A D-Bus interface name.
19363 * Gets the D-Bus interface with name @interface_name associated with
19366 * Returns: (transfer full): %NULL if not found, otherwise a
19367 * #GDBusInterface that must be freed with g_object_unref().
19373 * g_dbus_object_get_interfaces:
19374 * @object: A #GDBusObject.
19376 * Gets the D-Bus interfaces associated with @object.
19378 * Returns: (element-type GDBusInterface) (transfer full): A list of #GDBusInterface instances.
19379 * The returned list must be freed by g_list_free() after each element has been freed
19380 * with g_object_unref().
19386 * g_dbus_object_get_object_path:
19387 * @object: A #GDBusObject.
19389 * Gets the object path for @object.
19391 * Returns: A string owned by @object. Do not free.
19397 * g_dbus_object_manager_client_get_connection:
19398 * @manager: A #GDBusObjectManagerClient
19400 * Gets the #GDBusConnection used by @manager.
19402 * Returns: (transfer none): A #GDBusConnection object. Do not free,
19403 * the object belongs to @manager.
19409 * g_dbus_object_manager_client_get_flags:
19410 * @manager: A #GDBusObjectManagerClient
19412 * Gets the flags that @manager was constructed with.
19414 * Returns: Zero of more flags from the #GDBusObjectManagerClientFlags
19421 * g_dbus_object_manager_client_get_name:
19422 * @manager: A #GDBusObjectManagerClient
19424 * Gets the name that @manager is for, or %NULL if not a message bus
19427 * Returns: A unique or well-known name. Do not free, the string
19428 * belongs to @manager.
19434 * g_dbus_object_manager_client_get_name_owner:
19435 * @manager: A #GDBusObjectManagerClient.
19437 * The unique name that owns the name that @manager is for or %NULL if
19438 * no-one currently owns that name. You can connect to the
19439 * #GObject::notify signal to track changes to the
19440 * #GDBusObjectManagerClient:name-owner property.
19442 * Returns: (nullable): The name owner or %NULL if no name owner
19443 * exists. Free with g_free().
19449 * g_dbus_object_manager_client_new:
19450 * @connection: A #GDBusConnection.
19451 * @flags: Zero or more flags from the #GDBusObjectManagerClientFlags enumeration.
19452 * @name: The owner of the control object (unique or well-known name).
19453 * @object_path: The object path of the control object.
19454 * @get_proxy_type_func: (allow-none): A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies.
19455 * @get_proxy_type_user_data: User data to pass to @get_proxy_type_func.
19456 * @get_proxy_type_destroy_notify: (allow-none): Free function for @get_proxy_type_user_data or %NULL.
19457 * @cancellable: (allow-none): A #GCancellable or %NULL
19458 * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
19459 * @user_data: The data to pass to @callback.
19461 * Asynchronously creates a new #GDBusObjectManagerClient object.
19463 * This is an asynchronous failable constructor. When the result is
19464 * ready, @callback will be invoked in the
19465 * [thread-default main context][g-main-context-push-thread-default]
19466 * of the thread you are calling this method from. You can
19467 * then call g_dbus_object_manager_client_new_finish() to get the result. See
19468 * g_dbus_object_manager_client_new_sync() for the synchronous version.
19475 * g_dbus_object_manager_client_new_finish:
19476 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_object_manager_client_new().
19477 * @error: Return location for error or %NULL.
19479 * Finishes an operation started with g_dbus_object_manager_client_new().
19481 * Returns: (transfer full) (type GDBusObjectManagerClient): A
19482 * #GDBusObjectManagerClient object or %NULL if @error is set. Free
19483 * with g_object_unref().
19489 * g_dbus_object_manager_client_new_for_bus:
19490 * @bus_type: A #GBusType.
19491 * @flags: Zero or more flags from the #GDBusObjectManagerClientFlags enumeration.
19492 * @name: The owner of the control object (unique or well-known name).
19493 * @object_path: The object path of the control object.
19494 * @get_proxy_type_func: (allow-none): A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies.
19495 * @get_proxy_type_user_data: User data to pass to @get_proxy_type_func.
19496 * @get_proxy_type_destroy_notify: (allow-none): Free function for @get_proxy_type_user_data or %NULL.
19497 * @cancellable: (allow-none): A #GCancellable or %NULL
19498 * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
19499 * @user_data: The data to pass to @callback.
19501 * Like g_dbus_object_manager_client_new() but takes a #GBusType instead of a
19502 * #GDBusConnection.
19504 * This is an asynchronous failable constructor. When the result is
19505 * ready, @callback will be invoked in the
19506 * [thread-default main loop][g-main-context-push-thread-default]
19507 * of the thread you are calling this method from. You can
19508 * then call g_dbus_object_manager_client_new_for_bus_finish() to get the result. See
19509 * g_dbus_object_manager_client_new_for_bus_sync() for the synchronous version.
19516 * g_dbus_object_manager_client_new_for_bus_finish:
19517 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_object_manager_client_new_for_bus().
19518 * @error: Return location for error or %NULL.
19520 * Finishes an operation started with g_dbus_object_manager_client_new_for_bus().
19522 * Returns: (transfer full) (type GDBusObjectManagerClient): A
19523 * #GDBusObjectManagerClient object or %NULL if @error is set. Free
19524 * with g_object_unref().
19530 * g_dbus_object_manager_client_new_for_bus_sync:
19531 * @bus_type: A #GBusType.
19532 * @flags: Zero or more flags from the #GDBusObjectManagerClientFlags enumeration.
19533 * @name: The owner of the control object (unique or well-known name).
19534 * @object_path: The object path of the control object.
19535 * @get_proxy_type_func: (allow-none): A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies.
19536 * @get_proxy_type_user_data: User data to pass to @get_proxy_type_func.
19537 * @get_proxy_type_destroy_notify: (allow-none): Free function for @get_proxy_type_user_data or %NULL.
19538 * @cancellable: (allow-none): A #GCancellable or %NULL
19539 * @error: Return location for error or %NULL.
19541 * Like g_dbus_object_manager_client_new_sync() but takes a #GBusType instead
19542 * of a #GDBusConnection.
19544 * This is a synchronous failable constructor - the calling thread is
19545 * blocked until a reply is received. See g_dbus_object_manager_client_new_for_bus()
19546 * for the asynchronous version.
19548 * Returns: (transfer full) (type GDBusObjectManagerClient): A
19549 * #GDBusObjectManagerClient object or %NULL if @error is set. Free
19550 * with g_object_unref().
19556 * g_dbus_object_manager_client_new_sync:
19557 * @connection: A #GDBusConnection.
19558 * @flags: Zero or more flags from the #GDBusObjectManagerClientFlags enumeration.
19559 * @name: (allow-none): The owner of the control object (unique or well-known name), or %NULL when not using a message bus connection.
19560 * @object_path: The object path of the control object.
19561 * @get_proxy_type_func: (allow-none): A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies.
19562 * @get_proxy_type_user_data: User data to pass to @get_proxy_type_func.
19563 * @get_proxy_type_destroy_notify: (allow-none): Free function for @get_proxy_type_user_data or %NULL.
19564 * @cancellable: (allow-none): A #GCancellable or %NULL
19565 * @error: Return location for error or %NULL.
19567 * Creates a new #GDBusObjectManagerClient object.
19569 * This is a synchronous failable constructor - the calling thread is
19570 * blocked until a reply is received. See g_dbus_object_manager_client_new()
19571 * for the asynchronous version.
19573 * Returns: (transfer full) (type GDBusObjectManagerClient): A
19574 * #GDBusObjectManagerClient object or %NULL if @error is set. Free
19575 * with g_object_unref().
19581 * g_dbus_object_manager_get_interface:
19582 * @manager: A #GDBusObjectManager.
19583 * @object_path: Object path to lookup.
19584 * @interface_name: D-Bus interface name to lookup.
19586 * Gets the interface proxy for @interface_name at @object_path, if
19589 * Returns: (transfer full): A #GDBusInterface instance or %NULL. Free
19590 * with g_object_unref().
19596 * g_dbus_object_manager_get_object:
19597 * @manager: A #GDBusObjectManager.
19598 * @object_path: Object path to lookup.
19600 * Gets the #GDBusObjectProxy at @object_path, if any.
19602 * Returns: (transfer full): A #GDBusObject or %NULL. Free with
19603 * g_object_unref().
19609 * g_dbus_object_manager_get_object_path:
19610 * @manager: A #GDBusObjectManager.
19612 * Gets the object path that @manager is for.
19614 * Returns: A string owned by @manager. Do not free.
19620 * g_dbus_object_manager_get_objects:
19621 * @manager: A #GDBusObjectManager.
19623 * Gets all #GDBusObject objects known to @manager.
19625 * Returns: (transfer full) (element-type GDBusObject): A list of
19626 * #GDBusObject objects. The returned list should be freed with
19627 * g_list_free() after each element has been freed with
19628 * g_object_unref().
19634 * g_dbus_object_manager_server_export:
19635 * @manager: A #GDBusObjectManagerServer.
19636 * @object: A #GDBusObjectSkeleton.
19638 * Exports @object on @manager.
19640 * If there is already a #GDBusObject exported at the object path,
19641 * then the old object is removed.
19643 * The object path for @object must be in the hierarchy rooted by the
19644 * object path for @manager.
19646 * Note that @manager will take a reference on @object for as long as
19654 * g_dbus_object_manager_server_export_uniquely:
19655 * @manager: A #GDBusObjectManagerServer.
19656 * @object: An object.
19658 * Like g_dbus_object_manager_server_export() but appends a string of
19659 * the form _N (with N being a natural number) to @object's object path
19660 * if an object with the given path already exists. As such, the
19661 * #GDBusObjectProxy:g-object-path property of @object may be modified.
19668 * g_dbus_object_manager_server_get_connection:
19669 * @manager: A #GDBusObjectManagerServer
19671 * Gets the #GDBusConnection used by @manager.
19673 * Returns: (transfer full): A #GDBusConnection object or %NULL if
19674 * @manager isn't exported on a connection. The returned object should
19675 * be freed with g_object_unref().
19681 * g_dbus_object_manager_server_is_exported:
19682 * @manager: A #GDBusObjectManagerServer.
19683 * @object: An object.
19685 * Returns whether @object is currently exported on @manager.
19687 * Returns: %TRUE if @object is exported
19693 * g_dbus_object_manager_server_new:
19694 * @object_path: The object path to export the manager object at.
19696 * Creates a new #GDBusObjectManagerServer object.
19698 * The returned server isn't yet exported on any connection. To do so,
19699 * use g_dbus_object_manager_server_set_connection(). Normally you
19700 * want to export all of your objects before doing so to avoid
19701 * [InterfacesAdded](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager)
19702 * signals being emitted.
19704 * Returns: A #GDBusObjectManagerServer object. Free with g_object_unref().
19710 * g_dbus_object_manager_server_set_connection:
19711 * @manager: A #GDBusObjectManagerServer.
19712 * @connection: (allow-none): A #GDBusConnection or %NULL.
19714 * Exports all objects managed by @manager on @connection. If
19715 * @connection is %NULL, stops exporting objects.
19720 * g_dbus_object_manager_server_unexport:
19721 * @manager: A #GDBusObjectManagerServer.
19722 * @object_path: An object path.
19724 * If @manager has an object at @path, removes the object. Otherwise
19727 * Note that @object_path must be in the hierarchy rooted by the
19728 * object path for @manager.
19730 * Returns: %TRUE if object at @object_path was removed, %FALSE otherwise.
19736 * g_dbus_object_proxy_get_connection:
19737 * @proxy: a #GDBusObjectProxy
19739 * Gets the connection that @proxy is for.
19741 * Returns: (transfer none): A #GDBusConnection. Do not free, the
19742 * object is owned by @proxy.
19748 * g_dbus_object_proxy_new:
19749 * @connection: a #GDBusConnection
19750 * @object_path: the object path
19752 * Creates a new #GDBusObjectProxy for the given connection and
19755 * Returns: a new #GDBusObjectProxy
19761 * g_dbus_object_skeleton_add_interface:
19762 * @object: A #GDBusObjectSkeleton.
19763 * @interface_: A #GDBusInterfaceSkeleton.
19765 * Adds @interface_ to @object.
19767 * If @object already contains a #GDBusInterfaceSkeleton with the same
19768 * interface name, it is removed before @interface_ is added.
19770 * Note that @object takes its own reference on @interface_ and holds
19771 * it until removed.
19778 * g_dbus_object_skeleton_flush:
19779 * @object: A #GDBusObjectSkeleton.
19781 * This method simply calls g_dbus_interface_skeleton_flush() on all
19782 * interfaces belonging to @object. See that method for when flushing
19790 * g_dbus_object_skeleton_new:
19791 * @object_path: An object path.
19793 * Creates a new #GDBusObjectSkeleton.
19795 * Returns: A #GDBusObjectSkeleton. Free with g_object_unref().
19801 * g_dbus_object_skeleton_remove_interface:
19802 * @object: A #GDBusObjectSkeleton.
19803 * @interface_: A #GDBusInterfaceSkeleton.
19805 * Removes @interface_ from @object.
19812 * g_dbus_object_skeleton_remove_interface_by_name:
19813 * @object: A #GDBusObjectSkeleton.
19814 * @interface_name: A D-Bus interface name.
19816 * Removes the #GDBusInterface with @interface_name from @object.
19818 * If no D-Bus interface of the given interface exists, this function
19826 * g_dbus_object_skeleton_set_object_path:
19827 * @object: A #GDBusObjectSkeleton.
19828 * @object_path: A valid D-Bus object path.
19830 * Sets the object path for @object.
19837 * g_dbus_property_info_ref:
19838 * @info: A #GDBusPropertyInfo
19840 * If @info is statically allocated does nothing. Otherwise increases
19841 * the reference count.
19843 * Returns: The same @info.
19849 * g_dbus_property_info_unref:
19850 * @info: A #GDBusPropertyInfo.
19852 * If @info is statically allocated, does nothing. Otherwise decreases
19853 * the reference count of @info. When its reference count drops to 0,
19854 * the memory used is freed.
19861 * g_dbus_proxy_call:
19862 * @proxy: A #GDBusProxy.
19863 * @method_name: Name of method to invoke.
19864 * @parameters: (allow-none): A #GVariant tuple with parameters for the signal or %NULL if not passing parameters.
19865 * @flags: Flags from the #GDBusCallFlags enumeration.
19866 * @timeout_msec: The timeout in milliseconds (with %G_MAXINT meaning
19867 * "infinite") or -1 to use the proxy default timeout.
19868 * @cancellable: (allow-none): A #GCancellable or %NULL.
19869 * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't
19870 * care about the result of the method invocation.
19871 * @user_data: The data to pass to @callback.
19873 * Asynchronously invokes the @method_name method on @proxy.
19875 * If @method_name contains any dots, then @name is split into interface and
19876 * method name parts. This allows using @proxy for invoking methods on
19877 * other interfaces.
19879 * If the #GDBusConnection associated with @proxy is closed then
19880 * the operation will fail with %G_IO_ERROR_CLOSED. If
19881 * @cancellable is canceled, the operation will fail with
19882 * %G_IO_ERROR_CANCELLED. If @parameters contains a value not
19883 * compatible with the D-Bus protocol, the operation fails with
19884 * %G_IO_ERROR_INVALID_ARGUMENT.
19886 * If the @parameters #GVariant is floating, it is consumed. This allows
19887 * convenient 'inline' use of g_variant_new(), e.g.:
19888 * |[<!-- language="C" -->
19889 * g_dbus_proxy_call (proxy,
19891 * g_variant_new ("(ss)",
19894 * G_DBUS_CALL_FLAGS_NONE,
19897 * (GAsyncReadyCallback) two_strings_done,
19901 * If @proxy has an expected interface (see
19902 * #GDBusProxy:g-interface-info) and @method_name is referenced by it,
19903 * then the return value is checked against the return type.
19905 * This is an asynchronous method. When the operation is finished,
19906 * @callback will be invoked in the
19907 * [thread-default main context][g-main-context-push-thread-default]
19908 * of the thread you are calling this method from.
19909 * You can then call g_dbus_proxy_call_finish() to get the result of
19910 * the operation. See g_dbus_proxy_call_sync() for the synchronous
19911 * version of this method.
19913 * If @callback is %NULL then the D-Bus method call message will be sent with
19914 * the %G_DBUS_MESSAGE_FLAGS_NO_REPLY_EXPECTED flag set.
19921 * g_dbus_proxy_call_finish:
19922 * @proxy: A #GDBusProxy.
19923 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_proxy_call().
19924 * @error: Return location for error or %NULL.
19926 * Finishes an operation started with g_dbus_proxy_call().
19928 * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
19929 * return values. Free with g_variant_unref().
19935 * g_dbus_proxy_call_sync:
19936 * @proxy: A #GDBusProxy.
19937 * @method_name: Name of method to invoke.
19938 * @parameters: (allow-none): A #GVariant tuple with parameters for the signal
19939 * or %NULL if not passing parameters.
19940 * @flags: Flags from the #GDBusCallFlags enumeration.
19941 * @timeout_msec: The timeout in milliseconds (with %G_MAXINT meaning
19942 * "infinite") or -1 to use the proxy default timeout.
19943 * @cancellable: (allow-none): A #GCancellable or %NULL.
19944 * @error: Return location for error or %NULL.
19946 * Synchronously invokes the @method_name method on @proxy.
19948 * If @method_name contains any dots, then @name is split into interface and
19949 * method name parts. This allows using @proxy for invoking methods on
19950 * other interfaces.
19952 * If the #GDBusConnection associated with @proxy is disconnected then
19953 * the operation will fail with %G_IO_ERROR_CLOSED. If
19954 * @cancellable is canceled, the operation will fail with
19955 * %G_IO_ERROR_CANCELLED. If @parameters contains a value not
19956 * compatible with the D-Bus protocol, the operation fails with
19957 * %G_IO_ERROR_INVALID_ARGUMENT.
19959 * If the @parameters #GVariant is floating, it is consumed. This allows
19960 * convenient 'inline' use of g_variant_new(), e.g.:
19961 * |[<!-- language="C" -->
19962 * g_dbus_proxy_call_sync (proxy,
19964 * g_variant_new ("(ss)",
19967 * G_DBUS_CALL_FLAGS_NONE,
19973 * The calling thread is blocked until a reply is received. See
19974 * g_dbus_proxy_call() for the asynchronous version of this
19977 * If @proxy has an expected interface (see
19978 * #GDBusProxy:g-interface-info) and @method_name is referenced by it,
19979 * then the return value is checked against the return type.
19981 * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
19982 * return values. Free with g_variant_unref().
19988 * g_dbus_proxy_call_with_unix_fd_list:
19989 * @proxy: A #GDBusProxy.
19990 * @method_name: Name of method to invoke.
19991 * @parameters: (allow-none): A #GVariant tuple with parameters for the signal or %NULL if not passing parameters.
19992 * @flags: Flags from the #GDBusCallFlags enumeration.
19993 * @timeout_msec: The timeout in milliseconds (with %G_MAXINT meaning
19994 * "infinite") or -1 to use the proxy default timeout.
19995 * @fd_list: (allow-none): A #GUnixFDList or %NULL.
19996 * @cancellable: (allow-none): A #GCancellable or %NULL.
19997 * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't
19998 * care about the result of the method invocation.
19999 * @user_data: The data to pass to @callback.
20001 * Like g_dbus_proxy_call() but also takes a #GUnixFDList object.
20003 * This method is only available on UNIX.
20010 * g_dbus_proxy_call_with_unix_fd_list_finish:
20011 * @proxy: A #GDBusProxy.
20012 * @out_fd_list: (out) (allow-none): Return location for a #GUnixFDList or %NULL.
20013 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_proxy_call_with_unix_fd_list().
20014 * @error: Return location for error or %NULL.
20016 * Finishes an operation started with g_dbus_proxy_call_with_unix_fd_list().
20018 * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
20019 * return values. Free with g_variant_unref().
20025 * g_dbus_proxy_call_with_unix_fd_list_sync:
20026 * @proxy: A #GDBusProxy.
20027 * @method_name: Name of method to invoke.
20028 * @parameters: (allow-none): A #GVariant tuple with parameters for the signal
20029 * or %NULL if not passing parameters.
20030 * @flags: Flags from the #GDBusCallFlags enumeration.
20031 * @timeout_msec: The timeout in milliseconds (with %G_MAXINT meaning
20032 * "infinite") or -1 to use the proxy default timeout.
20033 * @fd_list: (allow-none): A #GUnixFDList or %NULL.
20034 * @out_fd_list: (out) (allow-none): Return location for a #GUnixFDList or %NULL.
20035 * @cancellable: (allow-none): A #GCancellable or %NULL.
20036 * @error: Return location for error or %NULL.
20038 * Like g_dbus_proxy_call_sync() but also takes and returns #GUnixFDList objects.
20040 * This method is only available on UNIX.
20042 * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
20043 * return values. Free with g_variant_unref().
20049 * g_dbus_proxy_get_cached_property:
20050 * @proxy: A #GDBusProxy.
20051 * @property_name: Property name.
20053 * Looks up the value for a property from the cache. This call does no
20056 * If @proxy has an expected interface (see
20057 * #GDBusProxy:g-interface-info) and @property_name is referenced by
20058 * it, then @value is checked against the type of the property.
20060 * Returns: A reference to the #GVariant instance that holds the value
20061 * for @property_name or %NULL if the value is not in the cache. The
20062 * returned reference must be freed with g_variant_unref().
20068 * g_dbus_proxy_get_cached_property_names:
20069 * @proxy: A #GDBusProxy.
20071 * Gets the names of all cached properties on @proxy.
20073 * Returns: (transfer full): A %NULL-terminated array of strings or %NULL if
20074 * @proxy has no cached properties. Free the returned array with
20081 * g_dbus_proxy_get_connection:
20082 * @proxy: A #GDBusProxy.
20084 * Gets the connection @proxy is for.
20086 * Returns: (transfer none): A #GDBusConnection owned by @proxy. Do not free.
20092 * g_dbus_proxy_get_default_timeout:
20093 * @proxy: A #GDBusProxy.
20095 * Gets the timeout to use if -1 (specifying default timeout) is
20096 * passed as @timeout_msec in the g_dbus_proxy_call() and
20097 * g_dbus_proxy_call_sync() functions.
20099 * See the #GDBusProxy:g-default-timeout property for more details.
20101 * Returns: Timeout to use for @proxy.
20107 * g_dbus_proxy_get_flags:
20108 * @proxy: A #GDBusProxy.
20110 * Gets the flags that @proxy was constructed with.
20112 * Returns: Flags from the #GDBusProxyFlags enumeration.
20118 * g_dbus_proxy_get_interface_info:
20119 * @proxy: A #GDBusProxy
20121 * Returns the #GDBusInterfaceInfo, if any, specifying the interface
20122 * that @proxy conforms to. See the #GDBusProxy:g-interface-info
20123 * property for more details.
20125 * Returns: A #GDBusInterfaceInfo or %NULL. Do not unref the returned
20126 * object, it is owned by @proxy.
20132 * g_dbus_proxy_get_interface_name:
20133 * @proxy: A #GDBusProxy.
20135 * Gets the D-Bus interface name @proxy is for.
20137 * Returns: A string owned by @proxy. Do not free.
20143 * g_dbus_proxy_get_name:
20144 * @proxy: A #GDBusProxy.
20146 * Gets the name that @proxy was constructed for.
20148 * Returns: A string owned by @proxy. Do not free.
20154 * g_dbus_proxy_get_name_owner:
20155 * @proxy: A #GDBusProxy.
20157 * The unique name that owns the name that @proxy is for or %NULL if
20158 * no-one currently owns that name. You may connect to the
20159 * #GObject::notify signal to track changes to the
20160 * #GDBusProxy:g-name-owner property.
20162 * Returns: The name owner or %NULL if no name owner exists. Free with g_free().
20168 * g_dbus_proxy_get_object_path:
20169 * @proxy: A #GDBusProxy.
20171 * Gets the object path @proxy is for.
20173 * Returns: A string owned by @proxy. Do not free.
20179 * g_dbus_proxy_new:
20180 * @connection: A #GDBusConnection.
20181 * @flags: Flags used when constructing the proxy.
20182 * @info: (allow-none): A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL.
20183 * @name: (allow-none): A bus name (well-known or unique) or %NULL if @connection is not a message bus connection.
20184 * @object_path: An object path.
20185 * @interface_name: A D-Bus interface name.
20186 * @cancellable: (allow-none): A #GCancellable or %NULL.
20187 * @callback: Callback function to invoke when the proxy is ready.
20188 * @user_data: User data to pass to @callback.
20190 * Creates a proxy for accessing @interface_name on the remote object
20191 * at @object_path owned by @name at @connection and asynchronously
20192 * loads D-Bus properties unless the
20193 * %G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES flag is used. Connect to
20194 * the #GDBusProxy::g-properties-changed signal to get notified about
20195 * property changes.
20197 * If the %G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS flag is not set, also sets up
20198 * match rules for signals. Connect to the #GDBusProxy::g-signal signal
20199 * to handle signals from the remote object.
20201 * If @name is a well-known name and the
20202 * %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START and %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START_AT_CONSTRUCTION
20203 * flags aren't set and no name owner currently exists, the message bus
20204 * will be requested to launch a name owner for the name.
20206 * This is a failable asynchronous constructor - when the proxy is
20207 * ready, @callback will be invoked and you can use
20208 * g_dbus_proxy_new_finish() to get the result.
20210 * See g_dbus_proxy_new_sync() and for a synchronous version of this constructor.
20212 * #GDBusProxy is used in this [example][gdbus-wellknown-proxy].
20219 * g_dbus_proxy_new_finish:
20220 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback function passed to g_dbus_proxy_new().
20221 * @error: Return location for error or %NULL.
20223 * Finishes creating a #GDBusProxy.
20225 * Returns: A #GDBusProxy or %NULL if @error is set. Free with g_object_unref().
20231 * g_dbus_proxy_new_for_bus:
20232 * @bus_type: A #GBusType.
20233 * @flags: Flags used when constructing the proxy.
20234 * @info: (allow-none): A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL.
20235 * @name: A bus name (well-known or unique).
20236 * @object_path: An object path.
20237 * @interface_name: A D-Bus interface name.
20238 * @cancellable: (allow-none): A #GCancellable or %NULL.
20239 * @callback: Callback function to invoke when the proxy is ready.
20240 * @user_data: User data to pass to @callback.
20242 * Like g_dbus_proxy_new() but takes a #GBusType instead of a #GDBusConnection.
20244 * #GDBusProxy is used in this [example][gdbus-wellknown-proxy].
20251 * g_dbus_proxy_new_for_bus_finish:
20252 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback function passed to g_dbus_proxy_new_for_bus().
20253 * @error: Return location for error or %NULL.
20255 * Finishes creating a #GDBusProxy.
20257 * Returns: A #GDBusProxy or %NULL if @error is set. Free with g_object_unref().
20263 * g_dbus_proxy_new_for_bus_sync:
20264 * @bus_type: A #GBusType.
20265 * @flags: Flags used when constructing the proxy.
20266 * @info: (allow-none): A #GDBusInterfaceInfo specifying the minimal interface
20267 * that @proxy conforms to or %NULL.
20268 * @name: A bus name (well-known or unique).
20269 * @object_path: An object path.
20270 * @interface_name: A D-Bus interface name.
20271 * @cancellable: (allow-none): A #GCancellable or %NULL.
20272 * @error: Return location for error or %NULL.
20274 * Like g_dbus_proxy_new_sync() but takes a #GBusType instead of a #GDBusConnection.
20276 * #GDBusProxy is used in this [example][gdbus-wellknown-proxy].
20278 * Returns: A #GDBusProxy or %NULL if error is set. Free with g_object_unref().
20284 * g_dbus_proxy_new_sync:
20285 * @connection: A #GDBusConnection.
20286 * @flags: Flags used when constructing the proxy.
20287 * @info: (allow-none): A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL.
20288 * @name: (allow-none): A bus name (well-known or unique) or %NULL if @connection is not a message bus connection.
20289 * @object_path: An object path.
20290 * @interface_name: A D-Bus interface name.
20291 * @cancellable: (allow-none): A #GCancellable or %NULL.
20292 * @error: (allow-none): Return location for error or %NULL.
20294 * Creates a proxy for accessing @interface_name on the remote object
20295 * at @object_path owned by @name at @connection and synchronously
20296 * loads D-Bus properties unless the
20297 * %G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES flag is used.
20299 * If the %G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS flag is not set, also sets up
20300 * match rules for signals. Connect to the #GDBusProxy::g-signal signal
20301 * to handle signals from the remote object.
20303 * If @name is a well-known name and the
20304 * %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START and %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START_AT_CONSTRUCTION
20305 * flags aren't set and no name owner currently exists, the message bus
20306 * will be requested to launch a name owner for the name.
20308 * This is a synchronous failable constructor. See g_dbus_proxy_new()
20309 * and g_dbus_proxy_new_finish() for the asynchronous version.
20311 * #GDBusProxy is used in this [example][gdbus-wellknown-proxy].
20313 * Returns: A #GDBusProxy or %NULL if error is set. Free with g_object_unref().
20319 * g_dbus_proxy_set_cached_property:
20320 * @proxy: A #GDBusProxy
20321 * @property_name: Property name.
20322 * @value: (allow-none): Value for the property or %NULL to remove it from the cache.
20324 * If @value is not %NULL, sets the cached value for the property with
20325 * name @property_name to the value in @value.
20327 * If @value is %NULL, then the cached value is removed from the
20330 * If @proxy has an expected interface (see
20331 * #GDBusProxy:g-interface-info) and @property_name is referenced by
20332 * it, then @value is checked against the type of the property.
20334 * If the @value #GVariant is floating, it is consumed. This allows
20335 * convenient 'inline' use of g_variant_new(), e.g.
20336 * |[<!-- language="C" -->
20337 * g_dbus_proxy_set_cached_property (proxy,
20339 * g_variant_new ("(si)",
20344 * Normally you will not need to use this method since @proxy
20345 * is tracking changes using the
20346 * `org.freedesktop.DBus.Properties.PropertiesChanged`
20347 * D-Bus signal. However, for performance reasons an object may
20348 * decide to not use this signal for some properties and instead
20349 * use a proprietary out-of-band mechanism to transmit changes.
20351 * As a concrete example, consider an object with a property
20352 * `ChatroomParticipants` which is an array of strings. Instead of
20353 * transmitting the same (long) array every time the property changes,
20354 * it is more efficient to only transmit the delta using e.g. signals
20355 * `ChatroomParticipantJoined(String name)` and
20356 * `ChatroomParticipantParted(String name)`.
20363 * g_dbus_proxy_set_default_timeout:
20364 * @proxy: A #GDBusProxy.
20365 * @timeout_msec: Timeout in milliseconds.
20367 * Sets the timeout to use if -1 (specifying default timeout) is
20368 * passed as @timeout_msec in the g_dbus_proxy_call() and
20369 * g_dbus_proxy_call_sync() functions.
20371 * See the #GDBusProxy:g-default-timeout property for more details.
20378 * g_dbus_proxy_set_interface_info:
20379 * @proxy: A #GDBusProxy
20380 * @info: (allow-none): Minimum interface this proxy conforms to or %NULL to unset.
20382 * Ensure that interactions with @proxy conform to the given
20383 * interface. See the #GDBusProxy:g-interface-info property for more
20391 * g_dbus_server_get_client_address:
20392 * @server: A #GDBusServer.
20394 * Gets a D-Bus address string that can be used by clients to connect
20397 * Returns: A D-Bus address string. Do not free, the string is owned
20404 * g_dbus_server_get_flags:
20405 * @server: A #GDBusServer.
20407 * Gets the flags for @server.
20409 * Returns: A set of flags from the #GDBusServerFlags enumeration.
20415 * g_dbus_server_get_guid:
20416 * @server: A #GDBusServer.
20418 * Gets the GUID for @server.
20420 * Returns: A D-Bus GUID. Do not free this string, it is owned by @server.
20426 * g_dbus_server_is_active:
20427 * @server: A #GDBusServer.
20429 * Gets whether @server is active.
20431 * Returns: %TRUE if server is active, %FALSE otherwise.
20437 * g_dbus_server_new_sync:
20438 * @address: A D-Bus address.
20439 * @flags: Flags from the #GDBusServerFlags enumeration.
20440 * @guid: A D-Bus GUID.
20441 * @observer: (allow-none): A #GDBusAuthObserver or %NULL.
20442 * @cancellable: (allow-none): A #GCancellable or %NULL.
20443 * @error: Return location for server or %NULL.
20445 * Creates a new D-Bus server that listens on the first address in
20446 * @address that works.
20448 * Once constructed, you can use g_dbus_server_get_client_address() to
20449 * get a D-Bus address string that clients can use to connect.
20451 * Connect to the #GDBusServer::new-connection signal to handle
20452 * incoming connections.
20454 * The returned #GDBusServer isn't active - you have to start it with
20455 * g_dbus_server_start().
20457 * #GDBusServer is used in this [example][gdbus-peer-to-peer].
20459 * This is a synchronous failable constructor. See
20460 * g_dbus_server_new() for the asynchronous version.
20462 * Returns: A #GDBusServer or %NULL if @error is set. Free with
20463 * g_object_unref().
20469 * g_dbus_server_start:
20470 * @server: A #GDBusServer.
20479 * g_dbus_server_stop:
20480 * @server: A #GDBusServer.
20489 * g_dbus_signal_info_ref:
20490 * @info: A #GDBusSignalInfo
20492 * If @info is statically allocated does nothing. Otherwise increases
20493 * the reference count.
20495 * Returns: The same @info.
20501 * g_dbus_signal_info_unref:
20502 * @info: A #GDBusSignalInfo.
20504 * If @info is statically allocated, does nothing. Otherwise decreases
20505 * the reference count of @info. When its reference count drops to 0,
20506 * the memory used is freed.
20513 * g_desktop_app_info_get_action_name:
20514 * @info: a #GDesktopAppInfo
20515 * @action_name: the name of the action as from
20516 * g_desktop_app_info_list_actions()
20518 * Gets the user-visible display name of the "additional application
20519 * action" specified by @action_name.
20521 * This corresponds to the "Name" key within the keyfile group for the
20524 * Returns: (transfer full): the locale-specific action name
20530 * g_desktop_app_info_get_boolean:
20531 * @info: a #GDesktopAppInfo
20532 * @key: the key to look up
20534 * Looks up a boolean value in the keyfile backing @info.
20536 * The @key is looked up in the "Desktop Entry" group.
20538 * Returns: the boolean value, or %FALSE if the key
20545 * g_desktop_app_info_get_categories:
20546 * @info: a #GDesktopAppInfo
20548 * Gets the categories from the desktop file.
20550 * Returns: The unparsed Categories key from the desktop file;
20551 * i.e. no attempt is made to split it by ';' or validate it.
20556 * g_desktop_app_info_get_filename:
20557 * @info: a #GDesktopAppInfo
20559 * When @info was created from a known filename, return it. In some
20560 * situations such as the #GDesktopAppInfo returned from
20561 * g_desktop_app_info_new_from_keyfile(), this function will return %NULL.
20563 * Returns: (type filename): The full path to the file for @info,
20564 * or %NULL if not known.
20570 * g_desktop_app_info_get_generic_name:
20571 * @info: a #GDesktopAppInfo
20573 * Gets the generic name from the destkop file.
20575 * Returns: The value of the GenericName key
20580 * g_desktop_app_info_get_implementations:
20581 * @interface: the name of the interface
20583 * Gets all applications that implement @interface.
20585 * An application implements an interface if that interface is listed in
20586 * the Implements= line of the desktop file of the application.
20588 * Returns: (element-type GDesktopAppInfo) (transfer full): a list of #GDesktopAppInfo
20595 * g_desktop_app_info_get_is_hidden:
20596 * @info: a #GDesktopAppInfo.
20598 * A desktop file is hidden if the Hidden key in it is
20601 * Returns: %TRUE if hidden, %FALSE otherwise.
20606 * g_desktop_app_info_get_keywords:
20607 * @info: a #GDesktopAppInfo
20609 * Gets the keywords from the desktop file.
20611 * Returns: (transfer none): The value of the Keywords key
20617 * g_desktop_app_info_get_nodisplay:
20618 * @info: a #GDesktopAppInfo
20620 * Gets the value of the NoDisplay key, which helps determine if the
20621 * application info should be shown in menus. See
20622 * #G_KEY_FILE_DESKTOP_KEY_NO_DISPLAY and g_app_info_should_show().
20624 * Returns: The value of the NoDisplay key
20630 * g_desktop_app_info_get_show_in:
20631 * @info: a #GDesktopAppInfo
20632 * @desktop_env: (nullable): a string specifying a desktop name
20634 * Checks if the application info should be shown in menus that list available
20635 * applications for a specific name of the desktop, based on the
20636 * `OnlyShowIn` and `NotShowIn` keys.
20638 * @desktop_env should typically be given as %NULL, in which case the
20639 * `XDG_CURRENT_DESKTOP` environment variable is consulted. If you want
20640 * to override the default mechanism then you may specify @desktop_env,
20641 * but this is not recommended.
20643 * Note that g_app_info_should_show() for @info will include this check (with
20644 * %NULL for @desktop_env) as well as additional checks.
20646 * Returns: %TRUE if the @info should be shown in @desktop_env according to the
20647 * `OnlyShowIn` and `NotShowIn` keys, %FALSE
20654 * g_desktop_app_info_get_startup_wm_class:
20655 * @info: a #GDesktopAppInfo that supports startup notify
20657 * Retrieves the StartupWMClass field from @info. This represents the
20658 * WM_CLASS property of the main window of the application, if launched
20661 * Returns: (transfer none): the startup WM class, or %NULL if none is set
20662 * in the desktop file.
20668 * g_desktop_app_info_get_string:
20669 * @info: a #GDesktopAppInfo
20670 * @key: the key to look up
20672 * Looks up a string value in the keyfile backing @info.
20674 * The @key is looked up in the "Desktop Entry" group.
20676 * Returns: a newly allocated string, or %NULL if the key
20683 * g_desktop_app_info_has_key:
20684 * @info: a #GDesktopAppInfo
20685 * @key: the key to look up
20687 * Returns whether @key exists in the "Desktop Entry" group
20688 * of the keyfile backing @info.
20690 * Returns: %TRUE if the @key exists
20696 * g_desktop_app_info_launch_action:
20697 * @info: a #GDesktopAppInfo
20698 * @action_name: the name of the action as from
20699 * g_desktop_app_info_list_actions()
20700 * @launch_context: (allow-none): a #GAppLaunchContext
20702 * Activates the named application action.
20704 * You may only call this function on action names that were
20705 * returned from g_desktop_app_info_list_actions().
20707 * Note that if the main entry of the desktop file indicates that the
20708 * application supports startup notification, and @launch_context is
20709 * non-%NULL, then startup notification will be used when activating the
20710 * action (and as such, invocation of the action on the receiving side
20711 * must signal the end of startup notification when it is completed).
20712 * This is the expected behaviour of applications declaring additional
20713 * actions, as per the desktop file specification.
20715 * As with g_app_info_launch() there is no way to detect failures that
20716 * occur while using this function.
20723 * g_desktop_app_info_launch_uris_as_manager:
20724 * @appinfo: a #GDesktopAppInfo
20725 * @uris: (element-type utf8): List of URIs
20726 * @launch_context: (allow-none): a #GAppLaunchContext
20727 * @spawn_flags: #GSpawnFlags, used for each process
20728 * @user_setup: (scope call) (allow-none): a #GSpawnChildSetupFunc, used once
20729 * for each process.
20730 * @user_setup_data: (closure user_setup) (allow-none): User data for @user_setup
20731 * @pid_callback: (scope call) (allow-none): Callback for child processes
20732 * @pid_callback_data: (closure pid_callback) (allow-none): User data for @callback
20733 * @error: return location for a #GError, or %NULL
20735 * This function performs the equivalent of g_app_info_launch_uris(),
20736 * but is intended primarily for operating system components that
20737 * launch applications. Ordinary applications should use
20738 * g_app_info_launch_uris().
20740 * If the application is launched via traditional UNIX fork()/exec()
20741 * then @spawn_flags, @user_setup and @user_setup_data are used for the
20742 * call to g_spawn_async(). Additionally, @pid_callback (with
20743 * @pid_callback_data) will be called to inform about the PID of the
20746 * If application launching occurs via some other mechanism (eg: D-Bus
20747 * activation) then @spawn_flags, @user_setup, @user_setup_data,
20748 * @pid_callback and @pid_callback_data are ignored.
20750 * Returns: %TRUE on successful launch, %FALSE otherwise.
20755 * g_desktop_app_info_list_actions:
20756 * @info: a #GDesktopAppInfo
20758 * Returns the list of "additional application actions" supported on the
20759 * desktop file, as per the desktop file specification.
20761 * As per the specification, this is the list of actions that are
20762 * explicitly listed in the "Actions" key of the [Desktop Entry] group.
20764 * Returns: (array zero-terminated=1) (element-type utf8) (transfer none): a list of strings, always non-%NULL
20770 * g_desktop_app_info_lookup_get_default_for_uri_scheme:
20771 * @lookup: a #GDesktopAppInfoLookup
20772 * @uri_scheme: a string containing a URI scheme.
20774 * Gets the default application for launching applications
20775 * using this URI scheme for a particular GDesktopAppInfoLookup
20778 * The GDesktopAppInfoLookup interface and this function is used
20779 * to implement g_app_info_get_default_for_uri_scheme() backends
20780 * in a GIO module. There is no reason for applications to use it
20781 * directly. Applications should use g_app_info_get_default_for_uri_scheme().
20783 * Returns: (transfer full): #GAppInfo for given @uri_scheme or %NULL on error.
20784 * Deprecated: The #GDesktopAppInfoLookup interface is deprecated and unused by gio.
20789 * g_desktop_app_info_new:
20790 * @desktop_id: the desktop file id
20792 * Creates a new #GDesktopAppInfo based on a desktop file id.
20794 * A desktop file id is the basename of the desktop file, including the
20795 * .desktop extension. GIO is looking for a desktop file with this name
20796 * in the `applications` subdirectories of the XDG
20797 * data directories (i.e. the directories specified in the `XDG_DATA_HOME`
20798 * and `XDG_DATA_DIRS` environment variables). GIO also supports the
20799 * prefix-to-subdirectory mapping that is described in the
20800 * [Menu Spec](http://standards.freedesktop.org/menu-spec/latest/)
20801 * (i.e. a desktop id of kde-foo.desktop will match
20802 * `/usr/share/applications/kde/foo.desktop`).
20804 * Returns: a new #GDesktopAppInfo, or %NULL if no desktop file with that id
20809 * g_desktop_app_info_new_from_filename:
20810 * @filename: (type filename): the path of a desktop file, in the GLib
20811 * filename encoding
20813 * Creates a new #GDesktopAppInfo.
20815 * Returns: a new #GDesktopAppInfo or %NULL on error.
20820 * g_desktop_app_info_new_from_keyfile:
20821 * @key_file: an opened #GKeyFile
20823 * Creates a new #GDesktopAppInfo.
20825 * Returns: a new #GDesktopAppInfo or %NULL on error.
20831 * g_desktop_app_info_search:
20832 * @search_string: the search string to use
20834 * Searches desktop files for ones that match @search_string.
20836 * The return value is an array of strvs. Each strv contains a list of
20837 * applications that matched @search_string with an equal score. The
20838 * outer list is sorted by score so that the first strv contains the
20839 * best-matching applications, and so on.
20840 * The algorithm for determining matches is undefined and may change at
20843 * Returns: (array zero-terminated=1) (element-type GStrv) (transfer full): a
20844 * list of strvs. Free each item with g_strfreev() and free the outer
20845 * list with g_free().
20850 * g_desktop_app_info_set_desktop_env:
20851 * @desktop_env: a string specifying what desktop this is
20853 * Sets the name of the desktop that the application is running in.
20854 * This is used by g_app_info_should_show() and
20855 * g_desktop_app_info_get_show_in() to evaluate the
20856 * `OnlyShowIn` and `NotShowIn`
20857 * desktop entry fields.
20859 * Should be called only once; subsequent calls are ignored.
20861 * Deprecated: 2.42: do not use this API. Since 2.42 the value of the
20862 * `XDG_CURRENT_DESKTOP` environment variable will be used.
20867 * g_drive_can_eject:
20868 * @drive: a #GDrive.
20870 * Checks if a drive can be ejected.
20872 * Returns: %TRUE if the @drive can be ejected, %FALSE otherwise.
20877 * g_drive_can_poll_for_media:
20878 * @drive: a #GDrive.
20880 * Checks if a drive can be polled for media changes.
20882 * Returns: %TRUE if the @drive can be polled for media changes,
20883 * %FALSE otherwise.
20888 * g_drive_can_start:
20889 * @drive: a #GDrive.
20891 * Checks if a drive can be started.
20893 * Returns: %TRUE if the @drive can be started, %FALSE otherwise.
20899 * g_drive_can_start_degraded:
20900 * @drive: a #GDrive.
20902 * Checks if a drive can be started degraded.
20904 * Returns: %TRUE if the @drive can be started degraded, %FALSE otherwise.
20910 * g_drive_can_stop:
20911 * @drive: a #GDrive.
20913 * Checks if a drive can be stopped.
20915 * Returns: %TRUE if the @drive can be stopped, %FALSE otherwise.
20922 * @drive: a #GDrive.
20923 * @flags: flags affecting the unmount if required for eject
20924 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
20925 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
20926 * @user_data: user data to pass to @callback
20928 * Asynchronously ejects a drive.
20930 * When the operation is finished, @callback will be called.
20931 * You can then call g_drive_eject_finish() to obtain the
20932 * result of the operation.
20934 * Deprecated: 2.22: Use g_drive_eject_with_operation() instead.
20939 * g_drive_eject_finish:
20940 * @drive: a #GDrive.
20941 * @result: a #GAsyncResult.
20942 * @error: a #GError, or %NULL
20944 * Finishes ejecting a drive.
20946 * Returns: %TRUE if the drive has been ejected successfully,
20947 * %FALSE otherwise.
20948 * Deprecated: 2.22: Use g_drive_eject_with_operation_finish() instead.
20953 * g_drive_eject_with_operation:
20954 * @drive: a #GDrive.
20955 * @flags: flags affecting the unmount if required for eject
20956 * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid
20957 * user interaction.
20958 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
20959 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
20960 * @user_data: user data passed to @callback.
20962 * Ejects a drive. This is an asynchronous operation, and is
20963 * finished by calling g_drive_eject_with_operation_finish() with the @drive
20964 * and #GAsyncResult data returned in the @callback.
20971 * g_drive_eject_with_operation_finish:
20972 * @drive: a #GDrive.
20973 * @result: a #GAsyncResult.
20974 * @error: a #GError location to store the error occurring, or %NULL to
20977 * Finishes ejecting a drive. If any errors occurred during the operation,
20978 * @error will be set to contain the errors and %FALSE will be returned.
20980 * Returns: %TRUE if the drive was successfully ejected. %FALSE otherwise.
20986 * g_drive_enumerate_identifiers:
20987 * @drive: a #GDrive
20989 * Gets the kinds of identifiers that @drive has.
20990 * Use g_drive_get_identifier() to obtain the identifiers
20993 * Returns: (transfer full) (array zero-terminated=1): a %NULL-terminated
20994 * array of strings containing kinds of identifiers. Use g_strfreev()
21000 * g_drive_get_icon:
21001 * @drive: a #GDrive.
21003 * Gets the icon for @drive.
21005 * Returns: (transfer full): #GIcon for the @drive.
21006 * Free the returned object with g_object_unref().
21011 * g_drive_get_identifier:
21012 * @drive: a #GDrive
21013 * @kind: the kind of identifier to return
21015 * Gets the identifier of the given kind for @drive.
21017 * Returns: a newly allocated string containing the
21018 * requested identfier, or %NULL if the #GDrive
21019 * doesn't have this kind of identifier.
21024 * g_drive_get_name:
21025 * @drive: a #GDrive.
21027 * Gets the name of @drive.
21029 * Returns: a string containing @drive's name. The returned
21030 * string should be freed when no longer needed.
21035 * g_drive_get_sort_key:
21036 * @drive: A #GDrive.
21038 * Gets the sort key for @drive, if any.
21040 * Returns: Sorting key for @drive or %NULL if no such key is available.
21046 * g_drive_get_start_stop_type:
21047 * @drive: a #GDrive.
21049 * Gets a hint about how a drive can be started/stopped.
21051 * Returns: A value from the #GDriveStartStopType enumeration.
21057 * g_drive_get_symbolic_icon:
21058 * @drive: a #GDrive.
21060 * Gets the icon for @drive.
21062 * Returns: (transfer full): symbolic #GIcon for the @drive.
21063 * Free the returned object with g_object_unref().
21069 * g_drive_get_volumes:
21070 * @drive: a #GDrive.
21072 * Get a list of mountable volumes for @drive.
21074 * The returned list should be freed with g_list_free(), after
21075 * its elements have been unreffed with g_object_unref().
21077 * Returns: (element-type GVolume) (transfer full): #GList containing any #GVolume objects on the given @drive.
21082 * g_drive_has_media:
21083 * @drive: a #GDrive.
21085 * Checks if the @drive has media. Note that the OS may not be polling
21086 * the drive for media changes; see g_drive_is_media_check_automatic()
21087 * for more details.
21089 * Returns: %TRUE if @drive has media, %FALSE otherwise.
21094 * g_drive_has_volumes:
21095 * @drive: a #GDrive.
21097 * Check if @drive has any mountable volumes.
21099 * Returns: %TRUE if the @drive contains volumes, %FALSE otherwise.
21104 * g_drive_is_media_check_automatic:
21105 * @drive: a #GDrive.
21107 * Checks if @drive is capabable of automatically detecting media changes.
21109 * Returns: %TRUE if the @drive is capabable of automatically detecting
21110 * media changes, %FALSE otherwise.
21115 * g_drive_is_media_removable:
21116 * @drive: a #GDrive.
21118 * Checks if the @drive supports removable media.
21120 * Returns: %TRUE if @drive supports removable media, %FALSE otherwise.
21125 * g_drive_is_removable:
21126 * @drive: a #GDrive.
21128 * Checks if the #GDrive and/or its media is considered removable by the user.
21129 * See g_drive_is_media_removable().
21131 * Returns: %TRUE if @drive and/or its media is considered removable, %FALSE otherwise.
21137 * g_drive_poll_for_media:
21138 * @drive: a #GDrive.
21139 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
21140 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
21141 * @user_data: user data to pass to @callback
21143 * Asynchronously polls @drive to see if media has been inserted or removed.
21145 * When the operation is finished, @callback will be called.
21146 * You can then call g_drive_poll_for_media_finish() to obtain the
21147 * result of the operation.
21152 * g_drive_poll_for_media_finish:
21153 * @drive: a #GDrive.
21154 * @result: a #GAsyncResult.
21155 * @error: a #GError, or %NULL
21157 * Finishes an operation started with g_drive_poll_for_media() on a drive.
21159 * Returns: %TRUE if the drive has been poll_for_mediaed successfully,
21160 * %FALSE otherwise.
21166 * @drive: a #GDrive.
21167 * @flags: flags affecting the start operation.
21168 * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid
21169 * user interaction.
21170 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
21171 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
21172 * @user_data: user data to pass to @callback
21174 * Asynchronously starts a drive.
21176 * When the operation is finished, @callback will be called.
21177 * You can then call g_drive_start_finish() to obtain the
21178 * result of the operation.
21185 * g_drive_start_finish:
21186 * @drive: a #GDrive.
21187 * @result: a #GAsyncResult.
21188 * @error: a #GError, or %NULL
21190 * Finishes starting a drive.
21192 * Returns: %TRUE if the drive has been started successfully,
21193 * %FALSE otherwise.
21200 * @drive: a #GDrive.
21201 * @flags: flags affecting the unmount if required for stopping.
21202 * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid
21203 * user interaction.
21204 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
21205 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
21206 * @user_data: user data to pass to @callback
21208 * Asynchronously stops a drive.
21210 * When the operation is finished, @callback will be called.
21211 * You can then call g_drive_stop_finish() to obtain the
21212 * result of the operation.
21219 * g_drive_stop_finish:
21220 * @drive: a #GDrive.
21221 * @result: a #GAsyncResult.
21222 * @error: a #GError, or %NULL
21224 * Finishes stopping a drive.
21226 * Returns: %TRUE if the drive has been stopped successfully,
21227 * %FALSE otherwise.
21233 * g_dtls_client_connection_get_accepted_cas:
21234 * @conn: the #GDtlsClientConnection
21236 * Gets the list of distinguished names of the Certificate Authorities
21237 * that the server will accept certificates from. This will be set
21238 * during the TLS handshake if the server requests a certificate.
21239 * Otherwise, it will be %NULL.
21241 * Each item in the list is a #GByteArray which contains the complete
21242 * subject DN of the certificate authority.
21244 * Returns: (element-type GByteArray) (transfer full): the list of
21245 * CA DNs. You should unref each element with g_byte_array_unref() and then
21246 * the free the list with g_list_free().
21252 * g_dtls_client_connection_get_server_identity:
21253 * @conn: the #GDtlsClientConnection
21255 * Gets @conn's expected server identity
21257 * Returns: (transfer none): a #GSocketConnectable describing the
21258 * expected server identity, or %NULL if the expected identity is not
21265 * g_dtls_client_connection_get_validation_flags:
21266 * @conn: the #GDtlsClientConnection
21268 * Gets @conn's validation flags
21270 * Returns: the validation flags
21276 * g_dtls_client_connection_new:
21277 * @base_socket: the #GDatagramBased to wrap
21278 * @server_identity: (allow-none): the expected identity of the server
21279 * @error: #GError for error reporting, or %NULL to ignore.
21281 * Creates a new #GDtlsClientConnection wrapping @base_socket which is
21282 * assumed to communicate with the server identified by @server_identity.
21284 * Returns: (transfer full) (type GDtlsClientConnection): the new
21285 * #GDtlsClientConnection, or %NULL on error
21291 * g_dtls_client_connection_set_server_identity:
21292 * @conn: the #GDtlsClientConnection
21293 * @identity: a #GSocketConnectable describing the expected server identity
21295 * Sets @conn's expected server identity, which is used both to tell
21296 * servers on virtual hosts which certificate to present, and also
21297 * to let @conn know what name to look for in the certificate when
21298 * performing %G_TLS_CERTIFICATE_BAD_IDENTITY validation, if enabled.
21305 * g_dtls_client_connection_set_validation_flags:
21306 * @conn: the #GDtlsClientConnection
21307 * @flags: the #GTlsCertificateFlags to use
21309 * Sets @conn's validation flags, to override the default set of
21310 * checks performed when validating a server certificate. By default,
21311 * %G_TLS_CERTIFICATE_VALIDATE_ALL is used.
21318 * g_dtls_connection_close:
21319 * @conn: a #GDtlsConnection
21320 * @cancellable: (nullable): a #GCancellable, or %NULL
21321 * @error: a #GError, or %NULL
21323 * Close the DTLS connection. This is equivalent to calling
21324 * g_dtls_connection_shutdown() to shut down both sides of the connection.
21326 * Closing a #GDtlsConnection waits for all buffered but untransmitted data to
21327 * be sent before it completes. It then sends a `close_notify` DTLS alert to the
21328 * peer and may wait for a `close_notify` to be received from the peer. It does
21329 * not close the underlying #GDtlsConnection:base-socket; that must be closed
21332 * Once @conn is closed, all other operations will return %G_IO_ERROR_CLOSED.
21333 * Closing a #GDtlsConnection multiple times will not return an error.
21335 * #GDtlsConnections will be automatically closed when the last reference is
21336 * dropped, but you might want to call this function to make sure resources are
21337 * released as early as possible.
21339 * If @cancellable is cancelled, the #GDtlsConnection may be left
21340 * partially-closed and any pending untransmitted data may be lost. Call
21341 * g_dtls_connection_close() again to complete closing the #GDtlsConnection.
21343 * Returns: %TRUE on success, %FALSE otherwise
21349 * g_dtls_connection_close_async:
21350 * @conn: a #GDtlsConnection
21351 * @io_priority: the [I/O priority][io-priority] of the request
21352 * @cancellable: (nullable): a #GCancellable, or %NULL
21353 * @callback: callback to call when the close operation is complete
21354 * @user_data: the data to pass to the callback function
21356 * Asynchronously close the DTLS connection. See g_dtls_connection_close() for
21357 * more information.
21364 * g_dtls_connection_close_finish:
21365 * @conn: a #GDtlsConnection
21366 * @result: a #GAsyncResult
21367 * @error: a #GError pointer, or %NULL
21369 * Finish an asynchronous TLS close operation. See g_dtls_connection_close()
21370 * for more information.
21372 * Returns: %TRUE on success, %FALSE on failure, in which
21373 * case @error will be set
21379 * g_dtls_connection_emit_accept_certificate:
21380 * @conn: a #GDtlsConnection
21381 * @peer_cert: the peer's #GTlsCertificate
21382 * @errors: the problems with @peer_cert
21384 * Used by #GDtlsConnection implementations to emit the
21385 * #GDtlsConnection::accept-certificate signal.
21387 * Returns: %TRUE if one of the signal handlers has returned
21388 * %TRUE to accept @peer_cert
21394 * g_dtls_connection_get_certificate:
21395 * @conn: a #GDtlsConnection
21397 * Gets @conn's certificate, as set by
21398 * g_dtls_connection_set_certificate().
21400 * Returns: (transfer none): @conn's certificate, or %NULL
21406 * g_dtls_connection_get_database:
21407 * @conn: a #GDtlsConnection
21409 * Gets the certificate database that @conn uses to verify
21410 * peer certificates. See g_dtls_connection_set_database().
21412 * Returns: (transfer none): the certificate database that @conn uses or %NULL
21418 * g_dtls_connection_get_interaction:
21419 * @conn: a connection
21421 * Get the object that will be used to interact with the user. It will be used
21422 * for things like prompting the user for passwords. If %NULL is returned, then
21423 * no user interaction will occur for this connection.
21425 * Returns: (transfer none): The interaction object.
21431 * g_dtls_connection_get_peer_certificate:
21432 * @conn: a #GDtlsConnection
21434 * Gets @conn's peer's certificate after the handshake has completed.
21435 * (It is not set during the emission of
21436 * #GDtlsConnection::accept-certificate.)
21438 * Returns: (transfer none): @conn's peer's certificate, or %NULL
21444 * g_dtls_connection_get_peer_certificate_errors:
21445 * @conn: a #GDtlsConnection
21447 * Gets the errors associated with validating @conn's peer's
21448 * certificate, after the handshake has completed. (It is not set
21449 * during the emission of #GDtlsConnection::accept-certificate.)
21451 * Returns: @conn's peer's certificate errors
21457 * g_dtls_connection_get_rehandshake_mode:
21458 * @conn: a #GDtlsConnection
21460 * Gets @conn rehandshaking mode. See
21461 * g_dtls_connection_set_rehandshake_mode() for details.
21463 * Returns: @conn's rehandshaking mode
21469 * g_dtls_connection_get_require_close_notify:
21470 * @conn: a #GDtlsConnection
21472 * Tests whether or not @conn expects a proper TLS close notification
21473 * when the connection is closed. See
21474 * g_dtls_connection_set_require_close_notify() for details.
21476 * Returns: %TRUE if @conn requires a proper TLS close notification.
21482 * g_dtls_connection_handshake:
21483 * @conn: a #GDtlsConnection
21484 * @cancellable: (allow-none): a #GCancellable, or %NULL
21485 * @error: a #GError, or %NULL
21487 * Attempts a TLS handshake on @conn.
21489 * On the client side, it is never necessary to call this method;
21490 * although the connection needs to perform a handshake after
21491 * connecting (or after sending a "STARTTLS"-type command) and may
21492 * need to rehandshake later if the server requests it,
21493 * #GDtlsConnection will handle this for you automatically when you try
21494 * to send or receive data on the connection. However, you can call
21495 * g_dtls_connection_handshake() manually if you want to know for sure
21496 * whether the initial handshake succeeded or failed (as opposed to
21497 * just immediately trying to write to @conn, in which
21498 * case if it fails, it may not be possible to tell if it failed
21499 * before or after completing the handshake).
21501 * Likewise, on the server side, although a handshake is necessary at
21502 * the beginning of the communication, you do not need to call this
21503 * function explicitly unless you want clearer error reporting.
21504 * However, you may call g_dtls_connection_handshake() later on to
21505 * renegotiate parameters (encryption methods, etc) with the client.
21507 * #GDtlsConnection::accept_certificate may be emitted during the
21510 * Returns: success or failure
21516 * g_dtls_connection_handshake_async:
21517 * @conn: a #GDtlsConnection
21518 * @io_priority: the [I/O priority][io-priority] of the request
21519 * @cancellable: (allow-none): a #GCancellable, or %NULL
21520 * @callback: callback to call when the handshake is complete
21521 * @user_data: the data to pass to the callback function
21523 * Asynchronously performs a TLS handshake on @conn. See
21524 * g_dtls_connection_handshake() for more information.
21531 * g_dtls_connection_handshake_finish:
21532 * @conn: a #GDtlsConnection
21533 * @result: a #GAsyncResult.
21534 * @error: a #GError pointer, or %NULL
21536 * Finish an asynchronous TLS handshake operation. See
21537 * g_dtls_connection_handshake() for more information.
21539 * Returns: %TRUE on success, %FALSE on failure, in which
21540 * case @error will be set.
21546 * g_dtls_connection_set_certificate:
21547 * @conn: a #GDtlsConnection
21548 * @certificate: the certificate to use for @conn
21550 * This sets the certificate that @conn will present to its peer
21551 * during the TLS handshake. For a #GDtlsServerConnection, it is
21552 * mandatory to set this, and that will normally be done at construct
21555 * For a #GDtlsClientConnection, this is optional. If a handshake fails
21556 * with %G_TLS_ERROR_CERTIFICATE_REQUIRED, that means that the server
21557 * requires a certificate, and if you try connecting again, you should
21558 * call this method first. You can call
21559 * g_dtls_client_connection_get_accepted_cas() on the failed connection
21560 * to get a list of Certificate Authorities that the server will
21561 * accept certificates from.
21563 * (It is also possible that a server will allow the connection with
21564 * or without a certificate; in that case, if you don't provide a
21565 * certificate, you can tell that the server requested one by the fact
21566 * that g_dtls_client_connection_get_accepted_cas() will return
21574 * g_dtls_connection_set_database:
21575 * @conn: a #GDtlsConnection
21576 * @database: a #GTlsDatabase
21578 * Sets the certificate database that is used to verify peer certificates.
21579 * This is set to the default database by default. See
21580 * g_dtls_backend_get_default_database(). If set to %NULL, then
21581 * peer certificate validation will always set the
21582 * %G_TLS_CERTIFICATE_UNKNOWN_CA error (meaning
21583 * #GDtlsConnection::accept-certificate will always be emitted on
21584 * client-side connections, unless that bit is not set in
21585 * #GDtlsClientConnection:validation-flags).
21592 * g_dtls_connection_set_interaction:
21593 * @conn: a connection
21594 * @interaction: (allow-none): an interaction object, or %NULL
21596 * Set the object that will be used to interact with the user. It will be used
21597 * for things like prompting the user for passwords.
21599 * The @interaction argument will normally be a derived subclass of
21600 * #GTlsInteraction. %NULL can also be provided if no user interaction
21601 * should occur for this connection.
21608 * g_dtls_connection_set_rehandshake_mode:
21609 * @conn: a #GDtlsConnection
21610 * @mode: the rehandshaking mode
21612 * Sets how @conn behaves with respect to rehandshaking requests.
21614 * %G_TLS_REHANDSHAKE_NEVER means that it will never agree to
21615 * rehandshake after the initial handshake is complete. (For a client,
21616 * this means it will refuse rehandshake requests from the server, and
21617 * for a server, this means it will close the connection with an error
21618 * if the client attempts to rehandshake.)
21620 * %G_TLS_REHANDSHAKE_SAFELY means that the connection will allow a
21621 * rehandshake only if the other end of the connection supports the
21622 * TLS `renegotiation_info` extension. This is the default behavior,
21623 * but means that rehandshaking will not work against older
21624 * implementations that do not support that extension.
21626 * %G_TLS_REHANDSHAKE_UNSAFELY means that the connection will allow
21627 * rehandshaking even without the `renegotiation_info` extension. On
21628 * the server side in particular, this is not recommended, since it
21629 * leaves the server open to certain attacks. However, this mode is
21630 * necessary if you need to allow renegotiation with older client
21638 * g_dtls_connection_set_require_close_notify:
21639 * @conn: a #GDtlsConnection
21640 * @require_close_notify: whether or not to require close notification
21642 * Sets whether or not @conn expects a proper TLS close notification
21643 * before the connection is closed. If this is %TRUE (the default),
21644 * then @conn will expect to receive a TLS close notification from its
21645 * peer before the connection is closed, and will return a
21646 * %G_TLS_ERROR_EOF error if the connection is closed without proper
21647 * notification (since this may indicate a network error, or
21648 * man-in-the-middle attack).
21650 * In some protocols, the application will know whether or not the
21651 * connection was closed cleanly based on application-level data
21652 * (because the application-level data includes a length field, or is
21653 * somehow self-delimiting); in this case, the close notify is
21654 * redundant and may be omitted. You
21655 * can use g_dtls_connection_set_require_close_notify() to tell @conn
21656 * to allow an "unannounced" connection close, in which case the close
21657 * will show up as a 0-length read, as in a non-TLS
21658 * #GDatagramBased, and it is up to the application to check that
21659 * the data has been fully received.
21661 * Note that this only affects the behavior when the peer closes the
21662 * connection; when the application calls g_dtls_connection_close_async() on
21663 * @conn itself, this will send a close notification regardless of the
21664 * setting of this property. If you explicitly want to do an unclean
21665 * close, you can close @conn's #GDtlsConnection:base-socket rather
21666 * than closing @conn itself.
21673 * g_dtls_connection_shutdown:
21674 * @conn: a #GDtlsConnection
21675 * @shutdown_read: %TRUE to stop reception of incoming datagrams
21676 * @shutdown_write: %TRUE to stop sending outgoing datagrams
21677 * @cancellable: (nullable): a #GCancellable, or %NULL
21678 * @error: a #GError, or %NULL
21680 * Shut down part or all of a DTLS connection.
21682 * If @shutdown_read is %TRUE then the receiving side of the connection is shut
21683 * down, and further reading is disallowed. Subsequent calls to
21684 * g_datagram_based_receive_messages() will return %G_IO_ERROR_CLOSED.
21686 * If @shutdown_write is %TRUE then the sending side of the connection is shut
21687 * down, and further writing is disallowed. Subsequent calls to
21688 * g_datagram_based_send_messages() will return %G_IO_ERROR_CLOSED.
21690 * It is allowed for both @shutdown_read and @shutdown_write to be TRUE — this
21691 * is equivalent to calling g_dtls_connection_close().
21693 * If @cancellable is cancelled, the #GDtlsConnection may be left
21694 * partially-closed and any pending untransmitted data may be lost. Call
21695 * g_dtls_connection_shutdown() again to complete closing the #GDtlsConnection.
21697 * Returns: %TRUE on success, %FALSE otherwise
21703 * g_dtls_connection_shutdown_async:
21704 * @conn: a #GDtlsConnection
21705 * @shutdown_read: %TRUE to stop reception of incoming datagrams
21706 * @shutdown_write: %TRUE to stop sending outgoing datagrams
21707 * @io_priority: the [I/O priority][io-priority] of the request
21708 * @cancellable: (nullable): a #GCancellable, or %NULL
21709 * @callback: callback to call when the shutdown operation is complete
21710 * @user_data: the data to pass to the callback function
21712 * Asynchronously shut down part or all of the DTLS connection. See
21713 * g_dtls_connection_shutdown() for more information.
21720 * g_dtls_connection_shutdown_finish:
21721 * @conn: a #GDtlsConnection
21722 * @result: a #GAsyncResult
21723 * @error: a #GError pointer, or %NULL
21725 * Finish an asynchronous TLS shutdown operation. See
21726 * g_dtls_connection_shutdown() for more information.
21728 * Returns: %TRUE on success, %FALSE on failure, in which
21729 * case @error will be set
21735 * g_dtls_server_connection_new:
21736 * @base_socket: the #GDatagramBased to wrap
21737 * @certificate: (allow-none): the default server certificate, or %NULL
21738 * @error: #GError for error reporting, or %NULL to ignore
21740 * Creates a new #GDtlsServerConnection wrapping @base_socket.
21742 * Returns: (transfer full) (type GDtlsServerConnection): the new
21743 * #GDtlsServerConnection, or %NULL on error
21749 * g_emblem_get_icon:
21750 * @emblem: a #GEmblem from which the icon should be extracted.
21752 * Gives back the icon from @emblem.
21754 * Returns: (transfer none): a #GIcon. The returned object belongs to
21755 * the emblem and should not be modified or freed.
21761 * g_emblem_get_origin:
21762 * @emblem: a #GEmblem
21764 * Gets the origin of the emblem.
21766 * Returns: (transfer none): the origin of the emblem
21773 * @icon: a GIcon containing the icon.
21775 * Creates a new emblem for @icon.
21777 * Returns: a new #GEmblem.
21783 * g_emblem_new_with_origin:
21784 * @icon: a GIcon containing the icon.
21785 * @origin: a GEmblemOrigin enum defining the emblem's origin
21787 * Creates a new emblem for @icon.
21789 * Returns: a new #GEmblem.
21795 * g_emblemed_icon_add_emblem:
21796 * @emblemed: a #GEmblemedIcon
21797 * @emblem: a #GEmblem
21799 * Adds @emblem to the #GList of #GEmblems.
21806 * g_emblemed_icon_clear_emblems:
21807 * @emblemed: a #GEmblemedIcon
21809 * Removes all the emblems from @icon.
21816 * g_emblemed_icon_get_emblems:
21817 * @emblemed: a #GEmblemedIcon
21819 * Gets the list of emblems for the @icon.
21821 * Returns: (element-type Gio.Emblem) (transfer none): a #GList of
21822 * #GEmblems that is owned by @emblemed
21828 * g_emblemed_icon_get_icon:
21829 * @emblemed: a #GEmblemedIcon
21831 * Gets the main icon for @emblemed.
21833 * Returns: (transfer none): a #GIcon that is owned by @emblemed
21839 * g_emblemed_icon_new:
21841 * @emblem: (allow-none): a #GEmblem, or %NULL
21843 * Creates a new emblemed icon for @icon with the emblem @emblem.
21845 * Returns: (transfer full) (type GEmblemedIcon): a new #GIcon
21851 * g_file_append_to:
21852 * @file: input #GFile
21853 * @flags: a set of #GFileCreateFlags
21854 * @cancellable: (allow-none): optional #GCancellable object,
21856 * @error: a #GError, or %NULL
21858 * Gets an output stream for appending data to the file.
21859 * If the file doesn't already exist it is created.
21861 * By default files created are generally readable by everyone,
21862 * but if you pass #G_FILE_CREATE_PRIVATE in @flags the file
21863 * will be made readable only to the current user, to the level that
21864 * is supported on the target filesystem.
21866 * If @cancellable is not %NULL, then the operation can be cancelled
21867 * by triggering the cancellable object from another thread. If the
21868 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
21871 * Some file systems don't allow all file names, and may return an
21872 * %G_IO_ERROR_INVALID_FILENAME error. If the file is a directory the
21873 * %G_IO_ERROR_IS_DIRECTORY error will be returned. Other errors are
21874 * possible too, and depend on what kind of filesystem the file is on.
21876 * Returns: (transfer full): a #GFileOutputStream, or %NULL on error.
21877 * Free the returned object with g_object_unref().
21882 * g_file_append_to_async:
21883 * @file: input #GFile
21884 * @flags: a set of #GFileCreateFlags
21885 * @io_priority: the [I/O priority][io-priority] of the request
21886 * @cancellable: (allow-none): optional #GCancellable object,
21888 * @callback: (scope async): a #GAsyncReadyCallback to call
21889 * when the request is satisfied
21890 * @user_data: (closure): the data to pass to callback function
21892 * Asynchronously opens @file for appending.
21894 * For more details, see g_file_append_to() which is
21895 * the synchronous version of this call.
21897 * When the operation is finished, @callback will be called.
21898 * You can then call g_file_append_to_finish() to get the result
21899 * of the operation.
21904 * g_file_append_to_finish:
21905 * @file: input #GFile
21906 * @res: #GAsyncResult
21907 * @error: a #GError, or %NULL
21909 * Finishes an asynchronous file append operation started with
21910 * g_file_append_to_async().
21912 * Returns: (transfer full): a valid #GFileOutputStream
21913 * or %NULL on error.
21914 * Free the returned object with g_object_unref().
21919 * g_file_attribute_info_list_add:
21920 * @list: a #GFileAttributeInfoList.
21921 * @name: the name of the attribute to add.
21922 * @type: the #GFileAttributeType for the attribute.
21923 * @flags: #GFileAttributeInfoFlags for the attribute.
21925 * Adds a new attribute with @name to the @list, setting
21926 * its @type and @flags.
21931 * g_file_attribute_info_list_dup:
21932 * @list: a #GFileAttributeInfoList to duplicate.
21934 * Makes a duplicate of a file attribute info list.
21936 * Returns: a copy of the given @list.
21941 * g_file_attribute_info_list_lookup:
21942 * @list: a #GFileAttributeInfoList.
21943 * @name: the name of the attribute to lookup.
21945 * Gets the file attribute with the name @name from @list.
21947 * Returns: a #GFileAttributeInfo for the @name, or %NULL if an
21948 * attribute isn't found.
21953 * g_file_attribute_info_list_new:
21955 * Creates a new file attribute info list.
21957 * Returns: a #GFileAttributeInfoList.
21962 * g_file_attribute_info_list_ref:
21963 * @list: a #GFileAttributeInfoList to reference.
21965 * References a file attribute info list.
21967 * Returns: #GFileAttributeInfoList or %NULL on error.
21972 * g_file_attribute_info_list_unref:
21973 * @list: The #GFileAttributeInfoList to unreference.
21975 * Removes a reference from the given @list. If the reference count
21976 * falls to zero, the @list is deleted.
21981 * g_file_attribute_matcher_enumerate_namespace:
21982 * @matcher: a #GFileAttributeMatcher.
21983 * @ns: a string containing a file attribute namespace.
21985 * Checks if the matcher will match all of the keys in a given namespace.
21986 * This will always return %TRUE if a wildcard character is in use (e.g. if
21987 * matcher was created with "standard::*" and @ns is "standard", or if matcher was created
21988 * using "*" and namespace is anything.)
21990 * TODO: this is awkwardly worded.
21992 * Returns: %TRUE if the matcher matches all of the entries
21993 * in the given @ns, %FALSE otherwise.
21998 * g_file_attribute_matcher_enumerate_next:
21999 * @matcher: a #GFileAttributeMatcher.
22001 * Gets the next matched attribute from a #GFileAttributeMatcher.
22003 * Returns: a string containing the next attribute or %NULL if
22004 * no more attribute exist.
22009 * g_file_attribute_matcher_matches:
22010 * @matcher: a #GFileAttributeMatcher.
22011 * @attribute: a file attribute key.
22013 * Checks if an attribute will be matched by an attribute matcher. If
22014 * the matcher was created with the "*" matching string, this function
22015 * will always return %TRUE.
22017 * Returns: %TRUE if @attribute matches @matcher. %FALSE otherwise.
22022 * g_file_attribute_matcher_matches_only:
22023 * @matcher: a #GFileAttributeMatcher.
22024 * @attribute: a file attribute key.
22026 * Checks if a attribute matcher only matches a given attribute. Always
22027 * returns %FALSE if "*" was used when creating the matcher.
22029 * Returns: %TRUE if the matcher only matches @attribute. %FALSE otherwise.
22034 * g_file_attribute_matcher_new:
22035 * @attributes: an attribute string to match.
22037 * Creates a new file attribute matcher, which matches attributes
22038 * against a given string. #GFileAttributeMatchers are reference
22039 * counted structures, and are created with a reference count of 1. If
22040 * the number of references falls to 0, the #GFileAttributeMatcher is
22041 * automatically destroyed.
22043 * The @attribute string should be formatted with specific keys separated
22044 * from namespaces with a double colon. Several "namespace::key" strings may be
22045 * concatenated with a single comma (e.g. "standard::type,standard::is-hidden").
22046 * The wildcard "*" may be used to match all keys and namespaces, or
22047 * "namespace::*" will match all keys in a given namespace.
22049 * ## Examples of file attribute matcher strings and results
22051 * - `"*"`: matches all attributes.
22052 * - `"standard::is-hidden"`: matches only the key is-hidden in the
22053 * standard namespace.
22054 * - `"standard::type,unix::*"`: matches the type key in the standard
22055 * namespace and all keys in the unix namespace.
22057 * Returns: a #GFileAttributeMatcher
22062 * g_file_attribute_matcher_ref:
22063 * @matcher: a #GFileAttributeMatcher.
22065 * References a file attribute matcher.
22067 * Returns: a #GFileAttributeMatcher.
22072 * g_file_attribute_matcher_subtract:
22073 * @matcher: Matcher to subtract from
22074 * @subtract: The matcher to subtract
22076 * Subtracts all attributes of @subtract from @matcher and returns
22077 * a matcher that supports those attributes.
22079 * Note that currently it is not possible to remove a single
22080 * attribute when the @matcher matches the whole namespace - or remove
22081 * a namespace or attribute when the matcher matches everything. This
22082 * is a limitation of the current implementation, but may be fixed
22085 * Returns: A file attribute matcher matching all attributes of
22086 * @matcher that are not matched by @subtract
22091 * g_file_attribute_matcher_to_string:
22092 * @matcher: (allow-none): a #GFileAttributeMatcher.
22094 * Prints what the matcher is matching against. The format will be
22095 * equal to the format passed to g_file_attribute_matcher_new().
22096 * The output however, might not be identical, as the matcher may
22097 * decide to use a different order or omit needless parts.
22099 * Returns: a string describing the attributes the matcher matches
22100 * against or %NULL if @matcher was %NULL.
22106 * g_file_attribute_matcher_unref:
22107 * @matcher: a #GFileAttributeMatcher.
22109 * Unreferences @matcher. If the reference count falls below 1,
22110 * the @matcher is automatically freed.
22115 * g_file_attribute_value_dup:
22116 * @other: a #GFileAttributeValue to duplicate.
22118 * Duplicates a file attribute.
22120 * Returns: a duplicate of the @other.
22125 * g_file_attribute_value_set:
22126 * @attr: a #GFileAttributeValue to set the value in.
22127 * @new_value: a #GFileAttributeValue to get the value from.
22129 * Sets an attribute's value from another attribute.
22135 * @source: input #GFile
22136 * @destination: destination #GFile
22137 * @flags: set of #GFileCopyFlags
22138 * @cancellable: (allow-none): optional #GCancellable object,
22140 * @progress_callback: (allow-none) (scope call): function to callback with
22141 * progress information, or %NULL if progress information is not needed
22142 * @progress_callback_data: (closure): user data to pass to @progress_callback
22143 * @error: #GError to set on error, or %NULL
22145 * Copies the file @source to the location specified by @destination.
22146 * Can not handle recursive copies of directories.
22148 * If the flag #G_FILE_COPY_OVERWRITE is specified an already
22149 * existing @destination file is overwritten.
22151 * If the flag #G_FILE_COPY_NOFOLLOW_SYMLINKS is specified then symlinks
22152 * will be copied as symlinks, otherwise the target of the
22153 * @source symlink will be copied.
22155 * If @cancellable is not %NULL, then the operation can be cancelled by
22156 * triggering the cancellable object from another thread. If the operation
22157 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
22159 * If @progress_callback is not %NULL, then the operation can be monitored
22160 * by setting this to a #GFileProgressCallback function.
22161 * @progress_callback_data will be passed to this function. It is guaranteed
22162 * that this callback will be called after all data has been transferred with
22163 * the total number of bytes copied during the operation.
22165 * If the @source file does not exist, then the %G_IO_ERROR_NOT_FOUND error
22166 * is returned, independent on the status of the @destination.
22168 * If #G_FILE_COPY_OVERWRITE is not specified and the target exists, then
22169 * the error %G_IO_ERROR_EXISTS is returned.
22171 * If trying to overwrite a file over a directory, the %G_IO_ERROR_IS_DIRECTORY
22172 * error is returned. If trying to overwrite a directory with a directory the
22173 * %G_IO_ERROR_WOULD_MERGE error is returned.
22175 * If the source is a directory and the target does not exist, or
22176 * #G_FILE_COPY_OVERWRITE is specified and the target is a file, then the
22177 * %G_IO_ERROR_WOULD_RECURSE error is returned.
22179 * If you are interested in copying the #GFile object itself (not the on-disk
22180 * file), see g_file_dup().
22182 * Returns: %TRUE on success, %FALSE otherwise.
22187 * g_file_copy_async: (skip)
22188 * @source: input #GFile
22189 * @destination: destination #GFile
22190 * @flags: set of #GFileCopyFlags
22191 * @io_priority: the [I/O priority][io-priority] of the request
22192 * @cancellable: (allow-none): optional #GCancellable object,
22194 * @progress_callback: (allow-none): function to callback with progress
22195 * information, or %NULL if progress information is not needed
22196 * @progress_callback_data: (closure): user data to pass to @progress_callback
22197 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
22198 * @user_data: the data to pass to callback function
22200 * Copies the file @source to the location specified by @destination
22201 * asynchronously. For details of the behaviour, see g_file_copy().
22203 * If @progress_callback is not %NULL, then that function that will be called
22204 * just like in g_file_copy(). The callback will run in the default main context
22205 * of the thread calling g_file_copy_async() — the same context as @callback is
22208 * When the operation is finished, @callback will be called. You can then call
22209 * g_file_copy_finish() to get the result of the operation.
22214 * g_file_copy_attributes:
22215 * @source: a #GFile with attributes
22216 * @destination: a #GFile to copy attributes to
22217 * @flags: a set of #GFileCopyFlags
22218 * @cancellable: (allow-none): optional #GCancellable object,
22220 * @error: a #GError, %NULL to ignore
22222 * Copies the file attributes from @source to @destination.
22224 * Normally only a subset of the file attributes are copied,
22225 * those that are copies in a normal file copy operation
22226 * (which for instance does not include e.g. owner). However
22227 * if #G_FILE_COPY_ALL_METADATA is specified in @flags, then
22228 * all the metadata that is possible to copy is copied. This
22229 * is useful when implementing move by copy + delete source.
22231 * Returns: %TRUE if the attributes were copied successfully,
22232 * %FALSE otherwise.
22237 * g_file_copy_finish:
22238 * @file: input #GFile
22239 * @res: a #GAsyncResult
22240 * @error: a #GError, or %NULL
22242 * Finishes copying the file started with g_file_copy_async().
22244 * Returns: a %TRUE on success, %FALSE on error.
22250 * @file: input #GFile
22251 * @flags: a set of #GFileCreateFlags
22252 * @cancellable: (allow-none): optional #GCancellable object,
22254 * @error: a #GError, or %NULL
22256 * Creates a new file and returns an output stream for writing to it.
22257 * The file must not already exist.
22259 * By default files created are generally readable by everyone,
22260 * but if you pass #G_FILE_CREATE_PRIVATE in @flags the file
22261 * will be made readable only to the current user, to the level
22262 * that is supported on the target filesystem.
22264 * If @cancellable is not %NULL, then the operation can be cancelled
22265 * by triggering the cancellable object from another thread. If the
22266 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
22269 * If a file or directory with this name already exists the
22270 * %G_IO_ERROR_EXISTS error will be returned. Some file systems don't
22271 * allow all file names, and may return an %G_IO_ERROR_INVALID_FILENAME
22272 * error, and if the name is to long %G_IO_ERROR_FILENAME_TOO_LONG will
22273 * be returned. Other errors are possible too, and depend on what kind
22274 * of filesystem the file is on.
22276 * Returns: (transfer full): a #GFileOutputStream for the newly created
22277 * file, or %NULL on error.
22278 * Free the returned object with g_object_unref().
22283 * g_file_create_async:
22284 * @file: input #GFile
22285 * @flags: a set of #GFileCreateFlags
22286 * @io_priority: the [I/O priority][io-priority] of the request
22287 * @cancellable: (allow-none): optional #GCancellable object,
22289 * @callback: (scope async): a #GAsyncReadyCallback to call
22290 * when the request is satisfied
22291 * @user_data: (closure): the data to pass to callback function
22293 * Asynchronously creates a new file and returns an output stream
22294 * for writing to it. The file must not already exist.
22296 * For more details, see g_file_create() which is
22297 * the synchronous version of this call.
22299 * When the operation is finished, @callback will be called.
22300 * You can then call g_file_create_finish() to get the result
22301 * of the operation.
22306 * g_file_create_finish:
22307 * @file: input #GFile
22308 * @res: a #GAsyncResult
22309 * @error: a #GError, or %NULL
22311 * Finishes an asynchronous file create operation started with
22312 * g_file_create_async().
22314 * Returns: (transfer full): a #GFileOutputStream or %NULL on error.
22315 * Free the returned object with g_object_unref().
22320 * g_file_create_readwrite:
22322 * @flags: a set of #GFileCreateFlags
22323 * @cancellable: (allow-none): optional #GCancellable object,
22325 * @error: return location for a #GError, or %NULL
22327 * Creates a new file and returns a stream for reading and
22328 * writing to it. The file must not already exist.
22330 * By default files created are generally readable by everyone,
22331 * but if you pass #G_FILE_CREATE_PRIVATE in @flags the file
22332 * will be made readable only to the current user, to the level
22333 * that is supported on the target filesystem.
22335 * If @cancellable is not %NULL, then the operation can be cancelled
22336 * by triggering the cancellable object from another thread. If the
22337 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
22340 * If a file or directory with this name already exists, the
22341 * %G_IO_ERROR_EXISTS error will be returned. Some file systems don't
22342 * allow all file names, and may return an %G_IO_ERROR_INVALID_FILENAME
22343 * error, and if the name is too long, %G_IO_ERROR_FILENAME_TOO_LONG
22344 * will be returned. Other errors are possible too, and depend on what
22345 * kind of filesystem the file is on.
22347 * Note that in many non-local file cases read and write streams are
22348 * not supported, so make sure you really need to do read and write
22349 * streaming, rather than just opening for reading or writing.
22351 * Returns: (transfer full): a #GFileIOStream for the newly created
22352 * file, or %NULL on error.
22353 * Free the returned object with g_object_unref().
22359 * g_file_create_readwrite_async:
22360 * @file: input #GFile
22361 * @flags: a set of #GFileCreateFlags
22362 * @io_priority: the [I/O priority][io-priority] of the request
22363 * @cancellable: (allow-none): optional #GCancellable object,
22365 * @callback: (scope async): a #GAsyncReadyCallback to call
22366 * when the request is satisfied
22367 * @user_data: (closure): the data to pass to callback function
22369 * Asynchronously creates a new file and returns a stream
22370 * for reading and writing to it. The file must not already exist.
22372 * For more details, see g_file_create_readwrite() which is
22373 * the synchronous version of this call.
22375 * When the operation is finished, @callback will be called.
22376 * You can then call g_file_create_readwrite_finish() to get
22377 * the result of the operation.
22384 * g_file_create_readwrite_finish:
22385 * @file: input #GFile
22386 * @res: a #GAsyncResult
22387 * @error: a #GError, or %NULL
22389 * Finishes an asynchronous file create operation started with
22390 * g_file_create_readwrite_async().
22392 * Returns: (transfer full): a #GFileIOStream or %NULL on error.
22393 * Free the returned object with g_object_unref().
22399 * g_file_delete: (virtual delete_file)
22400 * @file: input #GFile
22401 * @cancellable: (allow-none): optional #GCancellable object,
22403 * @error: a #GError, or %NULL
22405 * Deletes a file. If the @file is a directory, it will only be
22406 * deleted if it is empty. This has the same semantics as g_unlink().
22408 * If @cancellable is not %NULL, then the operation can be cancelled by
22409 * triggering the cancellable object from another thread. If the operation
22410 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
22412 * Returns: %TRUE if the file was deleted. %FALSE otherwise.
22417 * g_file_delete_async: (virtual delete_file_async)
22418 * @file: input #GFile
22419 * @io_priority: the [I/O priority][io-priority] of the request
22420 * @cancellable: (allow-none): optional #GCancellable object,
22422 * @callback: a #GAsyncReadyCallback to call
22423 * when the request is satisfied
22424 * @user_data: the data to pass to callback function
22426 * Asynchronously delete a file. If the @file is a directory, it will
22427 * only be deleted if it is empty. This has the same semantics as
22435 * g_file_delete_finish: (virtual delete_file_finish)
22436 * @file: input #GFile
22437 * @result: a #GAsyncResult
22438 * @error: a #GError, or %NULL
22440 * Finishes deleting a file started with g_file_delete_async().
22442 * Returns: %TRUE if the file was deleted. %FALSE otherwise.
22448 * g_file_descriptor_based_get_fd:
22449 * @fd_based: a #GFileDescriptorBased.
22451 * Gets the underlying file descriptor.
22453 * Returns: The file descriptor
22460 * @file: input #GFile
22462 * Duplicates a #GFile handle. This operation does not duplicate
22463 * the actual file or directory represented by the #GFile; see
22464 * g_file_copy() if attempting to copy a file.
22466 * This call does no blocking I/O.
22468 * Returns: (transfer full): a new #GFile that is a duplicate
22469 * of the given #GFile.
22474 * g_file_eject_mountable:
22475 * @file: input #GFile
22476 * @flags: flags affecting the operation
22477 * @cancellable: (allow-none): optional #GCancellable object,
22479 * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call
22480 * when the request is satisfied, or %NULL
22481 * @user_data: (closure): the data to pass to callback function
22483 * Starts an asynchronous eject on a mountable.
22484 * When this operation has completed, @callback will be called with
22485 * @user_user data, and the operation can be finalized with
22486 * g_file_eject_mountable_finish().
22488 * If @cancellable is not %NULL, then the operation can be cancelled by
22489 * triggering the cancellable object from another thread. If the operation
22490 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
22492 * Deprecated: 2.22: Use g_file_eject_mountable_with_operation() instead.
22497 * g_file_eject_mountable_finish:
22498 * @file: input #GFile
22499 * @result: a #GAsyncResult
22500 * @error: a #GError, or %NULL
22502 * Finishes an asynchronous eject operation started by
22503 * g_file_eject_mountable().
22505 * Returns: %TRUE if the @file was ejected successfully.
22506 * %FALSE otherwise.
22507 * Deprecated: 2.22: Use g_file_eject_mountable_with_operation_finish()
22513 * g_file_eject_mountable_with_operation:
22514 * @file: input #GFile
22515 * @flags: flags affecting the operation
22516 * @mount_operation: (allow-none): a #GMountOperation,
22517 * or %NULL to avoid user interaction
22518 * @cancellable: (allow-none): optional #GCancellable object,
22520 * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call
22521 * when the request is satisfied, or %NULL
22522 * @user_data: (closure): the data to pass to callback function
22524 * Starts an asynchronous eject on a mountable.
22525 * When this operation has completed, @callback will be called with
22526 * @user_user data, and the operation can be finalized with
22527 * g_file_eject_mountable_with_operation_finish().
22529 * If @cancellable is not %NULL, then the operation can be cancelled by
22530 * triggering the cancellable object from another thread. If the operation
22531 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
22538 * g_file_eject_mountable_with_operation_finish:
22539 * @file: input #GFile
22540 * @result: a #GAsyncResult
22541 * @error: a #GError, or %NULL
22543 * Finishes an asynchronous eject operation started by
22544 * g_file_eject_mountable_with_operation().
22546 * Returns: %TRUE if the @file was ejected successfully.
22547 * %FALSE otherwise.
22553 * g_file_enumerate_children:
22554 * @file: input #GFile
22555 * @attributes: an attribute query string
22556 * @flags: a set of #GFileQueryInfoFlags
22557 * @cancellable: (allow-none): optional #GCancellable object,
22559 * @error: #GError for error reporting
22561 * Gets the requested information about the files in a directory.
22562 * The result is a #GFileEnumerator object that will give out
22563 * #GFileInfo objects for all the files in the directory.
22565 * The @attributes value is a string that specifies the file
22566 * attributes that should be gathered. It is not an error if
22567 * it's not possible to read a particular requested attribute
22568 * from a file - it just won't be set. @attributes should
22569 * be a comma-separated list of attributes or attribute wildcards.
22570 * The wildcard "*" means all attributes, and a wildcard like
22571 * "standard::*" means all attributes in the standard namespace.
22572 * An example attribute query be "standard::*,owner::user".
22573 * The standard attributes are available as defines, like
22574 * #G_FILE_ATTRIBUTE_STANDARD_NAME.
22576 * If @cancellable is not %NULL, then the operation can be cancelled
22577 * by triggering the cancellable object from another thread. If the
22578 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
22581 * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will
22582 * be returned. If the file is not a directory, the %G_IO_ERROR_NOT_DIRECTORY
22583 * error will be returned. Other errors are possible too.
22585 * Returns: (transfer full): A #GFileEnumerator if successful,
22586 * %NULL on error. Free the returned object with g_object_unref().
22591 * g_file_enumerate_children_async:
22592 * @file: input #GFile
22593 * @attributes: an attribute query string
22594 * @flags: a set of #GFileQueryInfoFlags
22595 * @io_priority: the [I/O priority][io-priority] of the request
22596 * @cancellable: (allow-none): optional #GCancellable object,
22598 * @callback: (scope async): a #GAsyncReadyCallback to call when the
22599 * request is satisfied
22600 * @user_data: (closure): the data to pass to callback function
22602 * Asynchronously gets the requested information about the files
22603 * in a directory. The result is a #GFileEnumerator object that will
22604 * give out #GFileInfo objects for all the files in the directory.
22606 * For more details, see g_file_enumerate_children() which is
22607 * the synchronous version of this call.
22609 * When the operation is finished, @callback will be called. You can
22610 * then call g_file_enumerate_children_finish() to get the result of
22616 * g_file_enumerate_children_finish:
22617 * @file: input #GFile
22618 * @res: a #GAsyncResult
22619 * @error: a #GError
22621 * Finishes an async enumerate children operation.
22622 * See g_file_enumerate_children_async().
22624 * Returns: (transfer full): a #GFileEnumerator or %NULL
22625 * if an error occurred.
22626 * Free the returned object with g_object_unref().
22631 * g_file_enumerator_close:
22632 * @enumerator: a #GFileEnumerator.
22633 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
22634 * @error: location to store the error occurring, or %NULL to ignore
22636 * Releases all resources used by this enumerator, making the
22637 * enumerator return %G_IO_ERROR_CLOSED on all calls.
22639 * This will be automatically called when the last reference
22640 * is dropped, but you might want to call this function to make
22641 * sure resources are released as early as possible.
22643 * Returns: #TRUE on success or #FALSE on error.
22648 * g_file_enumerator_close_async:
22649 * @enumerator: a #GFileEnumerator.
22650 * @io_priority: the [I/O priority][io-priority] of the request
22651 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
22652 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
22653 * @user_data: (closure): the data to pass to callback function
22655 * Asynchronously closes the file enumerator.
22657 * If @cancellable is not %NULL, then the operation can be cancelled by
22658 * triggering the cancellable object from another thread. If the operation
22659 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned in
22660 * g_file_enumerator_close_finish().
22665 * g_file_enumerator_close_finish:
22666 * @enumerator: a #GFileEnumerator.
22667 * @result: a #GAsyncResult.
22668 * @error: a #GError location to store the error occurring, or %NULL to
22671 * Finishes closing a file enumerator, started from g_file_enumerator_close_async().
22673 * If the file enumerator was already closed when g_file_enumerator_close_async()
22674 * was called, then this function will report %G_IO_ERROR_CLOSED in @error, and
22675 * return %FALSE. If the file enumerator had pending operation when the close
22676 * operation was started, then this function will report %G_IO_ERROR_PENDING, and
22677 * return %FALSE. If @cancellable was not %NULL, then the operation may have been
22678 * cancelled by triggering the cancellable object from another thread. If the operation
22679 * was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %FALSE will be
22682 * Returns: %TRUE if the close operation has finished successfully.
22687 * g_file_enumerator_get_child:
22688 * @enumerator: a #GFileEnumerator
22689 * @info: a #GFileInfo gotten from g_file_enumerator_next_file()
22690 * or the async equivalents.
22692 * Return a new #GFile which refers to the file named by @info in the source
22693 * directory of @enumerator. This function is primarily intended to be used
22694 * inside loops with g_file_enumerator_next_file().
22696 * This is a convenience method that's equivalent to:
22697 * |[<!-- language="C" -->
22698 * gchar *name = g_file_info_get_name (info);
22699 * GFile *child = g_file_get_child (g_file_enumerator_get_container (enumr),
22703 * Returns: (transfer full): a #GFile for the #GFileInfo passed it.
22709 * g_file_enumerator_get_container:
22710 * @enumerator: a #GFileEnumerator
22712 * Get the #GFile container which is being enumerated.
22714 * Returns: (transfer none): the #GFile which is being enumerated.
22720 * g_file_enumerator_has_pending:
22721 * @enumerator: a #GFileEnumerator.
22723 * Checks if the file enumerator has pending operations.
22725 * Returns: %TRUE if the @enumerator has pending operations.
22730 * g_file_enumerator_is_closed:
22731 * @enumerator: a #GFileEnumerator.
22733 * Checks if the file enumerator has been closed.
22735 * Returns: %TRUE if the @enumerator is closed.
22740 * g_file_enumerator_iterate:
22741 * @direnum: an open #GFileEnumerator
22742 * @out_info: (out) (transfer none) (allow-none): Output location for the next #GFileInfo, or %NULL
22743 * @out_child: (out) (transfer none) (allow-none): Output location for the next #GFile, or %NULL
22744 * @cancellable: a #GCancellable
22745 * @error: a #GError
22747 * This is a version of g_file_enumerator_next_file() that's easier to
22748 * use correctly from C programs. With g_file_enumerator_next_file(),
22749 * the gboolean return value signifies "end of iteration or error", which
22750 * requires allocation of a temporary #GError.
22752 * In contrast, with this function, a %FALSE return from
22753 * g_file_enumerator_iterate() *always* means
22754 * "error". End of iteration is signaled by @out_info or @out_child being %NULL.
22756 * Another crucial difference is that the references for @out_info and
22757 * @out_child are owned by @direnum (they are cached as hidden
22758 * properties). You must not unref them in your own code. This makes
22759 * memory management significantly easier for C code in combination
22762 * Finally, this function optionally allows retrieving a #GFile as
22765 * You must specify at least one of @out_info or @out_child.
22767 * The code pattern for correctly using g_file_enumerator_iterate() from C
22771 * direnum = g_file_enumerate_children (file, ...);
22775 * if (!g_file_enumerator_iterate (direnum, &info, NULL, cancellable, error))
22779 * ... do stuff with "info"; do not unref it! ...
22783 * g_object_unref (direnum); // Note: frees the last @info
22791 * g_file_enumerator_next_file:
22792 * @enumerator: a #GFileEnumerator.
22793 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
22794 * @error: location to store the error occurring, or %NULL to ignore
22796 * Returns information for the next file in the enumerated object.
22797 * Will block until the information is available. The #GFileInfo
22798 * returned from this function will contain attributes that match the
22799 * attribute string that was passed when the #GFileEnumerator was created.
22801 * See the documentation of #GFileEnumerator for information about the
22802 * order of returned files.
22804 * On error, returns %NULL and sets @error to the error. If the
22805 * enumerator is at the end, %NULL will be returned and @error will
22808 * Returns: (nullable) (transfer full): A #GFileInfo or %NULL on error
22809 * or end of enumerator. Free the returned object with
22810 * g_object_unref() when no longer needed.
22815 * g_file_enumerator_next_files_async:
22816 * @enumerator: a #GFileEnumerator.
22817 * @num_files: the number of file info objects to request
22818 * @io_priority: the [I/O priority][io-priority] of the request
22819 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
22820 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
22821 * @user_data: (closure): the data to pass to callback function
22823 * Request information for a number of files from the enumerator asynchronously.
22824 * When all i/o for the operation is finished the @callback will be called with
22825 * the requested information.
22827 * See the documentation of #GFileEnumerator for information about the
22828 * order of returned files.
22830 * The callback can be called with less than @num_files files in case of error
22831 * or at the end of the enumerator. In case of a partial error the callback will
22832 * be called with any succeeding items and no error, and on the next request the
22833 * error will be reported. If a request is cancelled the callback will be called
22834 * with %G_IO_ERROR_CANCELLED.
22836 * During an async request no other sync and async calls are allowed, and will
22837 * result in %G_IO_ERROR_PENDING errors.
22839 * Any outstanding i/o request with higher priority (lower numerical value) will
22840 * be executed before an outstanding request with lower priority. Default
22841 * priority is %G_PRIORITY_DEFAULT.
22846 * g_file_enumerator_next_files_finish:
22847 * @enumerator: a #GFileEnumerator.
22848 * @result: a #GAsyncResult.
22849 * @error: a #GError location to store the error occurring, or %NULL to
22852 * Finishes the asynchronous operation started with g_file_enumerator_next_files_async().
22854 * Returns: (transfer full) (element-type Gio.FileInfo): a #GList of #GFileInfos. You must free the list with
22855 * g_list_free() and unref the infos with g_object_unref() when you're
22861 * g_file_enumerator_set_pending:
22862 * @enumerator: a #GFileEnumerator.
22863 * @pending: a boolean value.
22865 * Sets the file enumerator as having pending operations.
22871 * @file1: the first #GFile
22872 * @file2: the second #GFile
22874 * Checks if the two given #GFiles refer to the same file.
22876 * Note that two #GFiles that differ can still refer to the same
22877 * file on the filesystem due to various forms of filename
22880 * This call does no blocking I/O.
22882 * Returns: %TRUE if @file1 and @file2 are equal.
22887 * g_file_find_enclosing_mount:
22888 * @file: input #GFile
22889 * @cancellable: (allow-none): optional #GCancellable object,
22891 * @error: a #GError
22893 * Gets a #GMount for the #GFile.
22895 * If the #GFileIface for @file does not have a mount (e.g.
22896 * possibly a remote share), @error will be set to %G_IO_ERROR_NOT_FOUND
22897 * and %NULL will be returned.
22899 * If @cancellable is not %NULL, then the operation can be cancelled by
22900 * triggering the cancellable object from another thread. If the operation
22901 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
22903 * Returns: (transfer full): a #GMount where the @file is located
22904 * or %NULL on error.
22905 * Free the returned object with g_object_unref().
22910 * g_file_find_enclosing_mount_async:
22912 * @io_priority: the [I/O priority][io-priority] of the request
22913 * @cancellable: (allow-none): optional #GCancellable object,
22915 * @callback: (scope async): a #GAsyncReadyCallback to call
22916 * when the request is satisfied
22917 * @user_data: (closure): the data to pass to callback function
22919 * Asynchronously gets the mount for the file.
22921 * For more details, see g_file_find_enclosing_mount() which is
22922 * the synchronous version of this call.
22924 * When the operation is finished, @callback will be called.
22925 * You can then call g_file_find_enclosing_mount_finish() to
22926 * get the result of the operation.
22931 * g_file_find_enclosing_mount_finish:
22933 * @res: a #GAsyncResult
22934 * @error: a #GError
22936 * Finishes an asynchronous find mount request.
22937 * See g_file_find_enclosing_mount_async().
22939 * Returns: (transfer full): #GMount for given @file or %NULL on error.
22940 * Free the returned object with g_object_unref().
22945 * g_file_get_basename:
22946 * @file: input #GFile
22948 * Gets the base name (the last component of the path) for a given #GFile.
22950 * If called for the top level of a system (such as the filesystem root
22951 * or a uri like sftp://host/) it will return a single directory separator
22952 * (and on Windows, possibly a drive letter).
22954 * The base name is a byte string (not UTF-8). It has no defined encoding
22955 * or rules other than it may not contain zero bytes. If you want to use
22956 * filenames in a user interface you should use the display name that you
22957 * can get by requesting the %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME
22958 * attribute with g_file_query_info().
22960 * This call does no blocking I/O.
22962 * Returns: (type filename) (nullable): string containing the #GFile's
22963 * base name, or %NULL if given #GFile is invalid. The returned string
22964 * should be freed with g_free() when no longer needed.
22969 * g_file_get_child:
22970 * @file: input #GFile
22971 * @name: (type filename): string containing the child's basename
22973 * Gets a child of @file with basename equal to @name.
22975 * Note that the file with that specific name might not exist, but
22976 * you can still have a #GFile that points to it. You can use this
22977 * for instance to create that file.
22979 * This call does no blocking I/O.
22981 * Returns: (transfer full): a #GFile to a child specified by @name.
22982 * Free the returned object with g_object_unref().
22987 * g_file_get_child_for_display_name:
22988 * @file: input #GFile
22989 * @display_name: string to a possible child
22990 * @error: return location for an error
22992 * Gets the child of @file for a given @display_name (i.e. a UTF-8
22993 * version of the name). If this function fails, it returns %NULL
22994 * and @error will be set. This is very useful when constructing a
22995 * #GFile for a new file and the user entered the filename in the
22996 * user interface, for instance when you select a directory and
22997 * type a filename in the file selector.
22999 * This call does no blocking I/O.
23001 * Returns: (transfer full): a #GFile to the specified child, or
23002 * %NULL if the display name couldn't be converted.
23003 * Free the returned object with g_object_unref().
23008 * g_file_get_parent:
23009 * @file: input #GFile
23011 * Gets the parent directory for the @file.
23012 * If the @file represents the root directory of the
23013 * file system, then %NULL will be returned.
23015 * This call does no blocking I/O.
23017 * Returns: (nullable) (transfer full): a #GFile structure to the
23018 * parent of the given #GFile or %NULL if there is no parent. Free
23019 * the returned object with g_object_unref().
23024 * g_file_get_parse_name:
23025 * @file: input #GFile
23027 * Gets the parse name of the @file.
23028 * A parse name is a UTF-8 string that describes the
23029 * file such that one can get the #GFile back using
23030 * g_file_parse_name().
23032 * This is generally used to show the #GFile as a nice
23033 * full-pathname kind of string in a user interface,
23034 * like in a location entry.
23036 * For local files with names that can safely be converted
23037 * to UTF-8 the pathname is used, otherwise the IRI is used
23038 * (a form of URI that allows UTF-8 characters unescaped).
23040 * This call does no blocking I/O.
23042 * Returns: a string containing the #GFile's parse name.
23043 * The returned string should be freed with g_free()
23044 * when no longer needed.
23050 * @file: input #GFile
23052 * Gets the local pathname for #GFile, if one exists. If non-%NULL, this is
23053 * guaranteed to be an absolute, canonical path. It might contain symlinks.
23055 * This call does no blocking I/O.
23057 * Returns: (type filename) (nullable): string containing the #GFile's path,
23058 * or %NULL if no such path exists. The returned string should be freed
23059 * with g_free() when no longer needed.
23064 * g_file_get_relative_path:
23065 * @parent: input #GFile
23066 * @descendant: input #GFile
23068 * Gets the path for @descendant relative to @parent.
23070 * This call does no blocking I/O.
23072 * Returns: (type filename) (nullable): string with the relative path from
23073 * @descendant to @parent, or %NULL if @descendant doesn't have @parent as
23074 * prefix. The returned string should be freed with g_free() when
23075 * no longer needed.
23081 * @file: input #GFile
23083 * Gets the URI for the @file.
23085 * This call does no blocking I/O.
23087 * Returns: a string containing the #GFile's URI.
23088 * The returned string should be freed with g_free()
23089 * when no longer needed.
23094 * g_file_get_uri_scheme:
23095 * @file: input #GFile
23097 * Gets the URI scheme for a #GFile.
23098 * RFC 3986 decodes the scheme as:
23100 * URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
23102 * Common schemes include "file", "http", "ftp", etc.
23104 * This call does no blocking I/O.
23106 * Returns: a string containing the URI scheme for the given
23107 * #GFile. The returned string should be freed with g_free()
23108 * when no longer needed.
23113 * g_file_has_parent:
23114 * @file: input #GFile
23115 * @parent: (allow-none): the parent to check for, or %NULL
23117 * Checks if @file has a parent, and optionally, if it is @parent.
23119 * If @parent is %NULL then this function returns %TRUE if @file has any
23120 * parent at all. If @parent is non-%NULL then %TRUE is only returned
23121 * if @file is an immediate child of @parent.
23123 * Returns: %TRUE if @file is an immediate child of @parent (or any parent in
23124 * the case that @parent is %NULL).
23130 * g_file_has_prefix: (virtual prefix_matches)
23131 * @file: input #GFile
23132 * @prefix: input #GFile
23134 * Checks whether @file has the prefix specified by @prefix.
23136 * In other words, if the names of initial elements of @file's
23137 * pathname match @prefix. Only full pathname elements are matched,
23138 * so a path like /foo is not considered a prefix of /foobar, only
23141 * A #GFile is not a prefix of itself. If you want to check for
23142 * equality, use g_file_equal().
23144 * This call does no I/O, as it works purely on names. As such it can
23145 * sometimes return %FALSE even if @file is inside a @prefix (from a
23146 * filesystem point of view), because the prefix of @file is an alias
23149 * Returns: %TRUE if the @files's parent, grandparent, etc is @prefix,
23150 * %FALSE otherwise.
23155 * g_file_has_uri_scheme:
23156 * @file: input #GFile
23157 * @uri_scheme: a string containing a URI scheme
23159 * Checks to see if a #GFile has a given URI scheme.
23161 * This call does no blocking I/O.
23163 * Returns: %TRUE if #GFile's backend supports the
23164 * given URI scheme, %FALSE if URI scheme is %NULL,
23165 * not supported, or #GFile is invalid.
23170 * g_file_hash: (virtual hash)
23171 * @file: (type GFile): #gconstpointer to a #GFile
23173 * Creates a hash value for a #GFile.
23175 * This call does no blocking I/O.
23177 * Returns: 0 if @file is not a valid #GFile, otherwise an
23178 * integer that can be used as hash value for the #GFile.
23179 * This function is intended for easily hashing a #GFile to
23180 * add to a #GHashTable or similar data structure.
23185 * g_file_icon_get_file:
23188 * Gets the #GFile associated with the given @icon.
23190 * Returns: (transfer none): a #GFile, or %NULL.
23198 * Creates a new icon for a file.
23200 * Returns: (transfer full) (type GFileIcon): a #GIcon for the given
23201 * @file, or %NULL on error.
23206 * g_file_info_clear_status:
23207 * @info: a #GFileInfo.
23209 * Clears the status information from @info.
23214 * g_file_info_copy_into:
23215 * @src_info: source to copy attributes from.
23216 * @dest_info: destination to copy attributes to.
23218 * First clears all of the [GFileAttribute][gio-GFileAttribute] of @dest_info,
23219 * and then copies all of the file attributes from @src_info to @dest_info.
23225 * @other: a #GFileInfo.
23227 * Duplicates a file info structure.
23229 * Returns: (transfer full): a duplicate #GFileInfo of @other.
23234 * g_file_info_get_attribute_as_string:
23235 * @info: a #GFileInfo.
23236 * @attribute: a file attribute key.
23238 * Gets the value of a attribute, formated as a string.
23239 * This escapes things as needed to make the string valid
23242 * Returns: a UTF-8 string associated with the given @attribute.
23243 * When you're done with the string it must be freed with g_free().
23248 * g_file_info_get_attribute_boolean:
23249 * @info: a #GFileInfo.
23250 * @attribute: a file attribute key.
23252 * Gets the value of a boolean attribute. If the attribute does not
23253 * contain a boolean value, %FALSE will be returned.
23255 * Returns: the boolean value contained within the attribute.
23260 * g_file_info_get_attribute_byte_string:
23261 * @info: a #GFileInfo.
23262 * @attribute: a file attribute key.
23264 * Gets the value of a byte string attribute. If the attribute does
23265 * not contain a byte string, %NULL will be returned.
23267 * Returns: the contents of the @attribute value as a byte string, or
23273 * g_file_info_get_attribute_data:
23274 * @info: a #GFileInfo
23275 * @attribute: a file attribute key
23276 * @type: (out) (optional): return location for the attribute type, or %NULL
23277 * @value_pp: (out) (optional) (not nullable): return location for the
23278 * attribute value, or %NULL; the attribute value will not be %NULL
23279 * @status: (out) (optional): return location for the attribute status, or %NULL
23281 * Gets the attribute type, value and status for an attribute key.
23283 * Returns: (transfer none): %TRUE if @info has an attribute named @attribute,
23284 * %FALSE otherwise.
23289 * g_file_info_get_attribute_int32:
23290 * @info: a #GFileInfo.
23291 * @attribute: a file attribute key.
23293 * Gets a signed 32-bit integer contained within the attribute. If the
23294 * attribute does not contain a signed 32-bit integer, or is invalid,
23295 * 0 will be returned.
23297 * Returns: a signed 32-bit integer from the attribute.
23302 * g_file_info_get_attribute_int64:
23303 * @info: a #GFileInfo.
23304 * @attribute: a file attribute key.
23306 * Gets a signed 64-bit integer contained within the attribute. If the
23307 * attribute does not contain an signed 64-bit integer, or is invalid,
23308 * 0 will be returned.
23310 * Returns: a signed 64-bit integer from the attribute.
23315 * g_file_info_get_attribute_object:
23316 * @info: a #GFileInfo.
23317 * @attribute: a file attribute key.
23319 * Gets the value of a #GObject attribute. If the attribute does
23320 * not contain a #GObject, %NULL will be returned.
23322 * Returns: (transfer none): a #GObject associated with the given @attribute, or
23328 * g_file_info_get_attribute_status:
23329 * @info: a #GFileInfo
23330 * @attribute: a file attribute key
23332 * Gets the attribute status for an attribute key.
23334 * Returns: a #GFileAttributeStatus for the given @attribute, or
23335 * %G_FILE_ATTRIBUTE_STATUS_UNSET if the key is invalid.
23340 * g_file_info_get_attribute_string:
23341 * @info: a #GFileInfo.
23342 * @attribute: a file attribute key.
23344 * Gets the value of a string attribute. If the attribute does
23345 * not contain a string, %NULL will be returned.
23347 * Returns: the contents of the @attribute value as a UTF-8 string, or
23353 * g_file_info_get_attribute_stringv:
23354 * @info: a #GFileInfo.
23355 * @attribute: a file attribute key.
23357 * Gets the value of a stringv attribute. If the attribute does
23358 * not contain a stringv, %NULL will be returned.
23360 * Returns: (transfer none): the contents of the @attribute value as a stringv, or
23361 * %NULL otherwise. Do not free. These returned strings are UTF-8.
23367 * g_file_info_get_attribute_type:
23368 * @info: a #GFileInfo.
23369 * @attribute: a file attribute key.
23371 * Gets the attribute type for an attribute key.
23373 * Returns: a #GFileAttributeType for the given @attribute, or
23374 * %G_FILE_ATTRIBUTE_TYPE_INVALID if the key is not set.
23379 * g_file_info_get_attribute_uint32:
23380 * @info: a #GFileInfo.
23381 * @attribute: a file attribute key.
23383 * Gets an unsigned 32-bit integer contained within the attribute. If the
23384 * attribute does not contain an unsigned 32-bit integer, or is invalid,
23385 * 0 will be returned.
23387 * Returns: an unsigned 32-bit integer from the attribute.
23392 * g_file_info_get_attribute_uint64:
23393 * @info: a #GFileInfo.
23394 * @attribute: a file attribute key.
23396 * Gets a unsigned 64-bit integer contained within the attribute. If the
23397 * attribute does not contain an unsigned 64-bit integer, or is invalid,
23398 * 0 will be returned.
23400 * Returns: a unsigned 64-bit integer from the attribute.
23405 * g_file_info_get_content_type:
23406 * @info: a #GFileInfo.
23408 * Gets the file's content type.
23410 * Returns: a string containing the file's content type.
23415 * g_file_info_get_deletion_date:
23416 * @info: a #GFileInfo.
23418 * Returns the #GDateTime representing the deletion date of the file, as
23419 * available in G_FILE_ATTRIBUTE_TRASH_DELETION_DATE. If the
23420 * G_FILE_ATTRIBUTE_TRASH_DELETION_DATE attribute is unset, %NULL is returned.
23422 * Returns: a #GDateTime, or %NULL.
23428 * g_file_info_get_display_name:
23429 * @info: a #GFileInfo.
23431 * Gets a display name for a file.
23433 * Returns: a string containing the display name.
23438 * g_file_info_get_edit_name:
23439 * @info: a #GFileInfo.
23441 * Gets the edit name for a file.
23443 * Returns: a string containing the edit name.
23448 * g_file_info_get_etag:
23449 * @info: a #GFileInfo.
23451 * Gets the [entity tag][gfile-etag] for a given
23452 * #GFileInfo. See %G_FILE_ATTRIBUTE_ETAG_VALUE.
23454 * Returns: a string containing the value of the "etag:value" attribute.
23459 * g_file_info_get_file_type:
23460 * @info: a #GFileInfo.
23462 * Gets a file's type (whether it is a regular file, symlink, etc).
23463 * This is different from the file's content type, see g_file_info_get_content_type().
23465 * Returns: a #GFileType for the given file.
23470 * g_file_info_get_icon:
23471 * @info: a #GFileInfo.
23473 * Gets the icon for a file.
23475 * Returns: (transfer none): #GIcon for the given @info.
23480 * g_file_info_get_is_backup:
23481 * @info: a #GFileInfo.
23483 * Checks if a file is a backup file.
23485 * Returns: %TRUE if file is a backup file, %FALSE otherwise.
23490 * g_file_info_get_is_hidden:
23491 * @info: a #GFileInfo.
23493 * Checks if a file is hidden.
23495 * Returns: %TRUE if the file is a hidden file, %FALSE otherwise.
23500 * g_file_info_get_is_symlink:
23501 * @info: a #GFileInfo.
23503 * Checks if a file is a symlink.
23505 * Returns: %TRUE if the given @info is a symlink.
23510 * g_file_info_get_modification_time:
23511 * @info: a #GFileInfo.
23512 * @result: (out caller-allocates): a #GTimeVal.
23514 * Gets the modification time of the current @info and sets it
23520 * g_file_info_get_name:
23521 * @info: a #GFileInfo.
23523 * Gets the name for a file.
23525 * Returns: (type filename): a string containing the file name.
23530 * g_file_info_get_size:
23531 * @info: a #GFileInfo.
23533 * Gets the file's size.
23535 * Returns: a #goffset containing the file's size.
23540 * g_file_info_get_sort_order:
23541 * @info: a #GFileInfo.
23543 * Gets the value of the sort_order attribute from the #GFileInfo.
23544 * See %G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER.
23546 * Returns: a #gint32 containing the value of the "standard::sort_order" attribute.
23551 * g_file_info_get_symbolic_icon:
23552 * @info: a #GFileInfo.
23554 * Gets the symbolic icon for a file.
23556 * Returns: (transfer none): #GIcon for the given @info.
23562 * g_file_info_get_symlink_target:
23563 * @info: a #GFileInfo.
23565 * Gets the symlink target for a given #GFileInfo.
23567 * Returns: a string containing the symlink target.
23572 * g_file_info_has_attribute:
23573 * @info: a #GFileInfo.
23574 * @attribute: a file attribute key.
23576 * Checks if a file info structure has an attribute named @attribute.
23578 * Returns: %TRUE if @Ginfo has an attribute named @attribute,
23579 * %FALSE otherwise.
23584 * g_file_info_has_namespace:
23585 * @info: a #GFileInfo.
23586 * @name_space: a file attribute namespace.
23588 * Checks if a file info structure has an attribute in the
23589 * specified @name_space.
23591 * Returns: %TRUE if @Ginfo has an attribute in @name_space,
23592 * %FALSE otherwise.
23598 * g_file_info_list_attributes:
23599 * @info: a #GFileInfo.
23600 * @name_space: (nullable): a file attribute key's namespace, or %NULL to list
23603 * Lists the file info structure's attributes.
23605 * Returns: (nullable) (array zero-terminated=1) (transfer full): a
23606 * null-terminated array of strings of all of the possible attribute
23607 * types for the given @name_space, or %NULL on error.
23614 * Creates a new file info structure.
23616 * Returns: a #GFileInfo.
23621 * g_file_info_remove_attribute:
23622 * @info: a #GFileInfo.
23623 * @attribute: a file attribute key.
23625 * Removes all cases of @attribute from @info if it exists.
23630 * g_file_info_set_attribute:
23631 * @info: a #GFileInfo.
23632 * @attribute: a file attribute key.
23633 * @type: a #GFileAttributeType
23634 * @value_p: (not nullable): pointer to the value
23636 * Sets the @attribute to contain the given value, if possible. To unset the
23637 * attribute, use %G_ATTRIBUTE_TYPE_INVALID for @type.
23642 * g_file_info_set_attribute_boolean:
23643 * @info: a #GFileInfo.
23644 * @attribute: a file attribute key.
23645 * @attr_value: a boolean value.
23647 * Sets the @attribute to contain the given @attr_value,
23653 * g_file_info_set_attribute_byte_string:
23654 * @info: a #GFileInfo.
23655 * @attribute: a file attribute key.
23656 * @attr_value: a byte string.
23658 * Sets the @attribute to contain the given @attr_value,
23664 * g_file_info_set_attribute_int32:
23665 * @info: a #GFileInfo.
23666 * @attribute: a file attribute key.
23667 * @attr_value: a signed 32-bit integer
23669 * Sets the @attribute to contain the given @attr_value,
23675 * g_file_info_set_attribute_int64:
23676 * @info: a #GFileInfo.
23677 * @attribute: attribute name to set.
23678 * @attr_value: int64 value to set attribute to.
23680 * Sets the @attribute to contain the given @attr_value,
23686 * g_file_info_set_attribute_mask:
23687 * @info: a #GFileInfo.
23688 * @mask: a #GFileAttributeMatcher.
23690 * Sets @mask on @info to match specific attribute types.
23695 * g_file_info_set_attribute_object:
23696 * @info: a #GFileInfo.
23697 * @attribute: a file attribute key.
23698 * @attr_value: a #GObject.
23700 * Sets the @attribute to contain the given @attr_value,
23706 * g_file_info_set_attribute_status:
23707 * @info: a #GFileInfo
23708 * @attribute: a file attribute key
23709 * @status: a #GFileAttributeStatus
23711 * Sets the attribute status for an attribute key. This is only
23712 * needed by external code that implement g_file_set_attributes_from_info()
23713 * or similar functions.
23715 * The attribute must exist in @info for this to work. Otherwise %FALSE
23716 * is returned and @info is unchanged.
23718 * Returns: %TRUE if the status was changed, %FALSE if the key was not set.
23724 * g_file_info_set_attribute_string:
23725 * @info: a #GFileInfo.
23726 * @attribute: a file attribute key.
23727 * @attr_value: a UTF-8 string.
23729 * Sets the @attribute to contain the given @attr_value,
23735 * g_file_info_set_attribute_stringv:
23736 * @info: a #GFileInfo.
23737 * @attribute: a file attribute key
23738 * @attr_value: (array) (element-type utf8): a %NULL terminated array of UTF-8 strings.
23740 * Sets the @attribute to contain the given @attr_value,
23748 * g_file_info_set_attribute_uint32:
23749 * @info: a #GFileInfo.
23750 * @attribute: a file attribute key.
23751 * @attr_value: an unsigned 32-bit integer.
23753 * Sets the @attribute to contain the given @attr_value,
23759 * g_file_info_set_attribute_uint64:
23760 * @info: a #GFileInfo.
23761 * @attribute: a file attribute key.
23762 * @attr_value: an unsigned 64-bit integer.
23764 * Sets the @attribute to contain the given @attr_value,
23770 * g_file_info_set_content_type:
23771 * @info: a #GFileInfo.
23772 * @content_type: a content type. See [GContentType][gio-GContentType]
23774 * Sets the content type attribute for a given #GFileInfo.
23775 * See %G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE.
23780 * g_file_info_set_display_name:
23781 * @info: a #GFileInfo.
23782 * @display_name: a string containing a display name.
23784 * Sets the display name for the current #GFileInfo.
23785 * See %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME.
23790 * g_file_info_set_edit_name:
23791 * @info: a #GFileInfo.
23792 * @edit_name: a string containing an edit name.
23794 * Sets the edit name for the current file.
23795 * See %G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME.
23800 * g_file_info_set_file_type:
23801 * @info: a #GFileInfo.
23802 * @type: a #GFileType.
23804 * Sets the file type in a #GFileInfo to @type.
23805 * See %G_FILE_ATTRIBUTE_STANDARD_TYPE.
23810 * g_file_info_set_icon:
23811 * @info: a #GFileInfo.
23814 * Sets the icon for a given #GFileInfo.
23815 * See %G_FILE_ATTRIBUTE_STANDARD_ICON.
23820 * g_file_info_set_is_hidden:
23821 * @info: a #GFileInfo.
23822 * @is_hidden: a #gboolean.
23824 * Sets the "is_hidden" attribute in a #GFileInfo according to @is_hidden.
23825 * See %G_FILE_ATTRIBUTE_STANDARD_IS_HIDDEN.
23830 * g_file_info_set_is_symlink:
23831 * @info: a #GFileInfo.
23832 * @is_symlink: a #gboolean.
23834 * Sets the "is_symlink" attribute in a #GFileInfo according to @is_symlink.
23835 * See %G_FILE_ATTRIBUTE_STANDARD_IS_SYMLINK.
23840 * g_file_info_set_modification_time:
23841 * @info: a #GFileInfo.
23842 * @mtime: a #GTimeVal.
23844 * Sets the %G_FILE_ATTRIBUTE_TIME_MODIFIED attribute in the file
23845 * info to the given time value.
23850 * g_file_info_set_name:
23851 * @info: a #GFileInfo.
23852 * @name: (type filename): a string containing a name.
23854 * Sets the name attribute for the current #GFileInfo.
23855 * See %G_FILE_ATTRIBUTE_STANDARD_NAME.
23860 * g_file_info_set_size:
23861 * @info: a #GFileInfo.
23862 * @size: a #goffset containing the file's size.
23864 * Sets the %G_FILE_ATTRIBUTE_STANDARD_SIZE attribute in the file info
23865 * to the given size.
23870 * g_file_info_set_sort_order:
23871 * @info: a #GFileInfo.
23872 * @sort_order: a sort order integer.
23874 * Sets the sort order attribute in the file info structure. See
23875 * %G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER.
23880 * g_file_info_set_symbolic_icon:
23881 * @info: a #GFileInfo.
23884 * Sets the symbolic icon for a given #GFileInfo.
23885 * See %G_FILE_ATTRIBUTE_STANDARD_SYMBOLIC_ICON.
23892 * g_file_info_set_symlink_target:
23893 * @info: a #GFileInfo.
23894 * @symlink_target: a static string containing a path to a symlink target.
23896 * Sets the %G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET attribute in the file info
23897 * to the given symlink target.
23902 * g_file_info_unset_attribute_mask:
23903 * @info: #GFileInfo.
23905 * Unsets a mask set by g_file_info_set_attribute_mask(), if one
23911 * g_file_input_stream_query_info:
23912 * @stream: a #GFileInputStream.
23913 * @attributes: a file attribute query string.
23914 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
23915 * @error: a #GError location to store the error occurring, or %NULL to
23918 * Queries a file input stream the given @attributes. This function blocks
23919 * while querying the stream. For the asynchronous (non-blocking) version
23920 * of this function, see g_file_input_stream_query_info_async(). While the
23921 * stream is blocked, the stream will set the pending flag internally, and
23922 * any other operations on the stream will fail with %G_IO_ERROR_PENDING.
23924 * Returns: (transfer full): a #GFileInfo, or %NULL on error.
23929 * g_file_input_stream_query_info_async:
23930 * @stream: a #GFileInputStream.
23931 * @attributes: a file attribute query string.
23932 * @io_priority: the [I/O priority][io-priority] of the request
23933 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
23934 * @callback: (scope async): callback to call when the request is satisfied
23935 * @user_data: (closure): the data to pass to callback function
23937 * Queries the stream information asynchronously.
23938 * When the operation is finished @callback will be called.
23939 * You can then call g_file_input_stream_query_info_finish()
23940 * to get the result of the operation.
23942 * For the synchronous version of this function,
23943 * see g_file_input_stream_query_info().
23945 * If @cancellable is not %NULL, then the operation can be cancelled by
23946 * triggering the cancellable object from another thread. If the operation
23947 * was cancelled, the error %G_IO_ERROR_CANCELLED will be set
23952 * g_file_input_stream_query_info_finish:
23953 * @stream: a #GFileInputStream.
23954 * @result: a #GAsyncResult.
23955 * @error: a #GError location to store the error occurring,
23956 * or %NULL to ignore.
23958 * Finishes an asynchronous info query operation.
23960 * Returns: (transfer full): #GFileInfo.
23965 * g_file_io_stream_get_etag:
23966 * @stream: a #GFileIOStream.
23968 * Gets the entity tag for the file when it has been written.
23969 * This must be called after the stream has been written
23970 * and closed, as the etag can change while writing.
23972 * Returns: the entity tag for the stream.
23978 * g_file_io_stream_query_info:
23979 * @stream: a #GFileIOStream.
23980 * @attributes: a file attribute query string.
23981 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
23982 * @error: a #GError, %NULL to ignore.
23984 * Queries a file io stream for the given @attributes.
23985 * This function blocks while querying the stream. For the asynchronous
23986 * version of this function, see g_file_io_stream_query_info_async().
23987 * While the stream is blocked, the stream will set the pending flag
23988 * internally, and any other operations on the stream will fail with
23989 * %G_IO_ERROR_PENDING.
23991 * Can fail if the stream was already closed (with @error being set to
23992 * %G_IO_ERROR_CLOSED), the stream has pending operations (with @error being
23993 * set to %G_IO_ERROR_PENDING), or if querying info is not supported for
23994 * the stream's interface (with @error being set to %G_IO_ERROR_NOT_SUPPORTED). I
23995 * all cases of failure, %NULL will be returned.
23997 * If @cancellable is not %NULL, then the operation can be cancelled by
23998 * triggering the cancellable object from another thread. If the operation
23999 * was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %NULL will
24002 * Returns: (transfer full): a #GFileInfo for the @stream, or %NULL on error.
24008 * g_file_io_stream_query_info_async:
24009 * @stream: a #GFileIOStream.
24010 * @attributes: a file attribute query string.
24011 * @io_priority: the [I/O priority][gio-GIOScheduler] of the request
24012 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
24013 * @callback: (scope async): callback to call when the request is satisfied
24014 * @user_data: (closure): the data to pass to callback function
24016 * Asynchronously queries the @stream for a #GFileInfo. When completed,
24017 * @callback will be called with a #GAsyncResult which can be used to
24018 * finish the operation with g_file_io_stream_query_info_finish().
24020 * For the synchronous version of this function, see
24021 * g_file_io_stream_query_info().
24028 * g_file_io_stream_query_info_finish:
24029 * @stream: a #GFileIOStream.
24030 * @result: a #GAsyncResult.
24031 * @error: a #GError, %NULL to ignore.
24033 * Finalizes the asynchronous query started
24034 * by g_file_io_stream_query_info_async().
24036 * Returns: (transfer full): A #GFileInfo for the finished query.
24042 * g_file_is_native:
24043 * @file: input #GFile
24045 * Checks to see if a file is native to the platform.
24047 * A native file s one expressed in the platform-native filename format,
24048 * e.g. "C:\Windows" or "/usr/bin/". This does not mean the file is local,
24049 * as it might be on a locally mounted remote filesystem.
24051 * On some systems non-native files may be available using the native
24052 * filesystem via a userspace filesystem (FUSE), in these cases this call
24053 * will return %FALSE, but g_file_get_path() will still return a native path.
24055 * This call does no blocking I/O.
24057 * Returns: %TRUE if @file is native
24062 * g_file_load_contents:
24063 * @file: input #GFile
24064 * @cancellable: optional #GCancellable object, %NULL to ignore
24065 * @contents: (out) (transfer full) (element-type guint8) (array length=length): a location to place the contents of the file
24066 * @length: (out) (allow-none): a location to place the length of the contents of the file,
24067 * or %NULL if the length is not needed
24068 * @etag_out: (out) (allow-none): a location to place the current entity tag for the file,
24069 * or %NULL if the entity tag is not needed
24070 * @error: a #GError, or %NULL
24072 * Loads the content of the file into memory. The data is always
24073 * zero-terminated, but this is not included in the resultant @length.
24074 * The returned @content should be freed with g_free() when no longer
24077 * If @cancellable is not %NULL, then the operation can be cancelled by
24078 * triggering the cancellable object from another thread. If the operation
24079 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
24081 * Returns: %TRUE if the @file's contents were successfully loaded.
24082 * %FALSE if there were errors.
24087 * g_file_load_contents_async:
24088 * @file: input #GFile
24089 * @cancellable: optional #GCancellable object, %NULL to ignore
24090 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
24091 * @user_data: the data to pass to callback function
24093 * Starts an asynchronous load of the @file's contents.
24095 * For more details, see g_file_load_contents() which is
24096 * the synchronous version of this call.
24098 * When the load operation has completed, @callback will be called
24099 * with @user data. To finish the operation, call
24100 * g_file_load_contents_finish() with the #GAsyncResult returned by
24103 * If @cancellable is not %NULL, then the operation can be cancelled by
24104 * triggering the cancellable object from another thread. If the operation
24105 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
24110 * g_file_load_contents_finish:
24111 * @file: input #GFile
24112 * @res: a #GAsyncResult
24113 * @contents: (out) (transfer full) (element-type guint8) (array length=length): a location to place the contents of the file
24114 * @length: (out) (allow-none): a location to place the length of the contents of the file,
24115 * or %NULL if the length is not needed
24116 * @etag_out: (out) (allow-none): a location to place the current entity tag for the file,
24117 * or %NULL if the entity tag is not needed
24118 * @error: a #GError, or %NULL
24120 * Finishes an asynchronous load of the @file's contents.
24121 * The contents are placed in @contents, and @length is set to the
24122 * size of the @contents string. The @content should be freed with
24123 * g_free() when no longer needed. If @etag_out is present, it will be
24124 * set to the new entity tag for the @file.
24126 * Returns: %TRUE if the load was successful. If %FALSE and @error is
24127 * present, it will be set appropriately.
24132 * g_file_load_partial_contents_async: (skip)
24133 * @file: input #GFile
24134 * @cancellable: optional #GCancellable object, %NULL to ignore
24135 * @read_more_callback: a #GFileReadMoreCallback to receive partial data
24136 * and to specify whether further data should be read
24137 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
24138 * @user_data: the data to pass to the callback functions
24140 * Reads the partial contents of a file. A #GFileReadMoreCallback should
24141 * be used to stop reading from the file when appropriate, else this
24142 * function will behave exactly as g_file_load_contents_async(). This
24143 * operation can be finished by g_file_load_partial_contents_finish().
24145 * Users of this function should be aware that @user_data is passed to
24146 * both the @read_more_callback and the @callback.
24148 * If @cancellable is not %NULL, then the operation can be cancelled by
24149 * triggering the cancellable object from another thread. If the operation
24150 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
24155 * g_file_load_partial_contents_finish:
24156 * @file: input #GFile
24157 * @res: a #GAsyncResult
24158 * @contents: (out) (transfer full) (element-type guint8) (array length=length): a location to place the contents of the file
24159 * @length: (out) (allow-none): a location to place the length of the contents of the file,
24160 * or %NULL if the length is not needed
24161 * @etag_out: (out) (allow-none): a location to place the current entity tag for the file,
24162 * or %NULL if the entity tag is not needed
24163 * @error: a #GError, or %NULL
24165 * Finishes an asynchronous partial load operation that was started
24166 * with g_file_load_partial_contents_async(). The data is always
24167 * zero-terminated, but this is not included in the resultant @length.
24168 * The returned @content should be freed with g_free() when no longer
24171 * Returns: %TRUE if the load was successful. If %FALSE and @error is
24172 * present, it will be set appropriately.
24177 * g_file_make_directory:
24178 * @file: input #GFile
24179 * @cancellable: (allow-none): optional #GCancellable object,
24181 * @error: a #GError, or %NULL
24183 * Creates a directory. Note that this will only create a child directory
24184 * of the immediate parent directory of the path or URI given by the #GFile.
24185 * To recursively create directories, see g_file_make_directory_with_parents().
24186 * This function will fail if the parent directory does not exist, setting
24187 * @error to %G_IO_ERROR_NOT_FOUND. If the file system doesn't support
24188 * creating directories, this function will fail, setting @error to
24189 * %G_IO_ERROR_NOT_SUPPORTED.
24191 * For a local #GFile the newly created directory will have the default
24192 * (current) ownership and permissions of the current process.
24194 * If @cancellable is not %NULL, then the operation can be cancelled by
24195 * triggering the cancellable object from another thread. If the operation
24196 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
24198 * Returns: %TRUE on successful creation, %FALSE otherwise.
24203 * g_file_make_directory_async: (virtual make_directory_async)
24204 * @file: input #GFile
24205 * @io_priority: the [I/O priority][io-priority] of the request
24206 * @cancellable: (allow-none): optional #GCancellable object,
24208 * @callback: a #GAsyncReadyCallback to call
24209 * when the request is satisfied
24210 * @user_data: the data to pass to callback function
24212 * Asynchronously creates a directory.
24219 * g_file_make_directory_finish: (virtual make_directory_finish)
24220 * @file: input #GFile
24221 * @result: a #GAsyncResult
24222 * @error: a #GError, or %NULL
24224 * Finishes an asynchronous directory creation, started with
24225 * g_file_make_directory_async().
24227 * Returns: %TRUE on successful directory creation, %FALSE otherwise.
24233 * g_file_make_directory_with_parents:
24234 * @file: input #GFile
24235 * @cancellable: (allow-none): optional #GCancellable object,
24237 * @error: a #GError, or %NULL
24239 * Creates a directory and any parent directories that may not
24240 * exist similar to 'mkdir -p'. If the file system does not support
24241 * creating directories, this function will fail, setting @error to
24242 * %G_IO_ERROR_NOT_SUPPORTED. If the directory itself already exists,
24243 * this function will fail setting @error to %G_IO_ERROR_EXISTS, unlike
24244 * the similar g_mkdir_with_parents().
24246 * For a local #GFile the newly created directories will have the default
24247 * (current) ownership and permissions of the current process.
24249 * If @cancellable is not %NULL, then the operation can be cancelled by
24250 * triggering the cancellable object from another thread. If the operation
24251 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
24253 * Returns: %TRUE if all directories have been successfully created, %FALSE
24260 * g_file_make_symbolic_link:
24261 * @file: a #GFile with the name of the symlink to create
24262 * @symlink_value: (type filename): a string with the path for the target
24263 * of the new symlink
24264 * @cancellable: (allow-none): optional #GCancellable object,
24266 * @error: a #GError
24268 * Creates a symbolic link named @file which contains the string
24271 * If @cancellable is not %NULL, then the operation can be cancelled by
24272 * triggering the cancellable object from another thread. If the operation
24273 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
24275 * Returns: %TRUE on the creation of a new symlink, %FALSE otherwise.
24280 * g_file_measure_disk_usage:
24282 * @flags: #GFileMeasureFlags
24283 * @cancellable: (allow-none): optional #GCancellable
24284 * @progress_callback: (allow-none): a #GFileMeasureProgressCallback
24285 * @progress_data: user_data for @progress_callback
24286 * @disk_usage: (allow-none) (out): the number of bytes of disk space used
24287 * @num_dirs: (allow-none) (out): the number of directories encountered
24288 * @num_files: (allow-none) (out): the number of non-directories encountered
24289 * @error: (allow-none): %NULL, or a pointer to a %NULL #GError pointer
24291 * Recursively measures the disk usage of @file.
24293 * This is essentially an analog of the 'du' command, but it also
24294 * reports the number of directories and non-directory files encountered
24295 * (including things like symbolic links).
24297 * By default, errors are only reported against the toplevel file
24298 * itself. Errors found while recursing are silently ignored, unless
24299 * %G_FILE_DISK_USAGE_REPORT_ALL_ERRORS is given in @flags.
24301 * The returned size, @disk_usage, is in bytes and should be formatted
24302 * with g_format_size() in order to get something reasonable for showing
24303 * in a user interface.
24305 * @progress_callback and @progress_data can be given to request
24306 * periodic progress updates while scanning. See the documentation for
24307 * #GFileMeasureProgressCallback for information about when and how the
24308 * callback will be invoked.
24310 * Returns: %TRUE if successful, with the out parameters set.
24311 * %FALSE otherwise, with @error set.
24317 * g_file_measure_disk_usage_async:
24319 * @flags: #GFileMeasureFlags
24320 * @io_priority: the [I/O priority][io-priority] of the request
24321 * @cancellable: (allow-none): optional #GCancellable
24322 * @progress_callback: (allow-none): a #GFileMeasureProgressCallback
24323 * @progress_data: user_data for @progress_callback
24324 * @callback: (allow-none): a #GAsyncReadyCallback to call when complete
24325 * @user_data: the data to pass to callback function
24327 * Recursively measures the disk usage of @file.
24329 * This is the asynchronous version of g_file_measure_disk_usage(). See
24330 * there for more information.
24337 * g_file_measure_disk_usage_finish:
24339 * @result: the #GAsyncResult passed to your #GAsyncReadyCallback
24340 * @disk_usage: (allow-none) (out): the number of bytes of disk space used
24341 * @num_dirs: (allow-none) (out): the number of directories encountered
24342 * @num_files: (allow-none) (out): the number of non-directories encountered
24343 * @error: (allow-none): %NULL, or a pointer to a %NULL #GError pointer
24345 * Collects the results from an earlier call to
24346 * g_file_measure_disk_usage_async(). See g_file_measure_disk_usage() for
24347 * more information.
24349 * Returns: %TRUE if successful, with the out parameters set.
24350 * %FALSE otherwise, with @error set.
24357 * @file: input #GFile
24358 * @flags: a set of #GFileMonitorFlags
24359 * @cancellable: (allow-none): optional #GCancellable object,
24361 * @error: a #GError, or %NULL
24363 * Obtains a file or directory monitor for the given file,
24364 * depending on the type of the file.
24366 * If @cancellable is not %NULL, then the operation can be cancelled by
24367 * triggering the cancellable object from another thread. If the operation
24368 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
24370 * Returns: (transfer full): a #GFileMonitor for the given @file,
24371 * or %NULL on error.
24372 * Free the returned object with g_object_unref().
24378 * g_file_monitor_cancel:
24379 * @monitor: a #GFileMonitor.
24381 * Cancels a file monitor.
24383 * Returns: always %TRUE
24388 * g_file_monitor_directory: (virtual monitor_dir)
24389 * @file: input #GFile
24390 * @flags: a set of #GFileMonitorFlags
24391 * @cancellable: (allow-none): optional #GCancellable object,
24393 * @error: a #GError, or %NULL
24395 * Obtains a directory monitor for the given file.
24396 * This may fail if directory monitoring is not supported.
24398 * If @cancellable is not %NULL, then the operation can be cancelled by
24399 * triggering the cancellable object from another thread. If the operation
24400 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
24402 * It does not make sense for @flags to contain
24403 * %G_FILE_MONITOR_WATCH_HARD_LINKS, since hard links can not be made to
24404 * directories. It is not possible to monitor all the files in a
24405 * directory for changes made via hard links; if you want to do this then
24406 * you must register individual watches with g_file_monitor().
24408 * Returns: (transfer full): a #GFileMonitor for the given @file,
24409 * or %NULL on error.
24410 * Free the returned object with g_object_unref().
24415 * g_file_monitor_emit_event:
24416 * @monitor: a #GFileMonitor.
24417 * @child: a #GFile.
24418 * @other_file: a #GFile.
24419 * @event_type: a set of #GFileMonitorEvent flags.
24421 * Emits the #GFileMonitor::changed signal if a change
24422 * has taken place. Should be called from file monitor
24423 * implementations only.
24425 * Implementations are responsible to call this method from the
24426 * [thread-default main context][g-main-context-push-thread-default] of the
24427 * thread that the monitor was created in.
24432 * g_file_monitor_file:
24433 * @file: input #GFile
24434 * @flags: a set of #GFileMonitorFlags
24435 * @cancellable: (allow-none): optional #GCancellable object,
24437 * @error: a #GError, or %NULL
24439 * Obtains a file monitor for the given file. If no file notification
24440 * mechanism exists, then regular polling of the file is used.
24442 * If @cancellable is not %NULL, then the operation can be cancelled by
24443 * triggering the cancellable object from another thread. If the operation
24444 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
24446 * If @flags contains %G_FILE_MONITOR_WATCH_HARD_LINKS then the monitor
24447 * will also attempt to report changes made to the file via another
24448 * filename (ie, a hard link). Without this flag, you can only rely on
24449 * changes made through the filename contained in @file to be
24450 * reported. Using this flag may result in an increase in resource
24451 * usage, and may not have any effect depending on the #GFileMonitor
24452 * backend and/or filesystem type.
24454 * Returns: (transfer full): a #GFileMonitor for the given @file,
24455 * or %NULL on error.
24456 * Free the returned object with g_object_unref().
24461 * g_file_monitor_is_cancelled:
24462 * @monitor: a #GFileMonitor
24464 * Returns whether the monitor is canceled.
24466 * Returns: %TRUE if monitor is canceled. %FALSE otherwise.
24471 * g_file_monitor_set_rate_limit:
24472 * @monitor: a #GFileMonitor.
24473 * @limit_msecs: a non-negative integer with the limit in milliseconds
24474 * to poll for changes
24476 * Sets the rate limit to which the @monitor will report
24477 * consecutive change events to the same file.
24482 * g_file_mount_enclosing_volume:
24483 * @location: input #GFile
24484 * @flags: flags affecting the operation
24485 * @mount_operation: (allow-none): a #GMountOperation
24486 * or %NULL to avoid user interaction
24487 * @cancellable: (allow-none): optional #GCancellable object,
24489 * @callback: (allow-none): a #GAsyncReadyCallback to call
24490 * when the request is satisfied, or %NULL
24491 * @user_data: the data to pass to callback function
24493 * Starts a @mount_operation, mounting the volume that contains
24494 * the file @location.
24496 * When this operation has completed, @callback will be called with
24497 * @user_user data, and the operation can be finalized with
24498 * g_file_mount_enclosing_volume_finish().
24500 * If @cancellable is not %NULL, then the operation can be cancelled by
24501 * triggering the cancellable object from another thread. If the operation
24502 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
24507 * g_file_mount_enclosing_volume_finish:
24508 * @location: input #GFile
24509 * @result: a #GAsyncResult
24510 * @error: a #GError, or %NULL
24512 * Finishes a mount operation started by g_file_mount_enclosing_volume().
24514 * Returns: %TRUE if successful. If an error has occurred,
24515 * this function will return %FALSE and set @error
24516 * appropriately if present.
24521 * g_file_mount_mountable:
24522 * @file: input #GFile
24523 * @flags: flags affecting the operation
24524 * @mount_operation: (allow-none): a #GMountOperation,
24525 * or %NULL to avoid user interaction
24526 * @cancellable: (allow-none): optional #GCancellable object,
24528 * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call
24529 * when the request is satisfied, or %NULL
24530 * @user_data: (closure): the data to pass to callback function
24532 * Mounts a file of type G_FILE_TYPE_MOUNTABLE.
24533 * Using @mount_operation, you can request callbacks when, for instance,
24534 * passwords are needed during authentication.
24536 * If @cancellable is not %NULL, then the operation can be cancelled by
24537 * triggering the cancellable object from another thread. If the operation
24538 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
24540 * When the operation is finished, @callback will be called.
24541 * You can then call g_file_mount_mountable_finish() to get
24542 * the result of the operation.
24547 * g_file_mount_mountable_finish:
24548 * @file: input #GFile
24549 * @result: a #GAsyncResult
24550 * @error: a #GError, or %NULL
24552 * Finishes a mount operation. See g_file_mount_mountable() for details.
24554 * Finish an asynchronous mount operation that was started
24555 * with g_file_mount_mountable().
24557 * Returns: (transfer full): a #GFile or %NULL on error.
24558 * Free the returned object with g_object_unref().
24564 * @source: #GFile pointing to the source location
24565 * @destination: #GFile pointing to the destination location
24566 * @flags: set of #GFileCopyFlags
24567 * @cancellable: (allow-none): optional #GCancellable object,
24569 * @progress_callback: (allow-none) (scope call): #GFileProgressCallback
24570 * function for updates
24571 * @progress_callback_data: (closure): gpointer to user data for
24572 * the callback function
24573 * @error: #GError for returning error conditions, or %NULL
24575 * Tries to move the file or directory @source to the location specified
24576 * by @destination. If native move operations are supported then this is
24577 * used, otherwise a copy + delete fallback is used. The native
24578 * implementation may support moving directories (for instance on moves
24579 * inside the same filesystem), but the fallback code does not.
24581 * If the flag #G_FILE_COPY_OVERWRITE is specified an already
24582 * existing @destination file is overwritten.
24584 * If the flag #G_FILE_COPY_NOFOLLOW_SYMLINKS is specified then symlinks
24585 * will be copied as symlinks, otherwise the target of the
24586 * @source symlink will be copied.
24588 * If @cancellable is not %NULL, then the operation can be cancelled by
24589 * triggering the cancellable object from another thread. If the operation
24590 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
24592 * If @progress_callback is not %NULL, then the operation can be monitored
24593 * by setting this to a #GFileProgressCallback function.
24594 * @progress_callback_data will be passed to this function. It is
24595 * guaranteed that this callback will be called after all data has been
24596 * transferred with the total number of bytes copied during the operation.
24598 * If the @source file does not exist, then the %G_IO_ERROR_NOT_FOUND
24599 * error is returned, independent on the status of the @destination.
24601 * If #G_FILE_COPY_OVERWRITE is not specified and the target exists,
24602 * then the error %G_IO_ERROR_EXISTS is returned.
24604 * If trying to overwrite a file over a directory, the %G_IO_ERROR_IS_DIRECTORY
24605 * error is returned. If trying to overwrite a directory with a directory the
24606 * %G_IO_ERROR_WOULD_MERGE error is returned.
24608 * If the source is a directory and the target does not exist, or
24609 * #G_FILE_COPY_OVERWRITE is specified and the target is a file, then
24610 * the %G_IO_ERROR_WOULD_RECURSE error may be returned (if the native
24611 * move operation isn't available).
24613 * Returns: %TRUE on successful move, %FALSE otherwise.
24618 * g_file_new_for_commandline_arg:
24619 * @arg: a command line string
24621 * Creates a #GFile with the given argument from the command line.
24622 * The value of @arg can be either a URI, an absolute path or a
24623 * relative path resolved relative to the current working directory.
24624 * This operation never fails, but the returned object might not
24625 * support any I/O operation if @arg points to a malformed path.
24627 * Note that on Windows, this function expects its argument to be in
24628 * UTF-8 -- not the system code page. This means that you
24629 * should not use this function with string from argv as it is passed
24630 * to main(). g_win32_get_command_line() will return a UTF-8 version of
24631 * the commandline. #GApplication also uses UTF-8 but
24632 * g_application_command_line_create_file_for_arg() may be more useful
24633 * for you there. It is also always possible to use this function with
24634 * #GOptionContext arguments of type %G_OPTION_ARG_FILENAME.
24636 * Returns: (transfer full): a new #GFile.
24637 * Free the returned object with g_object_unref().
24642 * g_file_new_for_commandline_arg_and_cwd:
24643 * @arg: a command line string
24644 * @cwd: (type filename): the current working directory of the commandline
24646 * Creates a #GFile with the given argument from the command line.
24648 * This function is similar to g_file_new_for_commandline_arg() except
24649 * that it allows for passing the current working directory as an
24650 * argument instead of using the current working directory of the
24653 * This is useful if the commandline argument was given in a context
24654 * other than the invocation of the current process.
24656 * See also g_application_command_line_create_file_for_arg().
24658 * Returns: (transfer full): a new #GFile
24664 * g_file_new_for_path:
24665 * @path: (type filename): a string containing a relative or absolute path.
24666 * The string must be encoded in the glib filename encoding.
24668 * Constructs a #GFile for a given path. This operation never
24669 * fails, but the returned object might not support any I/O
24670 * operation if @path is malformed.
24672 * Returns: (transfer full): a new #GFile for the given @path.
24673 * Free the returned object with g_object_unref().
24678 * g_file_new_for_uri:
24679 * @uri: a UTF-8 string containing a URI
24681 * Constructs a #GFile for a given URI. This operation never
24682 * fails, but the returned object might not support any I/O
24683 * operation if @uri is malformed or if the uri type is
24686 * Returns: (transfer full): a new #GFile for the given @uri.
24687 * Free the returned object with g_object_unref().
24693 * @tmpl: (type filename) (allow-none): Template for the file
24694 * name, as in g_file_open_tmp(), or %NULL for a default template
24695 * @iostream: (out): on return, a #GFileIOStream for the created file
24696 * @error: a #GError, or %NULL
24698 * Opens a file in the preferred directory for temporary files (as
24699 * returned by g_get_tmp_dir()) and returns a #GFile and
24700 * #GFileIOStream pointing to it.
24702 * @tmpl should be a string in the GLib file name encoding
24703 * containing a sequence of six 'X' characters, and containing no
24704 * directory components. If it is %NULL, a default template is used.
24706 * Unlike the other #GFile constructors, this will return %NULL if
24707 * a temporary file could not be created.
24709 * Returns: (transfer full): a new #GFile.
24710 * Free the returned object with g_object_unref().
24716 * g_file_open_readwrite:
24717 * @file: #GFile to open
24718 * @cancellable: (allow-none): a #GCancellable
24719 * @error: a #GError, or %NULL
24721 * Opens an existing file for reading and writing. The result is
24722 * a #GFileIOStream that can be used to read and write the contents
24725 * If @cancellable is not %NULL, then the operation can be cancelled
24726 * by triggering the cancellable object from another thread. If the
24727 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
24730 * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will
24731 * be returned. If the file is a directory, the %G_IO_ERROR_IS_DIRECTORY
24732 * error will be returned. Other errors are possible too, and depend on
24733 * what kind of filesystem the file is on. Note that in many non-local
24734 * file cases read and write streams are not supported, so make sure you
24735 * really need to do read and write streaming, rather than just opening
24736 * for reading or writing.
24738 * Returns: (transfer full): #GFileIOStream or %NULL on error.
24739 * Free the returned object with g_object_unref().
24745 * g_file_open_readwrite_async:
24746 * @file: input #GFile
24747 * @io_priority: the [I/O priority][io-priority] of the request
24748 * @cancellable: (allow-none): optional #GCancellable object,
24750 * @callback: (scope async): a #GAsyncReadyCallback to call
24751 * when the request is satisfied
24752 * @user_data: (closure): the data to pass to callback function
24754 * Asynchronously opens @file for reading and writing.
24756 * For more details, see g_file_open_readwrite() which is
24757 * the synchronous version of this call.
24759 * When the operation is finished, @callback will be called.
24760 * You can then call g_file_open_readwrite_finish() to get
24761 * the result of the operation.
24768 * g_file_open_readwrite_finish:
24769 * @file: input #GFile
24770 * @res: a #GAsyncResult
24771 * @error: a #GError, or %NULL
24773 * Finishes an asynchronous file read operation started with
24774 * g_file_open_readwrite_async().
24776 * Returns: (transfer full): a #GFileIOStream or %NULL on error.
24777 * Free the returned object with g_object_unref().
24783 * g_file_output_stream_get_etag:
24784 * @stream: a #GFileOutputStream.
24786 * Gets the entity tag for the file when it has been written.
24787 * This must be called after the stream has been written
24788 * and closed, as the etag can change while writing.
24790 * Returns: the entity tag for the stream.
24795 * g_file_output_stream_query_info:
24796 * @stream: a #GFileOutputStream.
24797 * @attributes: a file attribute query string.
24798 * @cancellable: optional #GCancellable object, %NULL to ignore.
24799 * @error: a #GError, %NULL to ignore.
24801 * Queries a file output stream for the given @attributes.
24802 * This function blocks while querying the stream. For the asynchronous
24803 * version of this function, see g_file_output_stream_query_info_async().
24804 * While the stream is blocked, the stream will set the pending flag
24805 * internally, and any other operations on the stream will fail with
24806 * %G_IO_ERROR_PENDING.
24808 * Can fail if the stream was already closed (with @error being set to
24809 * %G_IO_ERROR_CLOSED), the stream has pending operations (with @error being
24810 * set to %G_IO_ERROR_PENDING), or if querying info is not supported for
24811 * the stream's interface (with @error being set to %G_IO_ERROR_NOT_SUPPORTED). In
24812 * all cases of failure, %NULL will be returned.
24814 * If @cancellable is not %NULL, then the operation can be cancelled by
24815 * triggering the cancellable object from another thread. If the operation
24816 * was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %NULL will
24819 * Returns: (transfer full): a #GFileInfo for the @stream, or %NULL on error.
24824 * g_file_output_stream_query_info_async:
24825 * @stream: a #GFileOutputStream.
24826 * @attributes: a file attribute query string.
24827 * @io_priority: the [I/O priority][gio-GIOScheduler] of the request
24828 * @cancellable: optional #GCancellable object, %NULL to ignore.
24829 * @callback: callback to call when the request is satisfied
24830 * @user_data: the data to pass to callback function
24832 * Asynchronously queries the @stream for a #GFileInfo. When completed,
24833 * @callback will be called with a #GAsyncResult which can be used to
24834 * finish the operation with g_file_output_stream_query_info_finish().
24836 * For the synchronous version of this function, see
24837 * g_file_output_stream_query_info().
24842 * g_file_output_stream_query_info_finish:
24843 * @stream: a #GFileOutputStream.
24844 * @result: a #GAsyncResult.
24845 * @error: a #GError, %NULL to ignore.
24847 * Finalizes the asynchronous query started
24848 * by g_file_output_stream_query_info_async().
24850 * Returns: (transfer full): A #GFileInfo for the finished query.
24855 * g_file_parse_name:
24856 * @parse_name: a file name or path to be parsed
24858 * Constructs a #GFile with the given @parse_name (i.e. something
24859 * given by g_file_get_parse_name()). This operation never fails,
24860 * but the returned object might not support any I/O operation if
24861 * the @parse_name cannot be parsed.
24863 * Returns: (transfer full): a new #GFile.
24868 * g_file_poll_mountable:
24869 * @file: input #GFile
24870 * @cancellable: optional #GCancellable object, %NULL to ignore
24871 * @callback: (allow-none): a #GAsyncReadyCallback to call
24872 * when the request is satisfied, or %NULL
24873 * @user_data: the data to pass to callback function
24875 * Polls a file of type #G_FILE_TYPE_MOUNTABLE.
24877 * If @cancellable is not %NULL, then the operation can be cancelled by
24878 * triggering the cancellable object from another thread. If the operation
24879 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
24881 * When the operation is finished, @callback will be called.
24882 * You can then call g_file_mount_mountable_finish() to get
24883 * the result of the operation.
24890 * g_file_poll_mountable_finish:
24891 * @file: input #GFile
24892 * @result: a #GAsyncResult
24893 * @error: a #GError, or %NULL
24895 * Finishes a poll operation. See g_file_poll_mountable() for details.
24897 * Finish an asynchronous poll operation that was polled
24898 * with g_file_poll_mountable().
24900 * Returns: %TRUE if the operation finished successfully. %FALSE
24907 * g_file_query_default_handler:
24908 * @file: a #GFile to open
24909 * @cancellable: optional #GCancellable object, %NULL to ignore
24910 * @error: a #GError, or %NULL
24912 * Returns the #GAppInfo that is registered as the default
24913 * application to handle the file specified by @file.
24915 * If @cancellable is not %NULL, then the operation can be cancelled by
24916 * triggering the cancellable object from another thread. If the operation
24917 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
24919 * Returns: (transfer full): a #GAppInfo if the handle was found,
24920 * %NULL if there were errors.
24921 * When you are done with it, release it with g_object_unref()
24926 * g_file_query_exists:
24927 * @file: input #GFile
24928 * @cancellable: (allow-none): optional #GCancellable object,
24931 * Utility function to check if a particular file exists. This is
24932 * implemented using g_file_query_info() and as such does blocking I/O.
24934 * Note that in many cases it is racy to first check for file existence
24935 * and then execute something based on the outcome of that, because the
24936 * file might have been created or removed in between the operations. The
24937 * general approach to handling that is to not check, but just do the
24938 * operation and handle the errors as they come.
24940 * As an example of race-free checking, take the case of reading a file,
24941 * and if it doesn't exist, creating it. There are two racy versions: read
24942 * it, and on error create it; and: check if it exists, if not create it.
24943 * These can both result in two processes creating the file (with perhaps
24944 * a partially written file as the result). The correct approach is to
24945 * always try to create the file with g_file_create() which will either
24946 * atomically create the file or fail with a %G_IO_ERROR_EXISTS error.
24948 * However, in many cases an existence check is useful in a user interface,
24949 * for instance to make a menu item sensitive/insensitive, so that you don't
24950 * have to fool users that something is possible and then just show an error
24951 * dialog. If you do this, you should make sure to also handle the errors
24952 * that can happen due to races when you execute the operation.
24954 * Returns: %TRUE if the file exists (and can be detected without error),
24955 * %FALSE otherwise (or if cancelled).
24960 * g_file_query_file_type:
24961 * @file: input #GFile
24962 * @flags: a set of #GFileQueryInfoFlags passed to g_file_query_info()
24963 * @cancellable: (allow-none): optional #GCancellable object,
24966 * Utility function to inspect the #GFileType of a file. This is
24967 * implemented using g_file_query_info() and as such does blocking I/O.
24969 * The primary use case of this method is to check if a file is
24970 * a regular file, directory, or symlink.
24972 * Returns: The #GFileType of the file and #G_FILE_TYPE_UNKNOWN
24973 * if the file does not exist
24979 * g_file_query_filesystem_info:
24980 * @file: input #GFile
24981 * @attributes: an attribute query string
24982 * @cancellable: (allow-none): optional #GCancellable object,
24984 * @error: a #GError
24986 * Similar to g_file_query_info(), but obtains information
24987 * about the filesystem the @file is on, rather than the file itself.
24988 * For instance the amount of space available and the type of
24991 * The @attributes value is a string that specifies the attributes
24992 * that should be gathered. It is not an error if it's not possible
24993 * to read a particular requested attribute from a file - it just
24994 * won't be set. @attributes should be a comma-separated list of
24995 * attributes or attribute wildcards. The wildcard "*" means all
24996 * attributes, and a wildcard like "filesystem::*" means all attributes
24997 * in the filesystem namespace. The standard namespace for filesystem
24998 * attributes is "filesystem". Common attributes of interest are
24999 * #G_FILE_ATTRIBUTE_FILESYSTEM_SIZE (the total size of the filesystem
25000 * in bytes), #G_FILE_ATTRIBUTE_FILESYSTEM_FREE (number of bytes available),
25001 * and #G_FILE_ATTRIBUTE_FILESYSTEM_TYPE (type of the filesystem).
25003 * If @cancellable is not %NULL, then the operation can be cancelled
25004 * by triggering the cancellable object from another thread. If the
25005 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
25008 * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will
25009 * be returned. Other errors are possible too, and depend on what
25010 * kind of filesystem the file is on.
25012 * Returns: (transfer full): a #GFileInfo or %NULL if there was an error.
25013 * Free the returned object with g_object_unref().
25018 * g_file_query_filesystem_info_async:
25019 * @file: input #GFile
25020 * @attributes: an attribute query string
25021 * @io_priority: the [I/O priority][io-priority] of the request
25022 * @cancellable: (allow-none): optional #GCancellable object,
25024 * @callback: (scope async): a #GAsyncReadyCallback to call
25025 * when the request is satisfied
25026 * @user_data: (closure): the data to pass to callback function
25028 * Asynchronously gets the requested information about the filesystem
25029 * that the specified @file is on. The result is a #GFileInfo object
25030 * that contains key-value attributes (such as type or size for the
25033 * For more details, see g_file_query_filesystem_info() which is the
25034 * synchronous version of this call.
25036 * When the operation is finished, @callback will be called. You can
25037 * then call g_file_query_info_finish() to get the result of the
25043 * g_file_query_filesystem_info_finish:
25044 * @file: input #GFile
25045 * @res: a #GAsyncResult
25046 * @error: a #GError
25048 * Finishes an asynchronous filesystem info query.
25049 * See g_file_query_filesystem_info_async().
25051 * Returns: (transfer full): #GFileInfo for given @file
25052 * or %NULL on error.
25053 * Free the returned object with g_object_unref().
25058 * g_file_query_info:
25059 * @file: input #GFile
25060 * @attributes: an attribute query string
25061 * @flags: a set of #GFileQueryInfoFlags
25062 * @cancellable: (allow-none): optional #GCancellable object,
25064 * @error: a #GError
25066 * Gets the requested information about specified @file.
25067 * The result is a #GFileInfo object that contains key-value
25068 * attributes (such as the type or size of the file).
25070 * The @attributes value is a string that specifies the file
25071 * attributes that should be gathered. It is not an error if
25072 * it's not possible to read a particular requested attribute
25073 * from a file - it just won't be set. @attributes should be a
25074 * comma-separated list of attributes or attribute wildcards.
25075 * The wildcard "*" means all attributes, and a wildcard like
25076 * "standard::*" means all attributes in the standard namespace.
25077 * An example attribute query be "standard::*,owner::user".
25078 * The standard attributes are available as defines, like
25079 * #G_FILE_ATTRIBUTE_STANDARD_NAME.
25081 * If @cancellable is not %NULL, then the operation can be cancelled
25082 * by triggering the cancellable object from another thread. If the
25083 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
25086 * For symlinks, normally the information about the target of the
25087 * symlink is returned, rather than information about the symlink
25088 * itself. However if you pass #G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS
25089 * in @flags the information about the symlink itself will be returned.
25090 * Also, for symlinks that point to non-existing files the information
25091 * about the symlink itself will be returned.
25093 * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will be
25094 * returned. Other errors are possible too, and depend on what kind of
25095 * filesystem the file is on.
25097 * Returns: (transfer full): a #GFileInfo for the given @file, or %NULL
25098 * on error. Free the returned object with g_object_unref().
25103 * g_file_query_info_async:
25104 * @file: input #GFile
25105 * @attributes: an attribute query string
25106 * @flags: a set of #GFileQueryInfoFlags
25107 * @io_priority: the [I/O priority][io-priority] of the request
25108 * @cancellable: (allow-none): optional #GCancellable object,
25110 * @callback: (scope async): a #GAsyncReadyCallback to call when the
25111 * request is satisfied
25112 * @user_data: (closure): the data to pass to callback function
25114 * Asynchronously gets the requested information about specified @file.
25115 * The result is a #GFileInfo object that contains key-value attributes
25116 * (such as type or size for the file).
25118 * For more details, see g_file_query_info() which is the synchronous
25119 * version of this call.
25121 * When the operation is finished, @callback will be called. You can
25122 * then call g_file_query_info_finish() to get the result of the operation.
25127 * g_file_query_info_finish:
25128 * @file: input #GFile
25129 * @res: a #GAsyncResult
25130 * @error: a #GError
25132 * Finishes an asynchronous file info query.
25133 * See g_file_query_info_async().
25135 * Returns: (transfer full): #GFileInfo for given @file
25136 * or %NULL on error. Free the returned object with
25137 * g_object_unref().
25142 * g_file_query_settable_attributes:
25143 * @file: input #GFile
25144 * @cancellable: (allow-none): optional #GCancellable object,
25146 * @error: a #GError, or %NULL
25148 * Obtain the list of settable attributes for the file.
25150 * Returns the type and full attribute name of all the attributes
25151 * that can be set on this file. This doesn't mean setting it will
25152 * always succeed though, you might get an access failure, or some
25153 * specific file may not support a specific attribute.
25155 * If @cancellable is not %NULL, then the operation can be cancelled by
25156 * triggering the cancellable object from another thread. If the operation
25157 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
25159 * Returns: a #GFileAttributeInfoList describing the settable attributes.
25160 * When you are done with it, release it with
25161 * g_file_attribute_info_list_unref()
25166 * g_file_query_writable_namespaces:
25167 * @file: input #GFile
25168 * @cancellable: (allow-none): optional #GCancellable object,
25170 * @error: a #GError, or %NULL
25172 * Obtain the list of attribute namespaces where new attributes
25173 * can be created by a user. An example of this is extended
25174 * attributes (in the "xattr" namespace).
25176 * If @cancellable is not %NULL, then the operation can be cancelled by
25177 * triggering the cancellable object from another thread. If the operation
25178 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
25180 * Returns: a #GFileAttributeInfoList describing the writable namespaces.
25181 * When you are done with it, release it with
25182 * g_file_attribute_info_list_unref()
25187 * g_file_read: (virtual read_fn)
25188 * @file: #GFile to read
25189 * @cancellable: (allow-none): a #GCancellable
25190 * @error: a #GError, or %NULL
25192 * Opens a file for reading. The result is a #GFileInputStream that
25193 * can be used to read the contents of the file.
25195 * If @cancellable is not %NULL, then the operation can be cancelled by
25196 * triggering the cancellable object from another thread. If the operation
25197 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
25199 * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will be
25200 * returned. If the file is a directory, the %G_IO_ERROR_IS_DIRECTORY
25201 * error will be returned. Other errors are possible too, and depend
25202 * on what kind of filesystem the file is on.
25204 * Returns: (transfer full): #GFileInputStream or %NULL on error.
25205 * Free the returned object with g_object_unref().
25210 * g_file_read_async:
25211 * @file: input #GFile
25212 * @io_priority: the [I/O priority][io-priority] of the request
25213 * @cancellable: (allow-none): optional #GCancellable object,
25215 * @callback: (scope async): a #GAsyncReadyCallback to call
25216 * when the request is satisfied
25217 * @user_data: (closure): the data to pass to callback function
25219 * Asynchronously opens @file for reading.
25221 * For more details, see g_file_read() which is
25222 * the synchronous version of this call.
25224 * When the operation is finished, @callback will be called.
25225 * You can then call g_file_read_finish() to get the result
25226 * of the operation.
25231 * g_file_read_finish:
25232 * @file: input #GFile
25233 * @res: a #GAsyncResult
25234 * @error: a #GError, or %NULL
25236 * Finishes an asynchronous file read operation started with
25237 * g_file_read_async().
25239 * Returns: (transfer full): a #GFileInputStream or %NULL on error.
25240 * Free the returned object with g_object_unref().
25246 * @file: input #GFile
25247 * @etag: (allow-none): an optional [entity tag][gfile-etag]
25248 * for the current #GFile, or #NULL to ignore
25249 * @make_backup: %TRUE if a backup should be created
25250 * @flags: a set of #GFileCreateFlags
25251 * @cancellable: (allow-none): optional #GCancellable object,
25253 * @error: a #GError, or %NULL
25255 * Returns an output stream for overwriting the file, possibly
25256 * creating a backup copy of the file first. If the file doesn't exist,
25257 * it will be created.
25259 * This will try to replace the file in the safest way possible so
25260 * that any errors during the writing will not affect an already
25261 * existing copy of the file. For instance, for local files it
25262 * may write to a temporary file and then atomically rename over
25263 * the destination when the stream is closed.
25265 * By default files created are generally readable by everyone,
25266 * but if you pass #G_FILE_CREATE_PRIVATE in @flags the file
25267 * will be made readable only to the current user, to the level that
25268 * is supported on the target filesystem.
25270 * If @cancellable is not %NULL, then the operation can be cancelled
25271 * by triggering the cancellable object from another thread. If the
25272 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
25275 * If you pass in a non-%NULL @etag value and @file already exists, then
25276 * this value is compared to the current entity tag of the file, and if
25277 * they differ an %G_IO_ERROR_WRONG_ETAG error is returned. This
25278 * generally means that the file has been changed since you last read
25279 * it. You can get the new etag from g_file_output_stream_get_etag()
25280 * after you've finished writing and closed the #GFileOutputStream. When
25281 * you load a new file you can use g_file_input_stream_query_info() to
25282 * get the etag of the file.
25284 * If @make_backup is %TRUE, this function will attempt to make a
25285 * backup of the current file before overwriting it. If this fails
25286 * a %G_IO_ERROR_CANT_CREATE_BACKUP error will be returned. If you
25287 * want to replace anyway, try again with @make_backup set to %FALSE.
25289 * If the file is a directory the %G_IO_ERROR_IS_DIRECTORY error will
25290 * be returned, and if the file is some other form of non-regular file
25291 * then a %G_IO_ERROR_NOT_REGULAR_FILE error will be returned. Some
25292 * file systems don't allow all file names, and may return an
25293 * %G_IO_ERROR_INVALID_FILENAME error, and if the name is to long
25294 * %G_IO_ERROR_FILENAME_TOO_LONG will be returned. Other errors are
25295 * possible too, and depend on what kind of filesystem the file is on.
25297 * Returns: (transfer full): a #GFileOutputStream or %NULL on error.
25298 * Free the returned object with g_object_unref().
25303 * g_file_replace_async:
25304 * @file: input #GFile
25305 * @etag: (allow-none): an [entity tag][gfile-etag] for the current #GFile,
25306 * or %NULL to ignore
25307 * @make_backup: %TRUE if a backup should be created
25308 * @flags: a set of #GFileCreateFlags
25309 * @io_priority: the [I/O priority][io-priority] of the request
25310 * @cancellable: (allow-none): optional #GCancellable object,
25312 * @callback: (scope async): a #GAsyncReadyCallback to call
25313 * when the request is satisfied
25314 * @user_data: (closure): the data to pass to callback function
25316 * Asynchronously overwrites the file, replacing the contents,
25317 * possibly creating a backup copy of the file first.
25319 * For more details, see g_file_replace() which is
25320 * the synchronous version of this call.
25322 * When the operation is finished, @callback will be called.
25323 * You can then call g_file_replace_finish() to get the result
25324 * of the operation.
25329 * g_file_replace_contents:
25330 * @file: input #GFile
25331 * @contents: (element-type guint8) (array length=length): a string containing the new contents for @file
25332 * @length: the length of @contents in bytes
25333 * @etag: (allow-none): the old [entity-tag][gfile-etag] for the document,
25335 * @make_backup: %TRUE if a backup should be created
25336 * @flags: a set of #GFileCreateFlags
25337 * @new_etag: (allow-none) (out): a location to a new [entity tag][gfile-etag]
25338 * for the document. This should be freed with g_free() when no longer
25340 * @cancellable: optional #GCancellable object, %NULL to ignore
25341 * @error: a #GError, or %NULL
25343 * Replaces the contents of @file with @contents of @length bytes.
25345 * If @etag is specified (not %NULL), any existing file must have that etag,
25346 * or the error %G_IO_ERROR_WRONG_ETAG will be returned.
25348 * If @make_backup is %TRUE, this function will attempt to make a backup
25349 * of @file. Internally, it uses g_file_replace(), so will try to replace the
25350 * file contents in the safest way possible. For example, atomic renames are
25351 * used when replacing local files’ contents.
25353 * If @cancellable is not %NULL, then the operation can be cancelled by
25354 * triggering the cancellable object from another thread. If the operation
25355 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
25357 * The returned @new_etag can be used to verify that the file hasn't
25358 * changed the next time it is saved over.
25360 * Returns: %TRUE if successful. If an error has occurred, this function
25361 * will return %FALSE and set @error appropriately if present.
25366 * g_file_replace_contents_async:
25367 * @file: input #GFile
25368 * @contents: (element-type guint8) (array length=length): string of contents to replace the file with
25369 * @length: the length of @contents in bytes
25370 * @etag: (allow-none): a new [entity tag][gfile-etag] for the @file, or %NULL
25371 * @make_backup: %TRUE if a backup should be created
25372 * @flags: a set of #GFileCreateFlags
25373 * @cancellable: optional #GCancellable object, %NULL to ignore
25374 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
25375 * @user_data: the data to pass to callback function
25377 * Starts an asynchronous replacement of @file with the given
25378 * @contents of @length bytes. @etag will replace the document's
25379 * current entity tag.
25381 * When this operation has completed, @callback will be called with
25382 * @user_user data, and the operation can be finalized with
25383 * g_file_replace_contents_finish().
25385 * If @cancellable is not %NULL, then the operation can be cancelled by
25386 * triggering the cancellable object from another thread. If the operation
25387 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
25389 * If @make_backup is %TRUE, this function will attempt to
25390 * make a backup of @file.
25392 * Note that no copy of @content will be made, so it must stay valid
25393 * until @callback is called. See g_file_replace_contents_bytes_async()
25394 * for a #GBytes version that will automatically hold a reference to the
25395 * contents (without copying) for the duration of the call.
25400 * g_file_replace_contents_bytes_async:
25401 * @file: input #GFile
25402 * @contents: a #GBytes
25403 * @etag: (allow-none): a new [entity tag][gfile-etag] for the @file, or %NULL
25404 * @make_backup: %TRUE if a backup should be created
25405 * @flags: a set of #GFileCreateFlags
25406 * @cancellable: optional #GCancellable object, %NULL to ignore
25407 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
25408 * @user_data: the data to pass to callback function
25410 * Same as g_file_replace_contents_async() but takes a #GBytes input instead.
25411 * This function will keep a ref on @contents until the operation is done.
25412 * Unlike g_file_replace_contents_async() this allows forgetting about the
25413 * content without waiting for the callback.
25415 * When this operation has completed, @callback will be called with
25416 * @user_user data, and the operation can be finalized with
25417 * g_file_replace_contents_finish().
25424 * g_file_replace_contents_finish:
25425 * @file: input #GFile
25426 * @res: a #GAsyncResult
25427 * @new_etag: (out) (allow-none): a location of a new [entity tag][gfile-etag]
25428 * for the document. This should be freed with g_free() when it is no
25429 * longer needed, or %NULL
25430 * @error: a #GError, or %NULL
25432 * Finishes an asynchronous replace of the given @file. See
25433 * g_file_replace_contents_async(). Sets @new_etag to the new entity
25434 * tag for the document, if present.
25436 * Returns: %TRUE on success, %FALSE on failure.
25441 * g_file_replace_finish:
25442 * @file: input #GFile
25443 * @res: a #GAsyncResult
25444 * @error: a #GError, or %NULL
25446 * Finishes an asynchronous file replace operation started with
25447 * g_file_replace_async().
25449 * Returns: (transfer full): a #GFileOutputStream, or %NULL on error.
25450 * Free the returned object with g_object_unref().
25455 * g_file_replace_readwrite:
25457 * @etag: (allow-none): an optional [entity tag][gfile-etag]
25458 * for the current #GFile, or #NULL to ignore
25459 * @make_backup: %TRUE if a backup should be created
25460 * @flags: a set of #GFileCreateFlags
25461 * @cancellable: (allow-none): optional #GCancellable object,
25463 * @error: return location for a #GError, or %NULL
25465 * Returns an output stream for overwriting the file in readwrite mode,
25466 * possibly creating a backup copy of the file first. If the file doesn't
25467 * exist, it will be created.
25469 * For details about the behaviour, see g_file_replace() which does the
25470 * same thing but returns an output stream only.
25472 * Note that in many non-local file cases read and write streams are not
25473 * supported, so make sure you really need to do read and write streaming,
25474 * rather than just opening for reading or writing.
25476 * Returns: (transfer full): a #GFileIOStream or %NULL on error.
25477 * Free the returned object with g_object_unref().
25483 * g_file_replace_readwrite_async:
25484 * @file: input #GFile
25485 * @etag: (allow-none): an [entity tag][gfile-etag] for the current #GFile,
25486 * or %NULL to ignore
25487 * @make_backup: %TRUE if a backup should be created
25488 * @flags: a set of #GFileCreateFlags
25489 * @io_priority: the [I/O priority][io-priority] of the request
25490 * @cancellable: (allow-none): optional #GCancellable object,
25492 * @callback: (scope async): a #GAsyncReadyCallback to call
25493 * when the request is satisfied
25494 * @user_data: (closure): the data to pass to callback function
25496 * Asynchronously overwrites the file in read-write mode,
25497 * replacing the contents, possibly creating a backup copy
25498 * of the file first.
25500 * For more details, see g_file_replace_readwrite() which is
25501 * the synchronous version of this call.
25503 * When the operation is finished, @callback will be called.
25504 * You can then call g_file_replace_readwrite_finish() to get
25505 * the result of the operation.
25512 * g_file_replace_readwrite_finish:
25513 * @file: input #GFile
25514 * @res: a #GAsyncResult
25515 * @error: a #GError, or %NULL
25517 * Finishes an asynchronous file replace operation started with
25518 * g_file_replace_readwrite_async().
25520 * Returns: (transfer full): a #GFileIOStream, or %NULL on error.
25521 * Free the returned object with g_object_unref().
25527 * g_file_resolve_relative_path:
25528 * @file: input #GFile
25529 * @relative_path: (type filename): a given relative path string
25531 * Resolves a relative path for @file to an absolute path.
25533 * This call does no blocking I/O.
25535 * Returns: (transfer full): #GFile to the resolved path.
25536 * %NULL if @relative_path is %NULL or if @file is invalid.
25537 * Free the returned object with g_object_unref().
25542 * g_file_set_attribute:
25543 * @file: input #GFile
25544 * @attribute: a string containing the attribute's name
25545 * @type: The type of the attribute
25546 * @value_p: (allow-none): a pointer to the value (or the pointer
25547 * itself if the type is a pointer type)
25548 * @flags: a set of #GFileQueryInfoFlags
25549 * @cancellable: (allow-none): optional #GCancellable object,
25551 * @error: a #GError, or %NULL
25553 * Sets an attribute in the file with attribute name @attribute to @value.
25555 * Some attributes can be unset by setting @attribute to
25556 * %G_FILE_ATTRIBUTE_TYPE_INVALID and @value_p to %NULL.
25558 * If @cancellable is not %NULL, then the operation can be cancelled by
25559 * triggering the cancellable object from another thread. If the operation
25560 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
25562 * Returns: %TRUE if the attribute was set, %FALSE otherwise.
25567 * g_file_set_attribute_byte_string:
25568 * @file: input #GFile
25569 * @attribute: a string containing the attribute's name
25570 * @value: a string containing the attribute's new value
25571 * @flags: a #GFileQueryInfoFlags
25572 * @cancellable: (allow-none): optional #GCancellable object,
25574 * @error: a #GError, or %NULL
25576 * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING to @value.
25577 * If @attribute is of a different type, this operation will fail,
25578 * returning %FALSE.
25580 * If @cancellable is not %NULL, then the operation can be cancelled by
25581 * triggering the cancellable object from another thread. If the operation
25582 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
25584 * Returns: %TRUE if the @attribute was successfully set to @value
25585 * in the @file, %FALSE otherwise.
25590 * g_file_set_attribute_int32:
25591 * @file: input #GFile
25592 * @attribute: a string containing the attribute's name
25593 * @value: a #gint32 containing the attribute's new value
25594 * @flags: a #GFileQueryInfoFlags
25595 * @cancellable: (allow-none): optional #GCancellable object,
25597 * @error: a #GError, or %NULL
25599 * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT32 to @value.
25600 * If @attribute is of a different type, this operation will fail.
25602 * If @cancellable is not %NULL, then the operation can be cancelled by
25603 * triggering the cancellable object from another thread. If the operation
25604 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
25606 * Returns: %TRUE if the @attribute was successfully set to @value
25607 * in the @file, %FALSE otherwise.
25612 * g_file_set_attribute_int64:
25613 * @file: input #GFile
25614 * @attribute: a string containing the attribute's name
25615 * @value: a #guint64 containing the attribute's new value
25616 * @flags: a #GFileQueryInfoFlags
25617 * @cancellable: (allow-none): optional #GCancellable object,
25619 * @error: a #GError, or %NULL
25621 * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT64 to @value.
25622 * If @attribute is of a different type, this operation will fail.
25624 * If @cancellable is not %NULL, then the operation can be cancelled by
25625 * triggering the cancellable object from another thread. If the operation
25626 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
25628 * Returns: %TRUE if the @attribute was successfully set, %FALSE otherwise.
25633 * g_file_set_attribute_string:
25634 * @file: input #GFile
25635 * @attribute: a string containing the attribute's name
25636 * @value: a string containing the attribute's value
25637 * @flags: #GFileQueryInfoFlags
25638 * @cancellable: (allow-none): optional #GCancellable object,
25640 * @error: a #GError, or %NULL
25642 * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_STRING to @value.
25643 * If @attribute is of a different type, this operation will fail.
25645 * If @cancellable is not %NULL, then the operation can be cancelled by
25646 * triggering the cancellable object from another thread. If the operation
25647 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
25649 * Returns: %TRUE if the @attribute was successfully set, %FALSE otherwise.
25654 * g_file_set_attribute_uint32:
25655 * @file: input #GFile
25656 * @attribute: a string containing the attribute's name
25657 * @value: a #guint32 containing the attribute's new value
25658 * @flags: a #GFileQueryInfoFlags
25659 * @cancellable: (allow-none): optional #GCancellable object,
25661 * @error: a #GError, or %NULL
25663 * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT32 to @value.
25664 * If @attribute is of a different type, this operation will fail.
25666 * If @cancellable is not %NULL, then the operation can be cancelled by
25667 * triggering the cancellable object from another thread. If the operation
25668 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
25670 * Returns: %TRUE if the @attribute was successfully set to @value
25671 * in the @file, %FALSE otherwise.
25676 * g_file_set_attribute_uint64:
25677 * @file: input #GFile
25678 * @attribute: a string containing the attribute's name
25679 * @value: a #guint64 containing the attribute's new value
25680 * @flags: a #GFileQueryInfoFlags
25681 * @cancellable: (allow-none): optional #GCancellable object,
25683 * @error: a #GError, or %NULL
25685 * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT64 to @value.
25686 * If @attribute is of a different type, this operation will fail.
25688 * If @cancellable is not %NULL, then the operation can be cancelled by
25689 * triggering the cancellable object from another thread. If the operation
25690 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
25692 * Returns: %TRUE if the @attribute was successfully set to @value
25693 * in the @file, %FALSE otherwise.
25698 * g_file_set_attributes_async:
25699 * @file: input #GFile
25700 * @info: a #GFileInfo
25701 * @flags: a #GFileQueryInfoFlags
25702 * @io_priority: the [I/O priority][io-priority] of the request
25703 * @cancellable: (allow-none): optional #GCancellable object,
25705 * @callback: (scope async): a #GAsyncReadyCallback
25706 * @user_data: (closure): a #gpointer
25708 * Asynchronously sets the attributes of @file with @info.
25710 * For more details, see g_file_set_attributes_from_info(),
25711 * which is the synchronous version of this call.
25713 * When the operation is finished, @callback will be called.
25714 * You can then call g_file_set_attributes_finish() to get
25715 * the result of the operation.
25720 * g_file_set_attributes_finish:
25721 * @file: input #GFile
25722 * @result: a #GAsyncResult
25723 * @info: (out) (transfer full): a #GFileInfo
25724 * @error: a #GError, or %NULL
25726 * Finishes setting an attribute started in g_file_set_attributes_async().
25728 * Returns: %TRUE if the attributes were set correctly, %FALSE otherwise.
25733 * g_file_set_attributes_from_info:
25734 * @file: input #GFile
25735 * @info: a #GFileInfo
25736 * @flags: #GFileQueryInfoFlags
25737 * @cancellable: (allow-none): optional #GCancellable object,
25739 * @error: a #GError, or %NULL
25741 * Tries to set all attributes in the #GFileInfo on the target
25742 * values, not stopping on the first error.
25744 * If there is any error during this operation then @error will
25745 * be set to the first error. Error on particular fields are flagged
25746 * by setting the "status" field in the attribute value to
25747 * %G_FILE_ATTRIBUTE_STATUS_ERROR_SETTING, which means you can
25748 * also detect further errors.
25750 * If @cancellable is not %NULL, then the operation can be cancelled by
25751 * triggering the cancellable object from another thread. If the operation
25752 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
25754 * Returns: %FALSE if there was any error, %TRUE otherwise.
25759 * g_file_set_display_name:
25760 * @file: input #GFile
25761 * @display_name: a string
25762 * @cancellable: (allow-none): optional #GCancellable object,
25764 * @error: a #GError, or %NULL
25766 * Renames @file to the specified display name.
25768 * The display name is converted from UTF-8 to the correct encoding
25769 * for the target filesystem if possible and the @file is renamed to this.
25771 * If you want to implement a rename operation in the user interface the
25772 * edit name (#G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME) should be used as the
25773 * initial value in the rename widget, and then the result after editing
25774 * should be passed to g_file_set_display_name().
25776 * On success the resulting converted filename is returned.
25778 * If @cancellable is not %NULL, then the operation can be cancelled by
25779 * triggering the cancellable object from another thread. If the operation
25780 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
25782 * Returns: (transfer full): a #GFile specifying what @file was renamed to,
25783 * or %NULL if there was an error.
25784 * Free the returned object with g_object_unref().
25789 * g_file_set_display_name_async:
25790 * @file: input #GFile
25791 * @display_name: a string
25792 * @io_priority: the [I/O priority][io-priority] of the request
25793 * @cancellable: (allow-none): optional #GCancellable object,
25795 * @callback: (scope async): a #GAsyncReadyCallback to call
25796 * when the request is satisfied
25797 * @user_data: (closure): the data to pass to callback function
25799 * Asynchronously sets the display name for a given #GFile.
25801 * For more details, see g_file_set_display_name() which is
25802 * the synchronous version of this call.
25804 * When the operation is finished, @callback will be called.
25805 * You can then call g_file_set_display_name_finish() to get
25806 * the result of the operation.
25811 * g_file_set_display_name_finish:
25812 * @file: input #GFile
25813 * @res: a #GAsyncResult
25814 * @error: a #GError, or %NULL
25816 * Finishes setting a display name started with
25817 * g_file_set_display_name_async().
25819 * Returns: (transfer full): a #GFile or %NULL on error.
25820 * Free the returned object with g_object_unref().
25825 * g_file_start_mountable:
25826 * @file: input #GFile
25827 * @flags: flags affecting the operation
25828 * @start_operation: (allow-none): a #GMountOperation, or %NULL to avoid user interaction
25829 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
25830 * @callback: (allow-none): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL
25831 * @user_data: the data to pass to callback function
25833 * Starts a file of type #G_FILE_TYPE_MOUNTABLE.
25834 * Using @start_operation, you can request callbacks when, for instance,
25835 * passwords are needed during authentication.
25837 * If @cancellable is not %NULL, then the operation can be cancelled by
25838 * triggering the cancellable object from another thread. If the operation
25839 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
25841 * When the operation is finished, @callback will be called.
25842 * You can then call g_file_mount_mountable_finish() to get
25843 * the result of the operation.
25850 * g_file_start_mountable_finish:
25851 * @file: input #GFile
25852 * @result: a #GAsyncResult
25853 * @error: a #GError, or %NULL
25855 * Finishes a start operation. See g_file_start_mountable() for details.
25857 * Finish an asynchronous start operation that was started
25858 * with g_file_start_mountable().
25860 * Returns: %TRUE if the operation finished successfully. %FALSE
25867 * g_file_stop_mountable:
25868 * @file: input #GFile
25869 * @flags: flags affecting the operation
25870 * @mount_operation: (allow-none): a #GMountOperation,
25871 * or %NULL to avoid user interaction.
25872 * @cancellable: (allow-none): optional #GCancellable object,
25874 * @callback: (allow-none): a #GAsyncReadyCallback to call
25875 * when the request is satisfied, or %NULL
25876 * @user_data: the data to pass to callback function
25878 * Stops a file of type #G_FILE_TYPE_MOUNTABLE.
25880 * If @cancellable is not %NULL, then the operation can be cancelled by
25881 * triggering the cancellable object from another thread. If the operation
25882 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
25884 * When the operation is finished, @callback will be called.
25885 * You can then call g_file_stop_mountable_finish() to get
25886 * the result of the operation.
25893 * g_file_stop_mountable_finish:
25894 * @file: input #GFile
25895 * @result: a #GAsyncResult
25896 * @error: a #GError, or %NULL
25898 * Finishes an stop operation, see g_file_stop_mountable() for details.
25900 * Finish an asynchronous stop operation that was started
25901 * with g_file_stop_mountable().
25903 * Returns: %TRUE if the operation finished successfully.
25904 * %FALSE otherwise.
25910 * g_file_supports_thread_contexts:
25913 * Checks if @file supports
25914 * [thread-default contexts][g-main-context-push-thread-default-context].
25915 * If this returns %FALSE, you cannot perform asynchronous operations on
25916 * @file in a thread that has a thread-default context.
25918 * Returns: Whether or not @file supports thread-default contexts.
25924 * g_file_trash: (virtual trash)
25925 * @file: #GFile to send to trash
25926 * @cancellable: (allow-none): optional #GCancellable object,
25928 * @error: a #GError, or %NULL
25930 * Sends @file to the "Trashcan", if possible. This is similar to
25931 * deleting it, but the user can recover it before emptying the trashcan.
25932 * Not all file systems support trashing, so this call can return the
25933 * %G_IO_ERROR_NOT_SUPPORTED error.
25935 * If @cancellable is not %NULL, then the operation can be cancelled by
25936 * triggering the cancellable object from another thread. If the operation
25937 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
25939 * Returns: %TRUE on successful trash, %FALSE otherwise.
25944 * g_file_trash_async: (virtual trash_async)
25945 * @file: input #GFile
25946 * @io_priority: the [I/O priority][io-priority] of the request
25947 * @cancellable: (allow-none): optional #GCancellable object,
25949 * @callback: a #GAsyncReadyCallback to call
25950 * when the request is satisfied
25951 * @user_data: the data to pass to callback function
25953 * Asynchronously sends @file to the Trash location, if possible.
25960 * g_file_trash_finish: (virtual trash_finish)
25961 * @file: input #GFile
25962 * @result: a #GAsyncResult
25963 * @error: a #GError, or %NULL
25965 * Finishes an asynchronous file trashing operation, started with
25966 * g_file_trash_async().
25968 * Returns: %TRUE on successful trash, %FALSE otherwise.
25974 * g_file_unmount_mountable:
25975 * @file: input #GFile
25976 * @flags: flags affecting the operation
25977 * @cancellable: (allow-none): optional #GCancellable object,
25979 * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call
25980 * when the request is satisfied, or %NULL
25981 * @user_data: (closure): the data to pass to callback function
25983 * Unmounts a file of type G_FILE_TYPE_MOUNTABLE.
25985 * If @cancellable is not %NULL, then the operation can be cancelled by
25986 * triggering the cancellable object from another thread. If the operation
25987 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
25989 * When the operation is finished, @callback will be called.
25990 * You can then call g_file_unmount_mountable_finish() to get
25991 * the result of the operation.
25993 * Deprecated: 2.22: Use g_file_unmount_mountable_with_operation() instead.
25998 * g_file_unmount_mountable_finish:
25999 * @file: input #GFile
26000 * @result: a #GAsyncResult
26001 * @error: a #GError, or %NULL
26003 * Finishes an unmount operation, see g_file_unmount_mountable() for details.
26005 * Finish an asynchronous unmount operation that was started
26006 * with g_file_unmount_mountable().
26008 * Returns: %TRUE if the operation finished successfully.
26009 * %FALSE otherwise.
26010 * Deprecated: 2.22: Use g_file_unmount_mountable_with_operation_finish()
26016 * g_file_unmount_mountable_with_operation:
26017 * @file: input #GFile
26018 * @flags: flags affecting the operation
26019 * @mount_operation: (allow-none): a #GMountOperation,
26020 * or %NULL to avoid user interaction
26021 * @cancellable: (allow-none): optional #GCancellable object,
26023 * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call
26024 * when the request is satisfied, or %NULL
26025 * @user_data: (closure): the data to pass to callback function
26027 * Unmounts a file of type #G_FILE_TYPE_MOUNTABLE.
26029 * If @cancellable is not %NULL, then the operation can be cancelled by
26030 * triggering the cancellable object from another thread. If the operation
26031 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
26033 * When the operation is finished, @callback will be called.
26034 * You can then call g_file_unmount_mountable_finish() to get
26035 * the result of the operation.
26042 * g_file_unmount_mountable_with_operation_finish:
26043 * @file: input #GFile
26044 * @result: a #GAsyncResult
26045 * @error: a #GError, or %NULL
26047 * Finishes an unmount operation,
26048 * see g_file_unmount_mountable_with_operation() for details.
26050 * Finish an asynchronous unmount operation that was started
26051 * with g_file_unmount_mountable_with_operation().
26053 * Returns: %TRUE if the operation finished successfully.
26054 * %FALSE otherwise.
26060 * g_filename_completer_get_completion_suffix:
26061 * @completer: the filename completer.
26062 * @initial_text: text to be completed.
26064 * Obtains a completion for @initial_text from @completer.
26066 * Returns: a completed string, or %NULL if no completion exists.
26067 * This string is not owned by GIO, so remember to g_free() it
26073 * g_filename_completer_get_completions:
26074 * @completer: the filename completer.
26075 * @initial_text: text to be completed.
26077 * Gets an array of completion strings for a given initial text.
26079 * Returns: (array zero-terminated=1) (transfer full): array of strings with possible completions for @initial_text.
26080 * This array must be freed by g_strfreev() when finished.
26085 * g_filename_completer_new:
26087 * Creates a new filename completer.
26089 * Returns: a #GFilenameCompleter.
26094 * g_filename_completer_set_dirs_only:
26095 * @completer: the filename completer.
26096 * @dirs_only: a #gboolean.
26098 * If @dirs_only is %TRUE, @completer will only
26099 * complete directory names, and not file names.
26104 * g_filter_input_stream_get_base_stream:
26105 * @stream: a #GFilterInputStream.
26107 * Gets the base stream for the filter stream.
26109 * Returns: (transfer none): a #GInputStream.
26114 * g_filter_input_stream_get_close_base_stream:
26115 * @stream: a #GFilterInputStream.
26117 * Returns whether the base stream will be closed when @stream is
26120 * Returns: %TRUE if the base stream will be closed.
26125 * g_filter_input_stream_set_close_base_stream:
26126 * @stream: a #GFilterInputStream.
26127 * @close_base: %TRUE to close the base stream.
26129 * Sets whether the base stream will be closed when @stream is closed.
26134 * g_filter_output_stream_get_base_stream:
26135 * @stream: a #GFilterOutputStream.
26137 * Gets the base stream for the filter stream.
26139 * Returns: (transfer none): a #GOutputStream.
26144 * g_filter_output_stream_get_close_base_stream:
26145 * @stream: a #GFilterOutputStream.
26147 * Returns whether the base stream will be closed when @stream is
26150 * Returns: %TRUE if the base stream will be closed.
26155 * g_filter_output_stream_set_close_base_stream:
26156 * @stream: a #GFilterOutputStream.
26157 * @close_base: %TRUE to close the base stream.
26159 * Sets whether the base stream will be closed when @stream is closed.
26164 * g_icon_deserialize:
26165 * @value: a #GVariant created with g_icon_serialize()
26167 * Deserializes a #GIcon previously serialized using g_icon_serialize().
26169 * Returns: (transfer full): a #GIcon, or %NULL when deserialization fails.
26176 * @icon1: (allow-none): pointer to the first #GIcon.
26177 * @icon2: (allow-none): pointer to the second #GIcon.
26179 * Checks if two icons are equal.
26181 * Returns: %TRUE if @icon1 is equal to @icon2. %FALSE otherwise.
26186 * g_icon_hash: (virtual hash)
26187 * @icon: (not nullable): #gconstpointer to an icon object.
26189 * Gets a hash for an icon.
26191 * Returns: a #guint containing a hash for the @icon, suitable for
26192 * use in a #GHashTable or similar data structure.
26197 * g_icon_new_for_string:
26198 * @str: A string obtained via g_icon_to_string().
26199 * @error: Return location for error.
26201 * Generate a #GIcon instance from @str. This function can fail if
26202 * @str is not valid - see g_icon_to_string() for discussion.
26204 * If your application or library provides one or more #GIcon
26205 * implementations you need to ensure that each #GType is registered
26206 * with the type system prior to calling g_icon_new_for_string().
26208 * Returns: (transfer full): An object implementing the #GIcon
26209 * interface or %NULL if @error is set.
26215 * g_icon_serialize:
26218 * Serializes a #GIcon into a #GVariant. An equivalent #GIcon can be retrieved
26219 * back by calling g_icon_deserialize() on the returned value.
26220 * As serialization will avoid using raw icon data when possible, it only
26221 * makes sense to transfer the #GVariant between processes on the same machine,
26222 * (as opposed to over the network), and within the same file system namespace.
26224 * Returns: (transfer full): a #GVariant, or %NULL when serialization fails.
26230 * g_icon_to_string: (virtual to_tokens)
26233 * Generates a textual representation of @icon that can be used for
26234 * serialization such as when passing @icon to a different process or
26235 * saving it to persistent storage. Use g_icon_new_for_string() to
26236 * get @icon back from the returned string.
26238 * The encoding of the returned string is proprietary to #GIcon except
26239 * in the following two cases
26241 * - If @icon is a #GFileIcon, the returned string is a native path
26242 * (such as `/path/to/my icon.png`) without escaping
26243 * if the #GFile for @icon is a native file. If the file is not
26244 * native, the returned string is the result of g_file_get_uri()
26245 * (such as `sftp://path/to/my%20icon.png`).
26247 * - If @icon is a #GThemedIcon with exactly one name, the encoding is
26248 * simply the name (such as `network-server`).
26250 * Returns: (nullable): An allocated NUL-terminated UTF8 string or
26251 * %NULL if @icon can't be serialized. Use g_free() to free.
26257 * g_inet_address_equal:
26258 * @address: A #GInetAddress.
26259 * @other_address: Another #GInetAddress.
26261 * Checks if two #GInetAddress instances are equal, e.g. the same address.
26263 * Returns: %TRUE if @address and @other_address are equal, %FALSE otherwise.
26269 * g_inet_address_get_family:
26270 * @address: a #GInetAddress
26272 * Gets @address's family
26274 * Returns: @address's family
26280 * g_inet_address_get_is_any:
26281 * @address: a #GInetAddress
26283 * Tests whether @address is the "any" address for its family.
26285 * Returns: %TRUE if @address is the "any" address for its family.
26291 * g_inet_address_get_is_link_local:
26292 * @address: a #GInetAddress
26294 * Tests whether @address is a link-local address (that is, if it
26295 * identifies a host on a local network that is not connected to the
26298 * Returns: %TRUE if @address is a link-local address.
26304 * g_inet_address_get_is_loopback:
26305 * @address: a #GInetAddress
26307 * Tests whether @address is the loopback address for its family.
26309 * Returns: %TRUE if @address is the loopback address for its family.
26315 * g_inet_address_get_is_mc_global:
26316 * @address: a #GInetAddress
26318 * Tests whether @address is a global multicast address.
26320 * Returns: %TRUE if @address is a global multicast address.
26326 * g_inet_address_get_is_mc_link_local:
26327 * @address: a #GInetAddress
26329 * Tests whether @address is a link-local multicast address.
26331 * Returns: %TRUE if @address is a link-local multicast address.
26337 * g_inet_address_get_is_mc_node_local:
26338 * @address: a #GInetAddress
26340 * Tests whether @address is a node-local multicast address.
26342 * Returns: %TRUE if @address is a node-local multicast address.
26348 * g_inet_address_get_is_mc_org_local:
26349 * @address: a #GInetAddress
26351 * Tests whether @address is an organization-local multicast address.
26353 * Returns: %TRUE if @address is an organization-local multicast address.
26359 * g_inet_address_get_is_mc_site_local:
26360 * @address: a #GInetAddress
26362 * Tests whether @address is a site-local multicast address.
26364 * Returns: %TRUE if @address is a site-local multicast address.
26370 * g_inet_address_get_is_multicast:
26371 * @address: a #GInetAddress
26373 * Tests whether @address is a multicast address.
26375 * Returns: %TRUE if @address is a multicast address.
26381 * g_inet_address_get_is_site_local:
26382 * @address: a #GInetAddress
26384 * Tests whether @address is a site-local address such as 10.0.0.1
26385 * (that is, the address identifies a host on a local network that can
26386 * not be reached directly from the Internet, but which may have
26387 * outgoing Internet connectivity via a NAT or firewall).
26389 * Returns: %TRUE if @address is a site-local address.
26395 * g_inet_address_get_native_size:
26396 * @address: a #GInetAddress
26398 * Gets the size of the native raw binary address for @address. This
26399 * is the size of the data that you get from g_inet_address_to_bytes().
26401 * Returns: the number of bytes used for the native version of @address.
26407 * g_inet_address_mask_equal:
26408 * @mask: a #GInetAddressMask
26409 * @mask2: another #GInetAddressMask
26411 * Tests if @mask and @mask2 are the same mask.
26413 * Returns: whether @mask and @mask2 are the same mask
26419 * g_inet_address_mask_get_address:
26420 * @mask: a #GInetAddressMask
26422 * Gets @mask's base address
26424 * Returns: (transfer none): @mask's base address
26430 * g_inet_address_mask_get_family:
26431 * @mask: a #GInetAddressMask
26433 * Gets the #GSocketFamily of @mask's address
26435 * Returns: the #GSocketFamily of @mask's address
26441 * g_inet_address_mask_get_length:
26442 * @mask: a #GInetAddressMask
26444 * Gets @mask's length
26446 * Returns: @mask's length
26452 * g_inet_address_mask_matches:
26453 * @mask: a #GInetAddressMask
26454 * @address: a #GInetAddress
26456 * Tests if @address falls within the range described by @mask.
26458 * Returns: whether @address falls within the range described by
26465 * g_inet_address_mask_new:
26466 * @addr: a #GInetAddress
26467 * @length: number of bits of @addr to use
26468 * @error: return location for #GError, or %NULL
26470 * Creates a new #GInetAddressMask representing all addresses whose
26471 * first @length bits match @addr.
26473 * Returns: a new #GInetAddressMask, or %NULL on error
26479 * g_inet_address_mask_new_from_string:
26480 * @mask_string: an IP address or address/length string
26481 * @error: return location for #GError, or %NULL
26483 * Parses @mask_string as an IP address and (optional) length, and
26484 * creates a new #GInetAddressMask. The length, if present, is
26485 * delimited by a "/". If it is not present, then the length is
26486 * assumed to be the full length of the address.
26488 * Returns: a new #GInetAddressMask corresponding to @string, or %NULL
26495 * g_inet_address_mask_to_string:
26496 * @mask: a #GInetAddressMask
26498 * Converts @mask back to its corresponding string form.
26500 * Returns: a string corresponding to @mask.
26506 * g_inet_address_new_any:
26507 * @family: the address family
26509 * Creates a #GInetAddress for the "any" address (unassigned/"don't
26510 * care") for @family.
26512 * Returns: a new #GInetAddress corresponding to the "any" address
26514 * Free the returned object with g_object_unref().
26520 * g_inet_address_new_from_bytes:
26521 * @bytes: (array) (element-type guint8): raw address data
26522 * @family: the address family of @bytes
26524 * Creates a new #GInetAddress from the given @family and @bytes.
26525 * @bytes should be 4 bytes for %G_SOCKET_FAMILY_IPV4 and 16 bytes for
26526 * %G_SOCKET_FAMILY_IPV6.
26528 * Returns: a new #GInetAddress corresponding to @family and @bytes.
26529 * Free the returned object with g_object_unref().
26535 * g_inet_address_new_from_string:
26536 * @string: a string representation of an IP address
26538 * Parses @string as an IP address and creates a new #GInetAddress.
26540 * Returns: a new #GInetAddress corresponding to @string, or %NULL if
26541 * @string could not be parsed.
26542 * Free the returned object with g_object_unref().
26548 * g_inet_address_new_loopback:
26549 * @family: the address family
26551 * Creates a #GInetAddress for the loopback address for @family.
26553 * Returns: a new #GInetAddress corresponding to the loopback address
26555 * Free the returned object with g_object_unref().
26561 * g_inet_address_to_bytes: (skip)
26562 * @address: a #GInetAddress
26564 * Gets the raw binary address data from @address.
26566 * Returns: a pointer to an internal array of the bytes in @address,
26567 * which should not be modified, stored, or freed. The size of this
26568 * array can be gotten with g_inet_address_get_native_size().
26574 * g_inet_address_to_string:
26575 * @address: a #GInetAddress
26577 * Converts @address to string form.
26579 * Returns: a representation of @address as a string, which should be
26586 * g_inet_socket_address_get_address:
26587 * @address: a #GInetSocketAddress
26589 * Gets @address's #GInetAddress.
26591 * Returns: (transfer none): the #GInetAddress for @address, which must be
26592 * g_object_ref()'d if it will be stored
26598 * g_inet_socket_address_get_flowinfo:
26599 * @address: a %G_SOCKET_FAMILY_IPV6 #GInetSocketAddress
26601 * Gets the `sin6_flowinfo` field from @address,
26602 * which must be an IPv6 address.
26604 * Returns: the flowinfo field
26610 * g_inet_socket_address_get_port:
26611 * @address: a #GInetSocketAddress
26613 * Gets @address's port.
26615 * Returns: the port for @address
26621 * g_inet_socket_address_get_scope_id:
26622 * @address: a %G_SOCKET_FAMILY_IPV6 #GInetAddress
26624 * Gets the `sin6_scope_id` field from @address,
26625 * which must be an IPv6 address.
26627 * Returns: the scope id field
26633 * g_inet_socket_address_new:
26634 * @address: a #GInetAddress
26635 * @port: a port number
26637 * Creates a new #GInetSocketAddress for @address and @port.
26639 * Returns: a new #GInetSocketAddress
26645 * g_inet_socket_address_new_from_string:
26646 * @address: the string form of an IP address
26647 * @port: a port number
26649 * Creates a new #GInetSocketAddress for @address and @port.
26651 * If @address is an IPv6 address, it can also contain a scope ID
26652 * (separated from the address by a "<literal>%</literal>").
26654 * Returns: a new #GInetSocketAddress, or %NULL if @address cannot be
26662 * @initable: a #GInitable.
26663 * @cancellable: optional #GCancellable object, %NULL to ignore.
26664 * @error: a #GError location to store the error occurring, or %NULL to
26667 * Initializes the object implementing the interface.
26669 * The object must be initialized before any real use after initial
26670 * construction, either with this function or g_async_initable_init_async().
26672 * Implementations may also support cancellation. If @cancellable is not %NULL,
26673 * then initialization can be cancelled by triggering the cancellable object
26674 * from another thread. If the operation was cancelled, the error
26675 * %G_IO_ERROR_CANCELLED will be returned. If @cancellable is not %NULL and
26676 * the object doesn't support cancellable initialization the error
26677 * %G_IO_ERROR_NOT_SUPPORTED will be returned.
26679 * If the object is not initialized, or initialization returns with an
26680 * error, then all operations on the object except g_object_ref() and
26681 * g_object_unref() are considered to be invalid, and have undefined
26682 * behaviour. See the [introduction][ginitable] for more details.
26684 * Implementations of this method must be idempotent, i.e. multiple calls
26685 * to this function with the same argument should return the same results.
26686 * Only the first call initializes the object, further calls return the result
26687 * of the first call. This is so that it's safe to implement the singleton
26688 * pattern in the GObject constructor function.
26690 * Returns: %TRUE if successful. If an error has occurred, this function will
26691 * return %FALSE and set @error appropriately if present.
26698 * @object_type: a #GType supporting #GInitable.
26699 * @cancellable: optional #GCancellable object, %NULL to ignore.
26700 * @error: a #GError location to store the error occurring, or %NULL to
26702 * @first_property_name: (allow-none): the name of the first property, or %NULL if no
26704 * @...: the value if the first property, followed by and other property
26705 * value pairs, and ended by %NULL.
26707 * Helper function for constructing #GInitable object. This is
26708 * similar to g_object_new() but also initializes the object
26709 * and returns %NULL, setting an error on failure.
26711 * Returns: (type GObject.Object) (transfer full): a newly allocated
26712 * #GObject, or %NULL on error
26718 * g_initable_new_valist:
26719 * @object_type: a #GType supporting #GInitable.
26720 * @first_property_name: the name of the first property, followed by
26721 * the value, and other property value pairs, and ended by %NULL.
26722 * @var_args: The var args list generated from @first_property_name.
26723 * @cancellable: optional #GCancellable object, %NULL to ignore.
26724 * @error: a #GError location to store the error occurring, or %NULL to
26727 * Helper function for constructing #GInitable object. This is
26728 * similar to g_object_new_valist() but also initializes the object
26729 * and returns %NULL, setting an error on failure.
26731 * Returns: (type GObject.Object) (transfer full): a newly allocated
26732 * #GObject, or %NULL on error
26739 * @object_type: a #GType supporting #GInitable.
26740 * @n_parameters: the number of parameters in @parameters
26741 * @parameters: (array length=n_parameters): the parameters to use to construct the object
26742 * @cancellable: optional #GCancellable object, %NULL to ignore.
26743 * @error: a #GError location to store the error occurring, or %NULL to
26746 * Helper function for constructing #GInitable object. This is
26747 * similar to g_object_newv() but also initializes the object
26748 * and returns %NULL, setting an error on failure.
26750 * Returns: (type GObject.Object) (transfer full): a newly allocated
26751 * #GObject, or %NULL on error
26757 * g_input_stream_clear_pending:
26758 * @stream: input stream
26760 * Clears the pending flag on @stream.
26765 * g_input_stream_close:
26766 * @stream: A #GInputStream.
26767 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
26768 * @error: location to store the error occurring, or %NULL to ignore
26770 * Closes the stream, releasing resources related to it.
26772 * Once the stream is closed, all other operations will return %G_IO_ERROR_CLOSED.
26773 * Closing a stream multiple times will not return an error.
26775 * Streams will be automatically closed when the last reference
26776 * is dropped, but you might want to call this function to make sure
26777 * resources are released as early as possible.
26779 * Some streams might keep the backing store of the stream (e.g. a file descriptor)
26780 * open after the stream is closed. See the documentation for the individual
26781 * stream for details.
26783 * On failure the first error that happened will be reported, but the close
26784 * operation will finish as much as possible. A stream that failed to
26785 * close will still return %G_IO_ERROR_CLOSED for all operations. Still, it
26786 * is important to check and report the error to the user.
26788 * If @cancellable is not %NULL, then the operation can be cancelled by
26789 * triggering the cancellable object from another thread. If the operation
26790 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
26791 * Cancelling a close will still leave the stream closed, but some streams
26792 * can use a faster close that doesn't block to e.g. check errors.
26794 * Returns: %TRUE on success, %FALSE on failure
26799 * g_input_stream_close_async:
26800 * @stream: A #GInputStream.
26801 * @io_priority: the [I/O priority][io-priority] of the request
26802 * @cancellable: (allow-none): optional cancellable object
26803 * @callback: (scope async): callback to call when the request is satisfied
26804 * @user_data: (closure): the data to pass to callback function
26806 * Requests an asynchronous closes of the stream, releasing resources related to it.
26807 * When the operation is finished @callback will be called.
26808 * You can then call g_input_stream_close_finish() to get the result of the
26811 * For behaviour details see g_input_stream_close().
26813 * The asyncronous methods have a default fallback that uses threads to implement
26814 * asynchronicity, so they are optional for inheriting classes. However, if you
26815 * override one you must override all.
26820 * g_input_stream_close_finish:
26821 * @stream: a #GInputStream.
26822 * @result: a #GAsyncResult.
26823 * @error: a #GError location to store the error occurring, or %NULL to
26826 * Finishes closing a stream asynchronously, started from g_input_stream_close_async().
26828 * Returns: %TRUE if the stream was closed successfully.
26833 * g_input_stream_has_pending:
26834 * @stream: input stream.
26836 * Checks if an input stream has pending actions.
26838 * Returns: %TRUE if @stream has pending actions.
26843 * g_input_stream_is_closed:
26844 * @stream: input stream.
26846 * Checks if an input stream is closed.
26848 * Returns: %TRUE if the stream is closed.
26853 * g_input_stream_read:
26854 * @stream: a #GInputStream.
26855 * @buffer: (array length=count) (element-type guint8): a buffer to
26856 * read data into (which should be at least count bytes long).
26857 * @count: the number of bytes that will be read from the stream
26858 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
26859 * @error: location to store the error occurring, or %NULL to ignore
26861 * Tries to read @count bytes from the stream into the buffer starting at
26862 * @buffer. Will block during this read.
26864 * If count is zero returns zero and does nothing. A value of @count
26865 * larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
26867 * On success, the number of bytes read into the buffer is returned.
26868 * It is not an error if this is not the same as the requested size, as it
26869 * can happen e.g. near the end of a file. Zero is returned on end of file
26870 * (or if @count is zero), but never otherwise.
26872 * The returned @buffer is not a nul-terminated string, it can contain nul bytes
26873 * at any position, and this function doesn't nul-terminate the @buffer.
26875 * If @cancellable is not %NULL, then the operation can be cancelled by
26876 * triggering the cancellable object from another thread. If the operation
26877 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
26878 * operation was partially finished when the operation was cancelled the
26879 * partial result will be returned, without an error.
26881 * On error -1 is returned and @error is set accordingly.
26883 * Returns: Number of bytes read, or -1 on error, or 0 on end of file.
26888 * g_input_stream_read_all:
26889 * @stream: a #GInputStream.
26890 * @buffer: (array length=count) (element-type guint8): a buffer to
26891 * read data into (which should be at least count bytes long).
26892 * @count: the number of bytes that will be read from the stream
26893 * @bytes_read: (out): location to store the number of bytes that was read from the stream
26894 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
26895 * @error: location to store the error occurring, or %NULL to ignore
26897 * Tries to read @count bytes from the stream into the buffer starting at
26898 * @buffer. Will block during this read.
26900 * This function is similar to g_input_stream_read(), except it tries to
26901 * read as many bytes as requested, only stopping on an error or end of stream.
26903 * On a successful read of @count bytes, or if we reached the end of the
26904 * stream, %TRUE is returned, and @bytes_read is set to the number of bytes
26905 * read into @buffer.
26907 * If there is an error during the operation %FALSE is returned and @error
26908 * is set to indicate the error status.
26910 * As a special exception to the normal conventions for functions that
26911 * use #GError, if this function returns %FALSE (and sets @error) then
26912 * @bytes_read will be set to the number of bytes that were successfully
26913 * read before the error was encountered. This functionality is only
26914 * available from C. If you need it from another language then you must
26915 * write your own loop around g_input_stream_read().
26917 * Returns: %TRUE on success, %FALSE if there was an error
26922 * g_input_stream_read_all_async:
26923 * @stream: A #GInputStream
26924 * @buffer: (array length=count) (element-type guint8): a buffer to
26925 * read data into (which should be at least count bytes long)
26926 * @count: the number of bytes that will be read from the stream
26927 * @io_priority: the [I/O priority][io-priority] of the request
26928 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
26929 * @callback: (scope async): callback to call when the request is satisfied
26930 * @user_data: (closure): the data to pass to callback function
26932 * Request an asynchronous read of @count bytes from the stream into the
26933 * buffer starting at @buffer.
26935 * This is the asynchronous equivalent of g_input_stream_read_all().
26937 * Call g_input_stream_read_all_finish() to collect the result.
26939 * Any outstanding I/O request with higher priority (lower numerical
26940 * value) will be executed before an outstanding request with lower
26941 * priority. Default priority is %G_PRIORITY_DEFAULT.
26948 * g_input_stream_read_all_finish:
26949 * @stream: a #GInputStream
26950 * @result: a #GAsyncResult
26951 * @bytes_read: (out): location to store the number of bytes that was read from the stream
26952 * @error: a #GError location to store the error occurring, or %NULL to ignore
26954 * Finishes an asynchronous stream read operation started with
26955 * g_input_stream_read_all_async().
26957 * As a special exception to the normal conventions for functions that
26958 * use #GError, if this function returns %FALSE (and sets @error) then
26959 * @bytes_read will be set to the number of bytes that were successfully
26960 * read before the error was encountered. This functionality is only
26961 * available from C. If you need it from another language then you must
26962 * write your own loop around g_input_stream_read_async().
26964 * Returns: %TRUE on success, %FALSE if there was an error
26970 * g_input_stream_read_async:
26971 * @stream: A #GInputStream.
26972 * @buffer: (array length=count) (element-type guint8): a buffer to
26973 * read data into (which should be at least count bytes long).
26974 * @count: the number of bytes that will be read from the stream
26975 * @io_priority: the [I/O priority][io-priority]
26977 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
26978 * @callback: (scope async): callback to call when the request is satisfied
26979 * @user_data: (closure): the data to pass to callback function
26981 * Request an asynchronous read of @count bytes from the stream into the buffer
26982 * starting at @buffer. When the operation is finished @callback will be called.
26983 * You can then call g_input_stream_read_finish() to get the result of the
26986 * During an async request no other sync and async calls are allowed on @stream, and will
26987 * result in %G_IO_ERROR_PENDING errors.
26989 * A value of @count larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
26991 * On success, the number of bytes read into the buffer will be passed to the
26992 * callback. It is not an error if this is not the same as the requested size, as it
26993 * can happen e.g. near the end of a file, but generally we try to read
26994 * as many bytes as requested. Zero is returned on end of file
26995 * (or if @count is zero), but never otherwise.
26997 * Any outstanding i/o request with higher priority (lower numerical value) will
26998 * be executed before an outstanding request with lower priority. Default
26999 * priority is %G_PRIORITY_DEFAULT.
27001 * The asyncronous methods have a default fallback that uses threads to implement
27002 * asynchronicity, so they are optional for inheriting classes. However, if you
27003 * override one you must override all.
27008 * g_input_stream_read_bytes:
27009 * @stream: a #GInputStream.
27010 * @count: maximum number of bytes that will be read from the stream. Common
27011 * values include 4096 and 8192.
27012 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
27013 * @error: location to store the error occurring, or %NULL to ignore
27015 * Like g_input_stream_read(), this tries to read @count bytes from
27016 * the stream in a blocking fashion. However, rather than reading into
27017 * a user-supplied buffer, this will create a new #GBytes containing
27018 * the data that was read. This may be easier to use from language
27021 * If count is zero, returns a zero-length #GBytes and does nothing. A
27022 * value of @count larger than %G_MAXSSIZE will cause a
27023 * %G_IO_ERROR_INVALID_ARGUMENT error.
27025 * On success, a new #GBytes is returned. It is not an error if the
27026 * size of this object is not the same as the requested size, as it
27027 * can happen e.g. near the end of a file. A zero-length #GBytes is
27028 * returned on end of file (or if @count is zero), but never
27031 * If @cancellable is not %NULL, then the operation can be cancelled by
27032 * triggering the cancellable object from another thread. If the operation
27033 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
27034 * operation was partially finished when the operation was cancelled the
27035 * partial result will be returned, without an error.
27037 * On error %NULL is returned and @error is set accordingly.
27039 * Returns: a new #GBytes, or %NULL on error
27045 * g_input_stream_read_bytes_async:
27046 * @stream: A #GInputStream.
27047 * @count: the number of bytes that will be read from the stream
27048 * @io_priority: the [I/O priority][io-priority] of the request
27049 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
27050 * @callback: (scope async): callback to call when the request is satisfied
27051 * @user_data: (closure): the data to pass to callback function
27053 * Request an asynchronous read of @count bytes from the stream into a
27054 * new #GBytes. When the operation is finished @callback will be
27055 * called. You can then call g_input_stream_read_bytes_finish() to get the
27056 * result of the operation.
27058 * During an async request no other sync and async calls are allowed
27059 * on @stream, and will result in %G_IO_ERROR_PENDING errors.
27061 * A value of @count larger than %G_MAXSSIZE will cause a
27062 * %G_IO_ERROR_INVALID_ARGUMENT error.
27064 * On success, the new #GBytes will be passed to the callback. It is
27065 * not an error if this is smaller than the requested size, as it can
27066 * happen e.g. near the end of a file, but generally we try to read as
27067 * many bytes as requested. Zero is returned on end of file (or if
27068 * @count is zero), but never otherwise.
27070 * Any outstanding I/O request with higher priority (lower numerical
27071 * value) will be executed before an outstanding request with lower
27072 * priority. Default priority is %G_PRIORITY_DEFAULT.
27079 * g_input_stream_read_bytes_finish:
27080 * @stream: a #GInputStream.
27081 * @result: a #GAsyncResult.
27082 * @error: a #GError location to store the error occurring, or %NULL to
27085 * Finishes an asynchronous stream read-into-#GBytes operation.
27087 * Returns: the newly-allocated #GBytes, or %NULL on error
27093 * g_input_stream_read_finish:
27094 * @stream: a #GInputStream.
27095 * @result: a #GAsyncResult.
27096 * @error: a #GError location to store the error occurring, or %NULL to
27099 * Finishes an asynchronous stream read operation.
27101 * Returns: number of bytes read in, or -1 on error, or 0 on end of file.
27106 * g_input_stream_set_pending:
27107 * @stream: input stream
27108 * @error: a #GError location to store the error occurring, or %NULL to
27111 * Sets @stream to have actions pending. If the pending flag is
27112 * already set or @stream is closed, it will return %FALSE and set
27115 * Returns: %TRUE if pending was previously unset and is now set.
27120 * g_input_stream_skip:
27121 * @stream: a #GInputStream.
27122 * @count: the number of bytes that will be skipped from the stream
27123 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
27124 * @error: location to store the error occurring, or %NULL to ignore
27126 * Tries to skip @count bytes from the stream. Will block during the operation.
27128 * This is identical to g_input_stream_read(), from a behaviour standpoint,
27129 * but the bytes that are skipped are not returned to the user. Some
27130 * streams have an implementation that is more efficient than reading the data.
27132 * This function is optional for inherited classes, as the default implementation
27133 * emulates it using read.
27135 * If @cancellable is not %NULL, then the operation can be cancelled by
27136 * triggering the cancellable object from another thread. If the operation
27137 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
27138 * operation was partially finished when the operation was cancelled the
27139 * partial result will be returned, without an error.
27141 * Returns: Number of bytes skipped, or -1 on error
27146 * g_input_stream_skip_async:
27147 * @stream: A #GInputStream.
27148 * @count: the number of bytes that will be skipped from the stream
27149 * @io_priority: the [I/O priority][io-priority] of the request
27150 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
27151 * @callback: (scope async): callback to call when the request is satisfied
27152 * @user_data: (closure): the data to pass to callback function
27154 * Request an asynchronous skip of @count bytes from the stream.
27155 * When the operation is finished @callback will be called.
27156 * You can then call g_input_stream_skip_finish() to get the result
27157 * of the operation.
27159 * During an async request no other sync and async calls are allowed,
27160 * and will result in %G_IO_ERROR_PENDING errors.
27162 * A value of @count larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
27164 * On success, the number of bytes skipped will be passed to the callback.
27165 * It is not an error if this is not the same as the requested size, as it
27166 * can happen e.g. near the end of a file, but generally we try to skip
27167 * as many bytes as requested. Zero is returned on end of file
27168 * (or if @count is zero), but never otherwise.
27170 * Any outstanding i/o request with higher priority (lower numerical value)
27171 * will be executed before an outstanding request with lower priority.
27172 * Default priority is %G_PRIORITY_DEFAULT.
27174 * The asynchronous methods have a default fallback that uses threads to
27175 * implement asynchronicity, so they are optional for inheriting classes.
27176 * However, if you override one, you must override all.
27181 * g_input_stream_skip_finish:
27182 * @stream: a #GInputStream.
27183 * @result: a #GAsyncResult.
27184 * @error: a #GError location to store the error occurring, or %NULL to
27187 * Finishes a stream skip operation.
27189 * Returns: the size of the bytes skipped, or %-1 on error.
27194 * g_io_error_from_errno:
27195 * @err_no: Error number as defined in errno.h.
27197 * Converts errno.h error codes into GIO error codes. The fallback
27198 * value %G_IO_ERROR_FAILED is returned for error codes not currently
27199 * handled (but note that future GLib releases may return a more
27200 * specific value instead).
27202 * Returns: #GIOErrorEnum value for the given errno.h error number.
27207 * g_io_error_from_win32_error:
27208 * @error_code: Windows error number.
27210 * Converts some common error codes (as returned from GetLastError()
27211 * or WSAGetLastError()) into GIO error codes. The fallback value
27212 * %G_IO_ERROR_FAILED is returned for error codes not currently
27213 * handled (but note that future GLib releases may return a more
27214 * specific value instead).
27216 * You can use g_win32_error_message() to get a localized string
27217 * corresponding to @error_code. (But note that unlike g_strerror(),
27218 * g_win32_error_message() returns a string that must be freed.)
27220 * Returns: #GIOErrorEnum value for the given error number.
27226 * g_io_error_quark:
27228 * Gets the GIO Error Quark.
27230 * Returns: a #GQuark.
27235 * g_io_extension_get_name:
27236 * @extension: a #GIOExtension
27238 * Gets the name under which @extension was registered.
27240 * Note that the same type may be registered as extension
27241 * for multiple extension points, under different names.
27243 * Returns: the name of @extension.
27248 * g_io_extension_get_priority:
27249 * @extension: a #GIOExtension
27251 * Gets the priority with which @extension was registered.
27253 * Returns: the priority of @extension
27258 * g_io_extension_get_type:
27259 * @extension: a #GIOExtension
27261 * Gets the type associated with @extension.
27263 * Returns: the type of @extension
27268 * g_io_extension_point_get_extension_by_name:
27269 * @extension_point: a #GIOExtensionPoint
27270 * @name: the name of the extension to get
27272 * Finds a #GIOExtension for an extension point by name.
27274 * Returns: (transfer none): the #GIOExtension for @extension_point that has the
27275 * given name, or %NULL if there is no extension with that name
27280 * g_io_extension_point_get_extensions:
27281 * @extension_point: a #GIOExtensionPoint
27283 * Gets a list of all extensions that implement this extension point.
27284 * The list is sorted by priority, beginning with the highest priority.
27286 * Returns: (element-type GIOExtension) (transfer none): a #GList of
27287 * #GIOExtensions. The list is owned by GIO and should not be
27293 * g_io_extension_point_get_required_type:
27294 * @extension_point: a #GIOExtensionPoint
27296 * Gets the required type for @extension_point.
27298 * Returns: the #GType that all implementations must have,
27299 * or #G_TYPE_INVALID if the extension point has no required type
27304 * g_io_extension_point_implement:
27305 * @extension_point_name: the name of the extension point
27306 * @type: the #GType to register as extension
27307 * @extension_name: the name for the extension
27308 * @priority: the priority for the extension
27310 * Registers @type as extension for the extension point with name
27311 * @extension_point_name.
27313 * If @type has already been registered as an extension for this
27314 * extension point, the existing #GIOExtension object is returned.
27316 * Returns: (transfer none): a #GIOExtension object for #GType
27321 * g_io_extension_point_lookup:
27322 * @name: the name of the extension point
27324 * Looks up an existing extension point.
27326 * Returns: (transfer none): the #GIOExtensionPoint, or %NULL if there
27327 * is no registered extension point with the given name.
27332 * g_io_extension_point_register:
27333 * @name: The name of the extension point
27335 * Registers an extension point.
27337 * Returns: (transfer none): the new #GIOExtensionPoint. This object is
27338 * owned by GIO and should not be freed.
27343 * g_io_extension_point_set_required_type:
27344 * @extension_point: a #GIOExtensionPoint
27345 * @type: the #GType to require
27347 * Sets the required type for @extension_point to @type.
27348 * All implementations must henceforth have this type.
27353 * g_io_extension_ref_class:
27354 * @extension: a #GIOExtension
27356 * Gets a reference to the class for the type that is
27357 * associated with @extension.
27359 * Returns: (transfer full): the #GTypeClass for the type of @extension
27365 * @filename: (type filename): filename of the shared library module.
27367 * Creates a new GIOModule that will load the specific
27368 * shared library when in use.
27370 * Returns: a #GIOModule from given @filename,
27371 * or %NULL on error.
27376 * g_io_module_scope_block:
27377 * @scope: a module loading scope
27378 * @basename: the basename to block
27380 * Block modules with the given @basename from being loaded when
27381 * this scope is used with g_io_modules_scan_all_in_directory_with_scope()
27382 * or g_io_modules_load_all_in_directory_with_scope().
27389 * g_io_module_scope_free:
27390 * @scope: a module loading scope
27392 * Free a module scope.
27399 * g_io_module_scope_new:
27400 * @flags: flags for the new scope
27402 * Create a new scope for loading of IO modules. A scope can be used for
27403 * blocking duplicate modules, or blocking a module you don't want to load.
27405 * Specify the %G_IO_MODULE_SCOPE_BLOCK_DUPLICATES flag to block modules
27406 * which have the same base name as a module that has already been seen
27409 * Returns: (transfer full): the new module scope
27415 * g_io_modules_load_all_in_directory:
27416 * @dirname: (type filename): pathname for a directory containing modules
27419 * Loads all the modules in the specified directory.
27421 * If don't require all modules to be initialized (and thus registering
27422 * all gtypes) then you can use g_io_modules_scan_all_in_directory()
27423 * which allows delayed/lazy loading of modules.
27425 * Returns: (element-type GIOModule) (transfer full): a list of #GIOModules loaded
27426 * from the directory,
27427 * All the modules are loaded into memory, if you want to
27428 * unload them (enabling on-demand loading) you must call
27429 * g_type_module_unuse() on all the modules. Free the list
27430 * with g_list_free().
27435 * g_io_modules_load_all_in_directory_with_scope:
27436 * @dirname: (type filename): pathname for a directory containing modules
27438 * @scope: a scope to use when scanning the modules.
27440 * Loads all the modules in the specified directory.
27442 * If don't require all modules to be initialized (and thus registering
27443 * all gtypes) then you can use g_io_modules_scan_all_in_directory()
27444 * which allows delayed/lazy loading of modules.
27446 * Returns: (element-type GIOModule) (transfer full): a list of #GIOModules loaded
27447 * from the directory,
27448 * All the modules are loaded into memory, if you want to
27449 * unload them (enabling on-demand loading) you must call
27450 * g_type_module_unuse() on all the modules. Free the list
27451 * with g_list_free().
27457 * g_io_modules_scan_all_in_directory:
27458 * @dirname: (type filename): pathname for a directory containing modules
27461 * Scans all the modules in the specified directory, ensuring that
27462 * any extension point implemented by a module is registered.
27464 * This may not actually load and initialize all the types in each
27465 * module, some modules may be lazily loaded and initialized when
27466 * an extension point it implementes is used with e.g.
27467 * g_io_extension_point_get_extensions() or
27468 * g_io_extension_point_get_extension_by_name().
27470 * If you need to guarantee that all types are loaded in all the modules,
27471 * use g_io_modules_load_all_in_directory().
27478 * g_io_modules_scan_all_in_directory_with_scope:
27479 * @dirname: (type filename): pathname for a directory containing modules
27481 * @scope: a scope to use when scanning the modules
27483 * Scans all the modules in the specified directory, ensuring that
27484 * any extension point implemented by a module is registered.
27486 * This may not actually load and initialize all the types in each
27487 * module, some modules may be lazily loaded and initialized when
27488 * an extension point it implementes is used with e.g.
27489 * g_io_extension_point_get_extensions() or
27490 * g_io_extension_point_get_extension_by_name().
27492 * If you need to guarantee that all types are loaded in all the modules,
27493 * use g_io_modules_load_all_in_directory().
27500 * g_io_scheduler_cancel_all_jobs:
27502 * Cancels all cancellable I/O jobs.
27504 * A job is cancellable if a #GCancellable was passed into
27505 * g_io_scheduler_push_job().
27507 * Deprecated: You should never call this function, since you don't
27508 * know how other libraries in your program might be making use of
27514 * g_io_scheduler_job_send_to_mainloop:
27515 * @job: a #GIOSchedulerJob
27516 * @func: a #GSourceFunc callback that will be called in the original thread
27517 * @user_data: data to pass to @func
27518 * @notify: (allow-none): a #GDestroyNotify for @user_data, or %NULL
27520 * Used from an I/O job to send a callback to be run in the thread
27521 * that the job was started from, waiting for the result (and thus
27522 * blocking the I/O job).
27524 * Returns: The return value of @func
27525 * Deprecated: Use g_main_context_invoke().
27530 * g_io_scheduler_job_send_to_mainloop_async:
27531 * @job: a #GIOSchedulerJob
27532 * @func: a #GSourceFunc callback that will be called in the original thread
27533 * @user_data: data to pass to @func
27534 * @notify: (allow-none): a #GDestroyNotify for @user_data, or %NULL
27536 * Used from an I/O job to send a callback to be run asynchronously in
27537 * the thread that the job was started from. The callback will be run
27538 * when the main loop is available, but at that time the I/O job might
27539 * have finished. The return value from the callback is ignored.
27541 * Note that if you are passing the @user_data from g_io_scheduler_push_job()
27542 * on to this function you have to ensure that it is not freed before
27543 * @func is called, either by passing %NULL as @notify to
27544 * g_io_scheduler_push_job() or by using refcounting for @user_data.
27546 * Deprecated: Use g_main_context_invoke().
27551 * g_io_scheduler_push_job:
27552 * @job_func: a #GIOSchedulerJobFunc.
27553 * @user_data: data to pass to @job_func
27554 * @notify: (allow-none): a #GDestroyNotify for @user_data, or %NULL
27555 * @io_priority: the [I/O priority][io-priority]
27557 * @cancellable: optional #GCancellable object, %NULL to ignore.
27559 * Schedules the I/O job to run in another thread.
27561 * @notify will be called on @user_data after @job_func has returned,
27562 * regardless whether the job was cancelled or has run to completion.
27564 * If @cancellable is not %NULL, it can be used to cancel the I/O job
27565 * by calling g_cancellable_cancel() or by calling
27566 * g_io_scheduler_cancel_all_jobs().
27568 * Deprecated: use #GThreadPool or g_task_run_in_thread()
27573 * g_io_stream_clear_pending:
27574 * @stream: a #GIOStream
27576 * Clears the pending flag on @stream.
27583 * g_io_stream_close:
27584 * @stream: a #GIOStream
27585 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
27586 * @error: location to store the error occurring, or %NULL to ignore
27588 * Closes the stream, releasing resources related to it. This will also
27589 * close the individual input and output streams, if they are not already
27592 * Once the stream is closed, all other operations will return
27593 * %G_IO_ERROR_CLOSED. Closing a stream multiple times will not
27596 * Closing a stream will automatically flush any outstanding buffers
27599 * Streams will be automatically closed when the last reference
27600 * is dropped, but you might want to call this function to make sure
27601 * resources are released as early as possible.
27603 * Some streams might keep the backing store of the stream (e.g. a file
27604 * descriptor) open after the stream is closed. See the documentation for
27605 * the individual stream for details.
27607 * On failure the first error that happened will be reported, but the
27608 * close operation will finish as much as possible. A stream that failed
27609 * to close will still return %G_IO_ERROR_CLOSED for all operations.
27610 * Still, it is important to check and report the error to the user,
27611 * otherwise there might be a loss of data as all data might not be written.
27613 * If @cancellable is not NULL, then the operation can be cancelled by
27614 * triggering the cancellable object from another thread. If the operation
27615 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
27616 * Cancelling a close will still leave the stream closed, but some streams
27617 * can use a faster close that doesn't block to e.g. check errors.
27619 * The default implementation of this method just calls close on the
27620 * individual input/output streams.
27622 * Returns: %TRUE on success, %FALSE on failure
27628 * g_io_stream_close_async:
27629 * @stream: a #GIOStream
27630 * @io_priority: the io priority of the request
27631 * @cancellable: (allow-none): optional cancellable object
27632 * @callback: (scope async): callback to call when the request is satisfied
27633 * @user_data: (closure): the data to pass to callback function
27635 * Requests an asynchronous close of the stream, releasing resources
27636 * related to it. When the operation is finished @callback will be
27637 * called. You can then call g_io_stream_close_finish() to get
27638 * the result of the operation.
27640 * For behaviour details see g_io_stream_close().
27642 * The asynchronous methods have a default fallback that uses threads
27643 * to implement asynchronicity, so they are optional for inheriting
27644 * classes. However, if you override one you must override all.
27651 * g_io_stream_close_finish:
27652 * @stream: a #GIOStream
27653 * @result: a #GAsyncResult
27654 * @error: a #GError location to store the error occurring, or %NULL to
27659 * Returns: %TRUE if stream was successfully closed, %FALSE otherwise.
27665 * g_io_stream_get_input_stream:
27666 * @stream: a #GIOStream
27668 * Gets the input stream for this object. This is used
27671 * Returns: (transfer none): a #GInputStream, owned by the #GIOStream.
27678 * g_io_stream_get_output_stream:
27679 * @stream: a #GIOStream
27681 * Gets the output stream for this object. This is used for
27684 * Returns: (transfer none): a #GOutputStream, owned by the #GIOStream.
27691 * g_io_stream_has_pending:
27692 * @stream: a #GIOStream
27694 * Checks if a stream has pending actions.
27696 * Returns: %TRUE if @stream has pending actions.
27702 * g_io_stream_is_closed:
27703 * @stream: a #GIOStream
27705 * Checks if a stream is closed.
27707 * Returns: %TRUE if the stream is closed.
27713 * g_io_stream_set_pending:
27714 * @stream: a #GIOStream
27715 * @error: a #GError location to store the error occurring, or %NULL to
27718 * Sets @stream to have actions pending. If the pending flag is
27719 * already set or @stream is closed, it will return %FALSE and set
27722 * Returns: %TRUE if pending was previously unset and is now set.
27728 * g_io_stream_splice_async:
27729 * @stream1: a #GIOStream.
27730 * @stream2: a #GIOStream.
27731 * @flags: a set of #GIOStreamSpliceFlags.
27732 * @io_priority: the io priority of the request.
27733 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
27734 * @callback: (scope async): a #GAsyncReadyCallback.
27735 * @user_data: (closure): user data passed to @callback.
27737 * Asyncronously splice the output stream of @stream1 to the input stream of
27738 * @stream2, and splice the output stream of @stream2 to the input stream of
27741 * When the operation is finished @callback will be called.
27742 * You can then call g_io_stream_splice_finish() to get the
27743 * result of the operation.
27750 * g_io_stream_splice_finish:
27751 * @result: a #GAsyncResult.
27752 * @error: a #GError location to store the error occurring, or %NULL to
27755 * Finishes an asynchronous io stream splice operation.
27757 * Returns: %TRUE on success, %FALSE otherwise.
27763 * g_keyfile_settings_backend_new:
27764 * @filename: the filename of the keyfile
27765 * @root_path: the path under which all settings keys appear
27766 * @root_group: (allow-none): the group name corresponding to
27767 * @root_path, or %NULL
27769 * Creates a keyfile-backed #GSettingsBackend.
27771 * The filename of the keyfile to use is given by @filename.
27773 * All settings read to or written from the backend must fall under the
27774 * path given in @root_path (which must start and end with a slash and
27775 * not contain two consecutive slashes). @root_path may be "/".
27777 * If @root_group is non-%NULL then it specifies the name of the keyfile
27778 * group used for keys that are written directly below @root_path. For
27779 * example, if @root_path is "/apps/example/" and @root_group is
27780 * "toplevel", then settings the key "/apps/example/enabled" to a value
27781 * of %TRUE will cause the following to appear in the keyfile:
27788 * If @root_group is %NULL then it is not permitted to store keys
27789 * directly below the @root_path.
27791 * For keys not stored directly below @root_path (ie: in a sub-path),
27792 * the name of the subpath (with the final slash stripped) is used as
27793 * the name of the keyfile group. To continue the example, if
27794 * "/apps/example/profiles/default/font-size" were set to
27795 * 12 then the following would appear in the keyfile:
27798 * [profiles/default]
27802 * The backend will refuse writes (and return writability as being
27803 * %FALSE) for keys outside of @root_path and, in the event that
27804 * @root_group is %NULL, also for keys directly under @root_path.
27805 * Writes will also be refused if the backend detects that it has the
27806 * inability to rewrite the keyfile (ie: the containing directory is not
27809 * There is no checking done for your key namespace clashing with the
27810 * syntax of the key file format. For example, if you have '[' or ']'
27811 * characters in your path names or '=' in your key names you may be in
27814 * Returns: (transfer full): a keyfile-backed #GSettingsBackend
27819 * g_list_model_get_item: (skip)
27820 * @list: a #GListModel
27821 * @position: the position of the item to fetch
27823 * Get the item at @position. If @position is greater than the number of
27824 * items in @list, %NULL is returned.
27826 * %NULL is never returned for an index that is smaller than the length
27827 * of the list. See g_list_model_get_n_items().
27829 * Returns: (transfer full) (nullable) (type GObject): the item at @position.
27835 * g_list_model_get_item_type:
27836 * @list: a #GListModel
27838 * Gets the type of the items in @list. All items returned from
27839 * g_list_model_get_type() are of that type or a subtype, or are an
27840 * implementation of that interface.
27842 * The item type of a #GListModel can not change during the life of the
27845 * Returns: the #GType of the items contained in @list.
27851 * g_list_model_get_n_items:
27852 * @list: a #GListModel
27854 * Gets the number of items in @list.
27856 * Depending on the model implementation, calling this function may be
27857 * less efficient than iterating the list with increasing values for
27858 * @position until g_list_model_get_item() returns %NULL.
27860 * Returns: the number of items in @list.
27866 * g_list_model_get_object: (rename-to g_list_model_get_item)
27867 * @list: a #GListModel
27868 * @position: the position of the item to fetch
27870 * Get the item at @position. If @position is greater than the number of
27871 * items in @list, %NULL is returned.
27873 * %NULL is never returned for an index that is smaller than the length
27874 * of the list. See g_list_model_get_n_items().
27876 * Returns: (transfer full) (nullable): the object at @position.
27882 * g_list_model_items_changed:
27883 * @list: a #GListModel
27884 * @position: the position at which @list changed
27885 * @removed: the number of items removed
27886 * @added: the number of items added
27888 * Emits the #GListModel::items-changed signal on @list.
27890 * This function should only be called by classes implementing
27891 * #GListModel. It has to be called after the internal representation
27892 * of @list has been updated, because handlers connected to this signal
27893 * might query the new state of the list.
27895 * Implementations must only make changes to the model (as visible to
27896 * its consumer) in places that will not cause problems for that
27897 * consumer. For models that are driven directly by a write API (such
27898 * as #GListStore), changes can be reported in response to uses of that
27899 * API. For models that represent remote data, changes should only be
27900 * made from a fresh mainloop dispatch. It is particularly not
27901 * permitted to make changes in response to a call to the #GListModel
27904 * Stated another way: in general, it is assumed that code making a
27905 * series of accesses to the model via the API, without returning to the
27906 * mainloop, and without calling other code, will continue to view the
27907 * same contents of the model.
27914 * g_list_store_append:
27915 * @store: a #GListStore
27916 * @item: (type GObject): the new item
27918 * Appends @item to @store. @item must be of type #GListStore:item-type.
27920 * This function takes a ref on @item.
27922 * Use g_list_store_splice() to append multiple items at the same time
27930 * g_list_store_insert:
27931 * @store: a #GListStore
27932 * @position: the position at which to insert the new item
27933 * @item: (type GObject): the new item
27935 * Inserts @item into @store at @position. @item must be of type
27936 * #GListStore:item-type or derived from it. @position must be smaller
27937 * than the length of the list, or equal to it to append.
27939 * This function takes a ref on @item.
27941 * Use g_list_store_splice() to insert multiple items at the same time
27949 * g_list_store_insert_sorted:
27950 * @store: a #GListStore
27951 * @item: (type GObject): the new item
27952 * @compare_func: (scope call): pairwise comparison function for sorting
27953 * @user_data: (closure): user data for @compare_func
27955 * Inserts @item into @store at a position to be determined by the
27958 * The list must already be sorted before calling this function or the
27959 * result is undefined. Usually you would approach this by only ever
27960 * inserting items by way of this function.
27962 * This function takes a ref on @item.
27964 * Returns: the position at which @item was inserted
27970 * g_list_store_new:
27971 * @item_type: the #GType of items in the list
27973 * Creates a new #GListStore with items of type @item_type. @item_type
27974 * must be a subclass of #GObject.
27976 * Returns: a new #GListStore
27982 * g_list_store_remove:
27983 * @store: a #GListStore
27984 * @position: the position of the item that is to be removed
27986 * Removes the item from @store that is at @position. @position must be
27987 * smaller than the current length of the list.
27989 * Use g_list_store_splice() to remove multiple items at the same time
27997 * g_list_store_remove_all:
27998 * @store: a #GListStore
28000 * Removes all items from @store.
28007 * g_list_store_sort:
28008 * @store: a #GListStore
28009 * @compare_func: (scope call): pairwise comparison function for sorting
28010 * @user_data: (closure): user data for @compare_func
28012 * Sort the items in @store according to @compare_func.
28019 * g_list_store_splice:
28020 * @store: a #GListStore
28021 * @position: the position at which to make the change
28022 * @n_removals: the number of items to remove
28023 * @additions: (array length=n_additions) (element-type GObject): the items to add
28024 * @n_additions: the number of items to add
28026 * Changes @store by removing @n_removals items and adding @n_additions
28027 * items to it. @additions must contain @n_additions items of type
28028 * #GListStore:item-type. %NULL is not permitted.
28030 * This function is more efficient than g_list_store_insert() and
28031 * g_list_store_remove(), because it only emits
28032 * #GListModel::items-changed once for the change.
28034 * This function takes a ref on each item in @additions.
28036 * The parameters @position and @n_removals must be correct (ie:
28037 * @position + @n_removals must be less than or equal to the length of
28038 * the list at the time this function is called).
28045 * g_loadable_icon_load:
28046 * @icon: a #GLoadableIcon.
28047 * @size: an integer.
28048 * @type: (out) (optional): a location to store the type of the loaded
28049 * icon, %NULL to ignore.
28050 * @cancellable: (allow-none): optional #GCancellable object, %NULL to
28052 * @error: a #GError location to store the error occurring, or %NULL
28055 * Loads a loadable icon. For the asynchronous version of this function,
28056 * see g_loadable_icon_load_async().
28058 * Returns: (transfer full): a #GInputStream to read the icon from.
28063 * g_loadable_icon_load_async:
28064 * @icon: a #GLoadableIcon.
28065 * @size: an integer.
28066 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
28067 * @callback: (scope async): a #GAsyncReadyCallback to call when the
28068 * request is satisfied
28069 * @user_data: (closure): the data to pass to callback function
28071 * Loads an icon asynchronously. To finish this function, see
28072 * g_loadable_icon_load_finish(). For the synchronous, blocking
28073 * version of this function, see g_loadable_icon_load().
28078 * g_loadable_icon_load_finish:
28079 * @icon: a #GLoadableIcon.
28080 * @res: a #GAsyncResult.
28081 * @type: (out) (optional): a location to store the type of the loaded
28082 * icon, %NULL to ignore.
28083 * @error: a #GError location to store the error occurring, or %NULL to
28086 * Finishes an asynchronous icon load started in g_loadable_icon_load_async().
28088 * Returns: (transfer full): a #GInputStream to read the icon from.
28095 * Returns a new #GVfs handle for a local vfs.
28097 * Returns: a new #GVfs handle.
28102 * g_memory_input_stream_add_bytes:
28103 * @stream: a #GMemoryInputStream
28104 * @bytes: input data
28106 * Appends @bytes to data that can be read from the input stream.
28113 * g_memory_input_stream_add_data:
28114 * @stream: a #GMemoryInputStream
28115 * @data: (array length=len) (element-type guint8) (transfer full): input data
28116 * @len: length of the data, may be -1 if @data is a nul-terminated string
28117 * @destroy: (allow-none): function that is called to free @data, or %NULL
28119 * Appends @data to data that can be read from the input stream
28124 * g_memory_input_stream_new:
28126 * Creates a new empty #GMemoryInputStream.
28128 * Returns: a new #GInputStream
28133 * g_memory_input_stream_new_from_bytes:
28134 * @bytes: a #GBytes
28136 * Creates a new #GMemoryInputStream with data from the given @bytes.
28138 * Returns: new #GInputStream read from @bytes
28144 * g_memory_input_stream_new_from_data:
28145 * @data: (array length=len) (element-type guint8) (transfer full): input data
28146 * @len: length of the data, may be -1 if @data is a nul-terminated string
28147 * @destroy: (allow-none): function that is called to free @data, or %NULL
28149 * Creates a new #GMemoryInputStream with data in memory of a given size.
28151 * Returns: new #GInputStream read from @data of @len bytes.
28156 * g_memory_output_stream_get_data:
28157 * @ostream: a #GMemoryOutputStream
28159 * Gets any loaded data from the @ostream.
28161 * Note that the returned pointer may become invalid on the next
28162 * write or truncate operation on the stream.
28164 * Returns: (transfer none): pointer to the stream's data, or %NULL if the data
28170 * g_memory_output_stream_get_data_size:
28171 * @ostream: a #GMemoryOutputStream
28173 * Returns the number of bytes from the start up to including the last
28174 * byte written in the stream that has not been truncated away.
28176 * Returns: the number of bytes written to the stream
28182 * g_memory_output_stream_get_size:
28183 * @ostream: a #GMemoryOutputStream
28185 * Gets the size of the currently allocated data area (available from
28186 * g_memory_output_stream_get_data()).
28188 * You probably don't want to use this function on resizable streams.
28189 * See g_memory_output_stream_get_data_size() instead. For resizable
28190 * streams the size returned by this function is an implementation
28191 * detail and may be change at any time in response to operations on the
28194 * If the stream is fixed-sized (ie: no realloc was passed to
28195 * g_memory_output_stream_new()) then this is the maximum size of the
28196 * stream and further writes will return %G_IO_ERROR_NO_SPACE.
28198 * In any case, if you want the number of bytes currently written to the
28199 * stream, use g_memory_output_stream_get_data_size().
28201 * Returns: the number of bytes allocated for the data buffer
28206 * g_memory_output_stream_new: (skip)
28207 * @data: (allow-none): pointer to a chunk of memory to use, or %NULL
28208 * @size: the size of @data
28209 * @realloc_function: (allow-none): a function with realloc() semantics (like g_realloc())
28210 * to be called when @data needs to be grown, or %NULL
28211 * @destroy_function: (allow-none): a function to be called on @data when the stream is
28212 * finalized, or %NULL
28214 * Creates a new #GMemoryOutputStream.
28216 * In most cases this is not the function you want. See
28217 * g_memory_output_stream_new_resizable() instead.
28219 * If @data is non-%NULL, the stream will use that for its internal storage.
28221 * If @realloc_fn is non-%NULL, it will be used for resizing the internal
28222 * storage when necessary and the stream will be considered resizable.
28223 * In that case, the stream will start out being (conceptually) empty.
28224 * @size is used only as a hint for how big @data is. Specifically,
28225 * seeking to the end of a newly-created stream will seek to zero, not
28226 * @size. Seeking past the end of the stream and then writing will
28227 * introduce a zero-filled gap.
28229 * If @realloc_fn is %NULL then the stream is fixed-sized. Seeking to
28230 * the end will seek to @size exactly. Writing past the end will give
28231 * an 'out of space' error. Attempting to seek past the end will fail.
28232 * Unlike the resizable case, seeking to an offset within the stream and
28233 * writing will preserve the bytes passed in as @data before that point
28234 * and will return them as part of g_memory_output_stream_steal_data().
28235 * If you intend to seek you should probably therefore ensure that @data
28236 * is properly initialised.
28238 * It is probably only meaningful to provide @data and @size in the case
28239 * that you want a fixed-sized stream. Put another way: if @realloc_fn
28240 * is non-%NULL then it makes most sense to give @data as %NULL and
28241 * @size as 0 (allowing #GMemoryOutputStream to do the initial
28242 * allocation for itself).
28244 * |[<!-- language="C" -->
28245 * // a stream that can grow
28246 * stream = g_memory_output_stream_new (NULL, 0, realloc, free);
28248 * // another stream that can grow
28249 * stream2 = g_memory_output_stream_new (NULL, 0, g_realloc, g_free);
28251 * // a fixed-size stream
28252 * data = malloc (200);
28253 * stream3 = g_memory_output_stream_new (data, 200, NULL, free);
28256 * Returns: A newly created #GMemoryOutputStream object.
28261 * g_memory_output_stream_new_resizable:
28263 * Creates a new #GMemoryOutputStream, using g_realloc() and g_free()
28264 * for memory allocation.
28271 * g_memory_output_stream_steal_as_bytes:
28272 * @ostream: a #GMemoryOutputStream
28274 * Returns data from the @ostream as a #GBytes. @ostream must be
28275 * closed before calling this function.
28277 * Returns: (transfer full): the stream's data
28283 * g_memory_output_stream_steal_data:
28284 * @ostream: a #GMemoryOutputStream
28286 * Gets any loaded data from the @ostream. Ownership of the data
28287 * is transferred to the caller; when no longer needed it must be
28288 * freed using the free function set in @ostream's
28289 * #GMemoryOutputStream:destroy-function property.
28291 * @ostream must be closed before calling this function.
28293 * Returns: (transfer full): the stream's data, or %NULL if it has previously
28300 * g_memory_settings_backend_new:
28302 * Creates a memory-backed #GSettingsBackend.
28304 * This backend allows changes to settings, but does not write them
28305 * to any backing storage, so the next time you run your application,
28306 * the memory backend will start out with the default values again.
28308 * Returns: (transfer full): a newly created #GSettingsBackend
28316 * @label: (allow-none): the section label, or %NULL
28317 * @detailed_action: (allow-none): the detailed action string, or %NULL
28319 * Convenience function for appending a normal menu item to the end of
28320 * @menu. Combine g_menu_item_new() and g_menu_insert_item() for a more
28321 * flexible alternative.
28328 * g_menu_append_item:
28330 * @item: a #GMenuItem to append
28332 * Appends @item to the end of @menu.
28334 * See g_menu_insert_item() for more information.
28341 * g_menu_append_section:
28343 * @label: (allow-none): the section label, or %NULL
28344 * @section: a #GMenuModel with the items of the section
28346 * Convenience function for appending a section menu item to the end of
28347 * @menu. Combine g_menu_item_new_section() and g_menu_insert_item() for a
28348 * more flexible alternative.
28355 * g_menu_append_submenu:
28357 * @label: (allow-none): the section label, or %NULL
28358 * @submenu: a #GMenuModel with the items of the submenu
28360 * Convenience function for appending a submenu menu item to the end of
28361 * @menu. Combine g_menu_item_new_submenu() and g_menu_insert_item() for a
28362 * more flexible alternative.
28369 * g_menu_attribute_iter_get_name:
28370 * @iter: a #GMenuAttributeIter
28372 * Gets the name of the attribute at the current iterator position, as
28375 * The iterator is not advanced.
28377 * Returns: the name of the attribute
28383 * g_menu_attribute_iter_get_next:
28384 * @iter: a #GMenuAttributeIter
28385 * @out_name: (out) (allow-none) (transfer none): the type of the attribute
28386 * @value: (out) (allow-none) (transfer full): the attribute value
28388 * This function combines g_menu_attribute_iter_next() with
28389 * g_menu_attribute_iter_get_name() and g_menu_attribute_iter_get_value().
28391 * First the iterator is advanced to the next (possibly first) attribute.
28392 * If that fails, then %FALSE is returned and there are no other
28395 * If successful, @name and @value are set to the name and value of the
28396 * attribute that has just been advanced to. At this point,
28397 * g_menu_attribute_iter_get_name() and g_menu_attribute_iter_get_value() will
28398 * return the same values again.
28400 * The value returned in @name remains valid for as long as the iterator
28401 * remains at the current position. The value returned in @value must
28402 * be unreffed using g_variant_unref() when it is no longer in use.
28404 * Returns: %TRUE on success, or %FALSE if there is no additional
28411 * g_menu_attribute_iter_get_value:
28412 * @iter: a #GMenuAttributeIter
28414 * Gets the value of the attribute at the current iterator position.
28416 * The iterator is not advanced.
28418 * Returns: (transfer full): the value of the current attribute
28424 * g_menu_attribute_iter_next:
28425 * @iter: a #GMenuAttributeIter
28427 * Attempts to advance the iterator to the next (possibly first)
28430 * %TRUE is returned on success, or %FALSE if there are no more
28433 * You must call this function when you first acquire the iterator
28434 * to advance it to the first attribute (and determine if the first
28435 * attribute exists at all).
28437 * Returns: %TRUE on success, or %FALSE when there are no more attributes
28446 * Marks @menu as frozen.
28448 * After the menu is frozen, it is an error to attempt to make any
28449 * changes to it. In effect this means that the #GMenu API must no
28452 * This function causes g_menu_model_is_mutable() to begin returning
28453 * %FALSE, which has some positive performance implications.
28462 * @position: the position at which to insert the item
28463 * @label: (allow-none): the section label, or %NULL
28464 * @detailed_action: (allow-none): the detailed action string, or %NULL
28466 * Convenience function for inserting a normal menu item into @menu.
28467 * Combine g_menu_item_new() and g_menu_insert_item() for a more flexible
28475 * g_menu_insert_item:
28477 * @position: the position at which to insert the item
28478 * @item: the #GMenuItem to insert
28480 * Inserts @item into @menu.
28482 * The "insertion" is actually done by copying all of the attribute and
28483 * link values of @item and using them to form a new item within @menu.
28484 * As such, @item itself is not really inserted, but rather, a menu item
28485 * that is exactly the same as the one presently described by @item.
28487 * This means that @item is essentially useless after the insertion
28488 * occurs. Any changes you make to it are ignored unless it is inserted
28489 * again (at which point its updated values will be copied).
28491 * You should probably just free @item once you're done.
28493 * There are many convenience functions to take care of common cases.
28494 * See g_menu_insert(), g_menu_insert_section() and
28495 * g_menu_insert_submenu() as well as "prepend" and "append" variants of
28496 * each of these functions.
28503 * g_menu_insert_section:
28505 * @position: the position at which to insert the item
28506 * @label: (allow-none): the section label, or %NULL
28507 * @section: a #GMenuModel with the items of the section
28509 * Convenience function for inserting a section menu item into @menu.
28510 * Combine g_menu_item_new_section() and g_menu_insert_item() for a more
28511 * flexible alternative.
28518 * g_menu_insert_submenu:
28520 * @position: the position at which to insert the item
28521 * @label: (allow-none): the section label, or %NULL
28522 * @submenu: a #GMenuModel with the items of the submenu
28524 * Convenience function for inserting a submenu menu item into @menu.
28525 * Combine g_menu_item_new_submenu() and g_menu_insert_item() for a more
28526 * flexible alternative.
28533 * g_menu_item_get_attribute:
28534 * @menu_item: a #GMenuItem
28535 * @attribute: the attribute name to query
28536 * @format_string: a #GVariant format string
28537 * @...: positional parameters, as per @format_string
28539 * Queries the named @attribute on @menu_item.
28541 * If the attribute exists and matches the #GVariantType corresponding
28542 * to @format_string then @format_string is used to deconstruct the
28543 * value into the positional parameters and %TRUE is returned.
28545 * If the attribute does not exist, or it does exist but has the wrong
28546 * type, then the positional parameters are ignored and %FALSE is
28549 * Returns: %TRUE if the named attribute was found with the expected
28556 * g_menu_item_get_attribute_value:
28557 * @menu_item: a #GMenuItem
28558 * @attribute: the attribute name to query
28559 * @expected_type: (allow-none): the expected type of the attribute
28561 * Queries the named @attribute on @menu_item.
28563 * If @expected_type is specified and the attribute does not have this
28564 * type, %NULL is returned. %NULL is also returned if the attribute
28565 * simply does not exist.
28567 * Returns: (transfer full): the attribute value, or %NULL
28573 * g_menu_item_get_link:
28574 * @menu_item: a #GMenuItem
28575 * @link: the link name to query
28577 * Queries the named @link on @menu_item.
28579 * Returns: (transfer full): the link, or %NULL
28586 * @label: (allow-none): the section label, or %NULL
28587 * @detailed_action: (allow-none): the detailed action string, or %NULL
28589 * Creates a new #GMenuItem.
28591 * If @label is non-%NULL it is used to set the "label" attribute of the
28594 * If @detailed_action is non-%NULL it is used to set the "action" and
28595 * possibly the "target" attribute of the new item. See
28596 * g_menu_item_set_detailed_action() for more information.
28598 * Returns: a new #GMenuItem
28604 * g_menu_item_new_from_model:
28605 * @model: a #GMenuModel
28606 * @item_index: the index of an item in @model
28608 * Creates a #GMenuItem as an exact copy of an existing menu item in a
28611 * @item_index must be valid (ie: be sure to call
28612 * g_menu_model_get_n_items() first).
28614 * Returns: a new #GMenuItem.
28620 * g_menu_item_new_section:
28621 * @label: (allow-none): the section label, or %NULL
28622 * @section: a #GMenuModel with the items of the section
28624 * Creates a new #GMenuItem representing a section.
28626 * This is a convenience API around g_menu_item_new() and
28627 * g_menu_item_set_section().
28629 * The effect of having one menu appear as a section of another is
28630 * exactly as it sounds: the items from @section become a direct part of
28631 * the menu that @menu_item is added to.
28633 * Visual separation is typically displayed between two non-empty
28634 * sections. If @label is non-%NULL then it will be encorporated into
28635 * this visual indication. This allows for labeled subsections of a
28638 * As a simple example, consider a typical "Edit" menu from a simple
28639 * program. It probably contains an "Undo" and "Redo" item, followed by
28640 * a separator, followed by "Cut", "Copy" and "Paste".
28642 * This would be accomplished by creating three #GMenu instances. The
28643 * first would be populated with the "Undo" and "Redo" items, and the
28644 * second with the "Cut", "Copy" and "Paste" items. The first and
28645 * second menus would then be added as submenus of the third. In XML
28646 * format, this would look something like the following:
28648 * <menu id='edit-menu'>
28650 * <item label='Undo'/>
28651 * <item label='Redo'/>
28654 * <item label='Cut'/>
28655 * <item label='Copy'/>
28656 * <item label='Paste'/>
28661 * The following example is exactly equivalent. It is more illustrative
28662 * of the exact relationship between the menus and items (keeping in
28663 * mind that the 'link' element defines a new menu that is linked to the
28664 * containing one). The style of the second example is more verbose and
28665 * difficult to read (and therefore not recommended except for the
28666 * purpose of understanding what is really going on).
28668 * <menu id='edit-menu'>
28670 * <link name='section'>
28671 * <item label='Undo'/>
28672 * <item label='Redo'/>
28676 * <link name='section'>
28677 * <item label='Cut'/>
28678 * <item label='Copy'/>
28679 * <item label='Paste'/>
28685 * Returns: a new #GMenuItem
28691 * g_menu_item_new_submenu:
28692 * @label: (allow-none): the section label, or %NULL
28693 * @submenu: a #GMenuModel with the items of the submenu
28695 * Creates a new #GMenuItem representing a submenu.
28697 * This is a convenience API around g_menu_item_new() and
28698 * g_menu_item_set_submenu().
28700 * Returns: a new #GMenuItem
28706 * g_menu_item_set_action_and_target:
28707 * @menu_item: a #GMenuItem
28708 * @action: (allow-none): the name of the action for this item
28709 * @format_string: (allow-none): a GVariant format string
28710 * @...: positional parameters, as per @format_string
28712 * Sets or unsets the "action" and "target" attributes of @menu_item.
28714 * If @action is %NULL then both the "action" and "target" attributes
28715 * are unset (and @format_string is ignored along with the positional
28718 * If @action is non-%NULL then the "action" attribute is set.
28719 * @format_string is then inspected. If it is non-%NULL then the proper
28720 * position parameters are collected to create a #GVariant instance to
28721 * use as the target value. If it is %NULL then the positional
28722 * parameters are ignored and the "target" attribute is unset.
28724 * See also g_menu_item_set_action_and_target_value() for an equivalent
28725 * call that directly accepts a #GVariant. See
28726 * g_menu_item_set_detailed_action() for a more convenient version that
28727 * works with string-typed targets.
28729 * See also g_menu_item_set_action_and_target_value() for a
28730 * description of the semantics of the action and target attributes.
28737 * g_menu_item_set_action_and_target_value:
28738 * @menu_item: a #GMenuItem
28739 * @action: (allow-none): the name of the action for this item
28740 * @target_value: (allow-none): a #GVariant to use as the action target
28742 * Sets or unsets the "action" and "target" attributes of @menu_item.
28744 * If @action is %NULL then both the "action" and "target" attributes
28745 * are unset (and @target_value is ignored).
28747 * If @action is non-%NULL then the "action" attribute is set. The
28748 * "target" attribute is then set to the value of @target_value if it is
28749 * non-%NULL or unset otherwise.
28751 * Normal menu items (ie: not submenu, section or other custom item
28752 * types) are expected to have the "action" attribute set to identify
28753 * the action that they are associated with. The state type of the
28754 * action help to determine the disposition of the menu item. See
28755 * #GAction and #GActionGroup for an overview of actions.
28757 * In general, clicking on the menu item will result in activation of
28758 * the named action with the "target" attribute given as the parameter
28759 * to the action invocation. If the "target" attribute is not set then
28760 * the action is invoked with no parameter.
28762 * If the action has no state then the menu item is usually drawn as a
28763 * plain menu item (ie: with no additional decoration).
28765 * If the action has a boolean state then the menu item is usually drawn
28766 * as a toggle menu item (ie: with a checkmark or equivalent
28767 * indication). The item should be marked as 'toggled' or 'checked'
28768 * when the boolean state is %TRUE.
28770 * If the action has a string state then the menu item is usually drawn
28771 * as a radio menu item (ie: with a radio bullet or equivalent
28772 * indication). The item should be marked as 'selected' when the string
28773 * state is equal to the value of the @target property.
28775 * See g_menu_item_set_action_and_target() or
28776 * g_menu_item_set_detailed_action() for two equivalent calls that are
28777 * probably more convenient for most uses.
28784 * g_menu_item_set_attribute:
28785 * @menu_item: a #GMenuItem
28786 * @attribute: the attribute to set
28787 * @format_string: (allow-none): a #GVariant format string, or %NULL
28788 * @...: positional parameters, as per @format_string
28790 * Sets or unsets an attribute on @menu_item.
28792 * The attribute to set or unset is specified by @attribute. This
28793 * can be one of the standard attribute names %G_MENU_ATTRIBUTE_LABEL,
28794 * %G_MENU_ATTRIBUTE_ACTION, %G_MENU_ATTRIBUTE_TARGET, or a custom
28796 * Attribute names are restricted to lowercase characters, numbers
28797 * and '-'. Furthermore, the names must begin with a lowercase character,
28798 * must not end with a '-', and must not contain consecutive dashes.
28800 * If @format_string is non-%NULL then the proper position parameters
28801 * are collected to create a #GVariant instance to use as the attribute
28802 * value. If it is %NULL then the positional parameterrs are ignored
28803 * and the named attribute is unset.
28805 * See also g_menu_item_set_attribute_value() for an equivalent call
28806 * that directly accepts a #GVariant.
28813 * g_menu_item_set_attribute_value:
28814 * @menu_item: a #GMenuItem
28815 * @attribute: the attribute to set
28816 * @value: (allow-none): a #GVariant to use as the value, or %NULL
28818 * Sets or unsets an attribute on @menu_item.
28820 * The attribute to set or unset is specified by @attribute. This
28821 * can be one of the standard attribute names %G_MENU_ATTRIBUTE_LABEL,
28822 * %G_MENU_ATTRIBUTE_ACTION, %G_MENU_ATTRIBUTE_TARGET, or a custom
28824 * Attribute names are restricted to lowercase characters, numbers
28825 * and '-'. Furthermore, the names must begin with a lowercase character,
28826 * must not end with a '-', and must not contain consecutive dashes.
28828 * must consist only of lowercase
28829 * ASCII characters, digits and '-'.
28831 * If @value is non-%NULL then it is used as the new value for the
28832 * attribute. If @value is %NULL then the attribute is unset. If
28833 * the @value #GVariant is floating, it is consumed.
28835 * See also g_menu_item_set_attribute() for a more convenient way to do
28843 * g_menu_item_set_detailed_action:
28844 * @menu_item: a #GMenuItem
28845 * @detailed_action: the "detailed" action string
28847 * Sets the "action" and possibly the "target" attribute of @menu_item.
28849 * The format of @detailed_action is the same format parsed by
28850 * g_action_parse_detailed_name().
28852 * See g_menu_item_set_action_and_target() or
28853 * g_menu_item_set_action_and_target_value() for more flexible (but
28854 * slightly less convenient) alternatives.
28856 * See also g_menu_item_set_action_and_target_value() for a description of
28857 * the semantics of the action and target attributes.
28864 * g_menu_item_set_icon:
28865 * @menu_item: a #GMenuItem
28866 * @icon: a #GIcon, or %NULL
28868 * Sets (or unsets) the icon on @menu_item.
28870 * This call is the same as calling g_icon_serialize() and using the
28871 * result as the value to g_menu_item_set_attribute_value() for
28872 * %G_MENU_ATTRIBUTE_ICON.
28874 * This API is only intended for use with "noun" menu items; things like
28875 * bookmarks or applications in an "Open With" menu. Don't use it on
28876 * menu items corresponding to verbs (eg: stock icons for 'Save' or
28879 * If @icon is %NULL then the icon is unset.
28886 * g_menu_item_set_label:
28887 * @menu_item: a #GMenuItem
28888 * @label: (allow-none): the label to set, or %NULL to unset
28890 * Sets or unsets the "label" attribute of @menu_item.
28892 * If @label is non-%NULL it is used as the label for the menu item. If
28893 * it is %NULL then the label attribute is unset.
28900 * g_menu_item_set_link:
28901 * @menu_item: a #GMenuItem
28902 * @link: type of link to establish or unset
28903 * @model: (allow-none): the #GMenuModel to link to (or %NULL to unset)
28905 * Creates a link from @menu_item to @model if non-%NULL, or unsets it.
28907 * Links are used to establish a relationship between a particular menu
28908 * item and another menu. For example, %G_MENU_LINK_SUBMENU is used to
28909 * associate a submenu with a particular menu item, and %G_MENU_LINK_SECTION
28910 * is used to create a section. Other types of link can be used, but there
28911 * is no guarantee that clients will be able to make sense of them.
28912 * Link types are restricted to lowercase characters, numbers
28913 * and '-'. Furthermore, the names must begin with a lowercase character,
28914 * must not end with a '-', and must not contain consecutive dashes.
28921 * g_menu_item_set_section:
28922 * @menu_item: a #GMenuItem
28923 * @section: (allow-none): a #GMenuModel, or %NULL
28925 * Sets or unsets the "section" link of @menu_item to @section.
28927 * The effect of having one menu appear as a section of another is
28928 * exactly as it sounds: the items from @section become a direct part of
28929 * the menu that @menu_item is added to. See g_menu_item_new_section()
28930 * for more information about what it means for a menu item to be a
28938 * g_menu_item_set_submenu:
28939 * @menu_item: a #GMenuItem
28940 * @submenu: (allow-none): a #GMenuModel, or %NULL
28942 * Sets or unsets the "submenu" link of @menu_item to @submenu.
28944 * If @submenu is non-%NULL, it is linked to. If it is %NULL then the
28947 * The effect of having one menu appear as a submenu of another is
28948 * exactly as it sounds.
28955 * g_menu_link_iter_get_name:
28956 * @iter: a #GMenuLinkIter
28958 * Gets the name of the link at the current iterator position.
28960 * The iterator is not advanced.
28962 * Returns: the type of the link
28968 * g_menu_link_iter_get_next:
28969 * @iter: a #GMenuLinkIter
28970 * @out_link: (out) (allow-none) (transfer none): the name of the link
28971 * @value: (out) (allow-none) (transfer full): the linked #GMenuModel
28973 * This function combines g_menu_link_iter_next() with
28974 * g_menu_link_iter_get_name() and g_menu_link_iter_get_value().
28976 * First the iterator is advanced to the next (possibly first) link.
28977 * If that fails, then %FALSE is returned and there are no other effects.
28979 * If successful, @out_link and @value are set to the name and #GMenuModel
28980 * of the link that has just been advanced to. At this point,
28981 * g_menu_link_iter_get_name() and g_menu_link_iter_get_value() will return the
28982 * same values again.
28984 * The value returned in @out_link remains valid for as long as the iterator
28985 * remains at the current position. The value returned in @value must
28986 * be unreffed using g_object_unref() when it is no longer in use.
28988 * Returns: %TRUE on success, or %FALSE if there is no additional link
28994 * g_menu_link_iter_get_value:
28995 * @iter: a #GMenuLinkIter
28997 * Gets the linked #GMenuModel at the current iterator position.
28999 * The iterator is not advanced.
29001 * Returns: (transfer full): the #GMenuModel that is linked to
29007 * g_menu_link_iter_next:
29008 * @iter: a #GMenuLinkIter
29010 * Attempts to advance the iterator to the next (possibly first)
29013 * %TRUE is returned on success, or %FALSE if there are no more links.
29015 * You must call this function when you first acquire the iterator to
29016 * advance it to the first link (and determine if the first link exists
29019 * Returns: %TRUE on success, or %FALSE when there are no more links
29025 * g_menu_model_get_item_attribute:
29026 * @model: a #GMenuModel
29027 * @item_index: the index of the item
29028 * @attribute: the attribute to query
29029 * @format_string: a #GVariant format string
29030 * @...: positional parameters, as per @format_string
29032 * Queries item at position @item_index in @model for the attribute
29033 * specified by @attribute.
29035 * If the attribute exists and matches the #GVariantType corresponding
29036 * to @format_string then @format_string is used to deconstruct the
29037 * value into the positional parameters and %TRUE is returned.
29039 * If the attribute does not exist, or it does exist but has the wrong
29040 * type, then the positional parameters are ignored and %FALSE is
29043 * This function is a mix of g_menu_model_get_item_attribute_value() and
29044 * g_variant_get(), followed by a g_variant_unref(). As such,
29045 * @format_string must make a complete copy of the data (since the
29046 * #GVariant may go away after the call to g_variant_unref()). In
29047 * particular, no '&' characters are allowed in @format_string.
29049 * Returns: %TRUE if the named attribute was found with the expected
29056 * g_menu_model_get_item_attribute_value:
29057 * @model: a #GMenuModel
29058 * @item_index: the index of the item
29059 * @attribute: the attribute to query
29060 * @expected_type: (allow-none): the expected type of the attribute, or
29063 * Queries the item at position @item_index in @model for the attribute
29064 * specified by @attribute.
29066 * If @expected_type is non-%NULL then it specifies the expected type of
29067 * the attribute. If it is %NULL then any type will be accepted.
29069 * If the attribute exists and matches @expected_type (or if the
29070 * expected type is unspecified) then the value is returned.
29072 * If the attribute does not exist, or does not match the expected type
29073 * then %NULL is returned.
29075 * Returns: (transfer full): the value of the attribute
29081 * g_menu_model_get_item_link:
29082 * @model: a #GMenuModel
29083 * @item_index: the index of the item
29084 * @link: the link to query
29086 * Queries the item at position @item_index in @model for the link
29087 * specified by @link.
29089 * If the link exists, the linked #GMenuModel is returned. If the link
29090 * does not exist, %NULL is returned.
29092 * Returns: (transfer full): the linked #GMenuModel, or %NULL
29098 * g_menu_model_get_n_items:
29099 * @model: a #GMenuModel
29101 * Query the number of items in @model.
29103 * Returns: the number of items
29109 * g_menu_model_is_mutable:
29110 * @model: a #GMenuModel
29112 * Queries if @model is mutable.
29114 * An immutable #GMenuModel will never emit the #GMenuModel::items-changed
29115 * signal. Consumers of the model may make optimisations accordingly.
29117 * Returns: %TRUE if the model is mutable (ie: "items-changed" may be
29124 * g_menu_model_items_changed:
29125 * @model: a #GMenuModel
29126 * @position: the position of the change
29127 * @removed: the number of items removed
29128 * @added: the number of items added
29130 * Requests emission of the #GMenuModel::items-changed signal on @model.
29132 * This function should never be called except by #GMenuModel
29133 * subclasses. Any other calls to this function will very likely lead
29134 * to a violation of the interface of the model.
29136 * The implementation should update its internal representation of the
29137 * menu before emitting the signal. The implementation should further
29138 * expect to receive queries about the new state of the menu (and
29139 * particularly added menu items) while signal handlers are running.
29141 * The implementation must dispatch this call directly from a mainloop
29142 * entry and not in response to calls -- particularly those from the
29143 * #GMenuModel API. Said another way: the menu must not change while
29144 * user code is running without returning to the mainloop.
29151 * g_menu_model_iterate_item_attributes:
29152 * @model: a #GMenuModel
29153 * @item_index: the index of the item
29155 * Creates a #GMenuAttributeIter to iterate over the attributes of
29156 * the item at position @item_index in @model.
29158 * You must free the iterator with g_object_unref() when you are done.
29160 * Returns: (transfer full): a new #GMenuAttributeIter
29166 * g_menu_model_iterate_item_links:
29167 * @model: a #GMenuModel
29168 * @item_index: the index of the item
29170 * Creates a #GMenuLinkIter to iterate over the links of the item at
29171 * position @item_index in @model.
29173 * You must free the iterator with g_object_unref() when you are done.
29175 * Returns: (transfer full): a new #GMenuLinkIter
29183 * Creates a new #GMenu.
29185 * The new menu has no items.
29187 * Returns: a new #GMenu
29195 * @label: (allow-none): the section label, or %NULL
29196 * @detailed_action: (allow-none): the detailed action string, or %NULL
29198 * Convenience function for prepending a normal menu item to the start
29199 * of @menu. Combine g_menu_item_new() and g_menu_insert_item() for a more
29200 * flexible alternative.
29207 * g_menu_prepend_item:
29209 * @item: a #GMenuItem to prepend
29211 * Prepends @item to the start of @menu.
29213 * See g_menu_insert_item() for more information.
29220 * g_menu_prepend_section:
29222 * @label: (allow-none): the section label, or %NULL
29223 * @section: a #GMenuModel with the items of the section
29225 * Convenience function for prepending a section menu item to the start
29226 * of @menu. Combine g_menu_item_new_section() and g_menu_insert_item() for
29227 * a more flexible alternative.
29234 * g_menu_prepend_submenu:
29236 * @label: (allow-none): the section label, or %NULL
29237 * @submenu: a #GMenuModel with the items of the submenu
29239 * Convenience function for prepending a submenu menu item to the start
29240 * of @menu. Combine g_menu_item_new_submenu() and g_menu_insert_item() for
29241 * a more flexible alternative.
29250 * @position: the position of the item to remove
29252 * Removes an item from the menu.
29254 * @position gives the index of the item to remove.
29256 * It is an error if position is not in range the range from 0 to one
29257 * less than the number of items in the menu.
29259 * It is not possible to remove items by identity since items are added
29260 * to the menu simply by copying their links and attributes (ie:
29261 * identity of the item itself is not preserved).
29268 * g_menu_remove_all:
29271 * Removes all items in the menu.
29278 * g_mount_can_eject:
29279 * @mount: a #GMount.
29281 * Checks if @mount can be eject.
29283 * Returns: %TRUE if the @mount can be ejected.
29288 * g_mount_can_unmount:
29289 * @mount: a #GMount.
29291 * Checks if @mount can be mounted.
29293 * Returns: %TRUE if the @mount can be unmounted.
29299 * @mount: a #GMount.
29300 * @flags: flags affecting the unmount if required for eject
29301 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
29302 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
29303 * @user_data: user data passed to @callback.
29305 * Ejects a mount. This is an asynchronous operation, and is
29306 * finished by calling g_mount_eject_finish() with the @mount
29307 * and #GAsyncResult data returned in the @callback.
29309 * Deprecated: 2.22: Use g_mount_eject_with_operation() instead.
29314 * g_mount_eject_finish:
29315 * @mount: a #GMount.
29316 * @result: a #GAsyncResult.
29317 * @error: a #GError location to store the error occurring, or %NULL to
29320 * Finishes ejecting a mount. If any errors occurred during the operation,
29321 * @error will be set to contain the errors and %FALSE will be returned.
29323 * Returns: %TRUE if the mount was successfully ejected. %FALSE otherwise.
29324 * Deprecated: 2.22: Use g_mount_eject_with_operation_finish() instead.
29329 * g_mount_eject_with_operation:
29330 * @mount: a #GMount.
29331 * @flags: flags affecting the unmount if required for eject
29332 * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid
29333 * user interaction.
29334 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
29335 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
29336 * @user_data: user data passed to @callback.
29338 * Ejects a mount. This is an asynchronous operation, and is
29339 * finished by calling g_mount_eject_with_operation_finish() with the @mount
29340 * and #GAsyncResult data returned in the @callback.
29347 * g_mount_eject_with_operation_finish:
29348 * @mount: a #GMount.
29349 * @result: a #GAsyncResult.
29350 * @error: a #GError location to store the error occurring, or %NULL to
29353 * Finishes ejecting a mount. If any errors occurred during the operation,
29354 * @error will be set to contain the errors and %FALSE will be returned.
29356 * Returns: %TRUE if the mount was successfully ejected. %FALSE otherwise.
29362 * g_mount_get_default_location:
29363 * @mount: a #GMount.
29365 * Gets the default location of @mount. The default location of the given
29366 * @mount is a path that reflects the main entry point for the user (e.g.
29367 * the home directory, or the root of the volume).
29369 * Returns: (transfer full): a #GFile.
29370 * The returned object should be unreffed with
29371 * g_object_unref() when no longer needed.
29376 * g_mount_get_drive:
29377 * @mount: a #GMount.
29379 * Gets the drive for the @mount.
29381 * This is a convenience method for getting the #GVolume and then
29382 * using that object to get the #GDrive.
29384 * Returns: (transfer full): a #GDrive or %NULL if @mount is not associated with a volume or a drive.
29385 * The returned object should be unreffed with
29386 * g_object_unref() when no longer needed.
29391 * g_mount_get_icon:
29392 * @mount: a #GMount.
29394 * Gets the icon for @mount.
29396 * Returns: (transfer full): a #GIcon.
29397 * The returned object should be unreffed with
29398 * g_object_unref() when no longer needed.
29403 * g_mount_get_name:
29404 * @mount: a #GMount.
29406 * Gets the name of @mount.
29408 * Returns: the name for the given @mount.
29409 * The returned string should be freed with g_free()
29410 * when no longer needed.
29415 * g_mount_get_root:
29416 * @mount: a #GMount.
29418 * Gets the root directory on @mount.
29420 * Returns: (transfer full): a #GFile.
29421 * The returned object should be unreffed with
29422 * g_object_unref() when no longer needed.
29427 * g_mount_get_sort_key:
29428 * @mount: A #GMount.
29430 * Gets the sort key for @mount, if any.
29432 * Returns: Sorting key for @mount or %NULL if no such key is available.
29438 * g_mount_get_symbolic_icon:
29439 * @mount: a #GMount.
29441 * Gets the symbolic icon for @mount.
29443 * Returns: (transfer full): a #GIcon.
29444 * The returned object should be unreffed with
29445 * g_object_unref() when no longer needed.
29451 * g_mount_get_uuid:
29452 * @mount: a #GMount.
29454 * Gets the UUID for the @mount. The reference is typically based on
29455 * the file system UUID for the mount in question and should be
29456 * considered an opaque string. Returns %NULL if there is no UUID
29459 * Returns: the UUID for @mount or %NULL if no UUID can be computed.
29460 * The returned string should be freed with g_free()
29461 * when no longer needed.
29466 * g_mount_get_volume:
29467 * @mount: a #GMount.
29469 * Gets the volume for the @mount.
29471 * Returns: (transfer full): a #GVolume or %NULL if @mount is not associated with a volume.
29472 * The returned object should be unreffed with
29473 * g_object_unref() when no longer needed.
29478 * g_mount_guess_content_type:
29479 * @mount: a #GMount
29480 * @force_rescan: Whether to force a rescan of the content.
29481 * Otherwise a cached result will be used if available
29482 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
29483 * @callback: a #GAsyncReadyCallback
29484 * @user_data: user data passed to @callback
29486 * Tries to guess the type of content stored on @mount. Returns one or
29487 * more textual identifiers of well-known content types (typically
29488 * prefixed with "x-content/"), e.g. x-content/image-dcf for camera
29489 * memory cards. See the
29490 * [shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec)
29491 * specification for more on x-content types.
29493 * This is an asynchronous operation (see
29494 * g_mount_guess_content_type_sync() for the synchronous version), and
29495 * is finished by calling g_mount_guess_content_type_finish() with the
29496 * @mount and #GAsyncResult data returned in the @callback.
29503 * g_mount_guess_content_type_finish:
29504 * @mount: a #GMount
29505 * @result: a #GAsyncResult
29506 * @error: a #GError location to store the error occurring, or %NULL to
29509 * Finishes guessing content types of @mount. If any errors occurred
29510 * during the operation, @error will be set to contain the errors and
29511 * %FALSE will be returned. In particular, you may get an
29512 * %G_IO_ERROR_NOT_SUPPORTED if the mount does not support content
29515 * Returns: (transfer full) (element-type utf8): a %NULL-terminated array of content types or %NULL on error.
29516 * Caller should free this array with g_strfreev() when done with it.
29522 * g_mount_guess_content_type_sync:
29523 * @mount: a #GMount
29524 * @force_rescan: Whether to force a rescan of the content.
29525 * Otherwise a cached result will be used if available
29526 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
29527 * @error: a #GError location to store the error occurring, or %NULL to
29530 * Tries to guess the type of content stored on @mount. Returns one or
29531 * more textual identifiers of well-known content types (typically
29532 * prefixed with "x-content/"), e.g. x-content/image-dcf for camera
29533 * memory cards. See the
29534 * [shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec)
29535 * specification for more on x-content types.
29537 * This is an synchronous operation and as such may block doing IO;
29538 * see g_mount_guess_content_type() for the asynchronous version.
29540 * Returns: (transfer full) (element-type utf8): a %NULL-terminated array of content types or %NULL on error.
29541 * Caller should free this array with g_strfreev() when done with it.
29547 * g_mount_is_shadowed:
29548 * @mount: A #GMount.
29550 * Determines if @mount is shadowed. Applications or libraries should
29551 * avoid displaying @mount in the user interface if it is shadowed.
29553 * A mount is said to be shadowed if there exists one or more user
29554 * visible objects (currently #GMount objects) with a root that is
29555 * inside the root of @mount.
29557 * One application of shadow mounts is when exposing a single file
29558 * system that is used to address several logical volumes. In this
29559 * situation, a #GVolumeMonitor implementation would create two
29560 * #GVolume objects (for example, one for the camera functionality of
29561 * the device and one for a SD card reader on the device) with
29562 * activation URIs `gphoto2://[usb:001,002]/store1/`
29563 * and `gphoto2://[usb:001,002]/store2/`. When the
29564 * underlying mount (with root
29565 * `gphoto2://[usb:001,002]/`) is mounted, said
29566 * #GVolumeMonitor implementation would create two #GMount objects
29567 * (each with their root matching the corresponding volume activation
29568 * root) that would shadow the original mount.
29570 * The proxy monitor in GVfs 2.26 and later, automatically creates and
29571 * manage shadow mounts (and shadows the underlying mount) if the
29572 * activation root on a #GVolume is set.
29574 * Returns: %TRUE if @mount is shadowed.
29580 * g_mount_operation_get_anonymous:
29581 * @op: a #GMountOperation.
29583 * Check to see whether the mount operation is being used
29584 * for an anonymous user.
29586 * Returns: %TRUE if mount operation is anonymous.
29591 * g_mount_operation_get_choice:
29592 * @op: a #GMountOperation.
29594 * Gets a choice from the mount operation.
29596 * Returns: an integer containing an index of the user's choice from
29597 * the choice's list, or %0.
29602 * g_mount_operation_get_domain:
29603 * @op: a #GMountOperation.
29605 * Gets the domain of the mount operation.
29607 * Returns: a string set to the domain.
29612 * g_mount_operation_get_password:
29613 * @op: a #GMountOperation.
29615 * Gets a password from the mount operation.
29617 * Returns: a string containing the password within @op.
29622 * g_mount_operation_get_password_save:
29623 * @op: a #GMountOperation.
29625 * Gets the state of saving passwords for the mount operation.
29627 * Returns: a #GPasswordSave flag.
29632 * g_mount_operation_get_username:
29633 * @op: a #GMountOperation.
29635 * Get the user name from the mount operation.
29637 * Returns: a string containing the user name.
29642 * g_mount_operation_new:
29644 * Creates a new mount operation.
29646 * Returns: a #GMountOperation.
29651 * g_mount_operation_reply:
29652 * @op: a #GMountOperation
29653 * @result: a #GMountOperationResult
29655 * Emits the #GMountOperation::reply signal.
29660 * g_mount_operation_set_anonymous:
29661 * @op: a #GMountOperation.
29662 * @anonymous: boolean value.
29664 * Sets the mount operation to use an anonymous user if @anonymous is %TRUE.
29669 * g_mount_operation_set_choice:
29670 * @op: a #GMountOperation.
29671 * @choice: an integer.
29673 * Sets a default choice for the mount operation.
29678 * g_mount_operation_set_domain:
29679 * @op: a #GMountOperation.
29680 * @domain: the domain to set.
29682 * Sets the mount operation's domain.
29687 * g_mount_operation_set_password:
29688 * @op: a #GMountOperation.
29689 * @password: password to set.
29691 * Sets the mount operation's password to @password.
29696 * g_mount_operation_set_password_save:
29697 * @op: a #GMountOperation.
29698 * @save: a set of #GPasswordSave flags.
29700 * Sets the state of saving passwords for the mount operation.
29705 * g_mount_operation_set_username:
29706 * @op: a #GMountOperation.
29707 * @username: input username.
29709 * Sets the user name within @op to @username.
29715 * @mount: a #GMount.
29716 * @flags: flags affecting the operation
29717 * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid
29718 * user interaction.
29719 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
29720 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
29721 * @user_data: user data passed to @callback.
29723 * Remounts a mount. This is an asynchronous operation, and is
29724 * finished by calling g_mount_remount_finish() with the @mount
29725 * and #GAsyncResults data returned in the @callback.
29727 * Remounting is useful when some setting affecting the operation
29728 * of the volume has been changed, as these may need a remount to
29729 * take affect. While this is semantically equivalent with unmounting
29730 * and then remounting not all backends might need to actually be
29736 * g_mount_remount_finish:
29737 * @mount: a #GMount.
29738 * @result: a #GAsyncResult.
29739 * @error: a #GError location to store the error occurring, or %NULL to
29742 * Finishes remounting a mount. If any errors occurred during the operation,
29743 * @error will be set to contain the errors and %FALSE will be returned.
29745 * Returns: %TRUE if the mount was successfully remounted. %FALSE otherwise.
29751 * @mount: A #GMount.
29753 * Increments the shadow count on @mount. Usually used by
29754 * #GVolumeMonitor implementations when creating a shadow mount for
29755 * @mount, see g_mount_is_shadowed() for more information. The caller
29756 * will need to emit the #GMount::changed signal on @mount manually.
29764 * @mount: a #GMount.
29765 * @flags: flags affecting the operation
29766 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
29767 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
29768 * @user_data: user data passed to @callback.
29770 * Unmounts a mount. This is an asynchronous operation, and is
29771 * finished by calling g_mount_unmount_finish() with the @mount
29772 * and #GAsyncResult data returned in the @callback.
29774 * Deprecated: 2.22: Use g_mount_unmount_with_operation() instead.
29779 * g_mount_unmount_finish:
29780 * @mount: a #GMount.
29781 * @result: a #GAsyncResult.
29782 * @error: a #GError location to store the error occurring, or %NULL to
29785 * Finishes unmounting a mount. If any errors occurred during the operation,
29786 * @error will be set to contain the errors and %FALSE will be returned.
29788 * Returns: %TRUE if the mount was successfully unmounted. %FALSE otherwise.
29789 * Deprecated: 2.22: Use g_mount_unmount_with_operation_finish() instead.
29794 * g_mount_unmount_with_operation:
29795 * @mount: a #GMount.
29796 * @flags: flags affecting the operation
29797 * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid
29798 * user interaction.
29799 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
29800 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
29801 * @user_data: user data passed to @callback.
29803 * Unmounts a mount. This is an asynchronous operation, and is
29804 * finished by calling g_mount_unmount_with_operation_finish() with the @mount
29805 * and #GAsyncResult data returned in the @callback.
29812 * g_mount_unmount_with_operation_finish:
29813 * @mount: a #GMount.
29814 * @result: a #GAsyncResult.
29815 * @error: a #GError location to store the error occurring, or %NULL to
29818 * Finishes unmounting a mount. If any errors occurred during the operation,
29819 * @error will be set to contain the errors and %FALSE will be returned.
29821 * Returns: %TRUE if the mount was successfully unmounted. %FALSE otherwise.
29827 * g_mount_unshadow:
29828 * @mount: A #GMount.
29830 * Decrements the shadow count on @mount. Usually used by
29831 * #GVolumeMonitor implementations when destroying a shadow mount for
29832 * @mount, see g_mount_is_shadowed() for more information. The caller
29833 * will need to emit the #GMount::changed signal on @mount manually.
29840 * g_native_socket_address_new:
29841 * @native: a native address object
29842 * @len: the length of @native, in bytes
29844 * Creates a new #GNativeSocketAddress for @native and @len.
29846 * Returns: a new #GNativeSocketAddress
29852 * g_network_address_get_hostname:
29853 * @addr: a #GNetworkAddress
29855 * Gets @addr's hostname. This might be either UTF-8 or ASCII-encoded,
29856 * depending on what @addr was created with.
29858 * Returns: @addr's hostname
29864 * g_network_address_get_port:
29865 * @addr: a #GNetworkAddress
29867 * Gets @addr's port number
29869 * Returns: @addr's port (which may be 0)
29875 * g_network_address_get_scheme:
29876 * @addr: a #GNetworkAddress
29878 * Gets @addr's scheme
29880 * Returns: @addr's scheme (%NULL if not built from URI)
29886 * g_network_address_new:
29887 * @hostname: the hostname
29890 * Creates a new #GSocketConnectable for connecting to the given
29891 * @hostname and @port.
29893 * Note that depending on the configuration of the machine, a
29894 * @hostname of `localhost` may refer to the IPv4 loopback address
29895 * only, or to both IPv4 and IPv6; use
29896 * g_network_address_new_loopback() to create a #GNetworkAddress that
29897 * is guaranteed to resolve to both addresses.
29899 * Returns: (transfer full) (type GNetworkAddress): the new #GNetworkAddress
29905 * g_network_address_new_loopback:
29908 * Creates a new #GSocketConnectable for connecting to the local host
29909 * over a loopback connection to the given @port. This is intended for
29910 * use in connecting to local services which may be running on IPv4 or
29913 * The connectable will return IPv4 and IPv6 loopback addresses,
29914 * regardless of how the host resolves `localhost`. By contrast,
29915 * g_network_address_new() will often only return an IPv4 address when
29916 * resolving `localhost`, and an IPv6 address for `localhost6`.
29918 * g_network_address_get_hostname() will always return `localhost` for
29919 * #GNetworkAddresses created with this constructor.
29921 * Returns: (transfer full) (type GNetworkAddress): the new #GNetworkAddress
29927 * g_network_address_parse:
29928 * @host_and_port: the hostname and optionally a port
29929 * @default_port: the default port if not in @host_and_port
29930 * @error: a pointer to a #GError, or %NULL
29932 * Creates a new #GSocketConnectable for connecting to the given
29933 * @hostname and @port. May fail and return %NULL in case
29934 * parsing @host_and_port fails.
29936 * @host_and_port may be in any of a number of recognised formats; an IPv6
29937 * address, an IPv4 address, or a domain name (in which case a DNS
29938 * lookup is performed). Quoting with [] is supported for all address
29939 * types. A port override may be specified in the usual way with a
29942 * If no port is specified in @host_and_port then @default_port will be
29943 * used as the port number to connect to.
29945 * In general, @host_and_port is expected to be provided by the user
29946 * (allowing them to give the hostname, and a port overide if necessary)
29947 * and @default_port is expected to be provided by the application.
29949 * (The port component of @host_and_port can also be specified as a
29950 * service name rather than as a numeric port, but this functionality
29951 * is deprecated, because it depends on the contents of /etc/services,
29952 * which is generally quite sparse on platforms other than Linux.)
29954 * Returns: (transfer full) (type GNetworkAddress): the new
29955 * #GNetworkAddress, or %NULL on error
29961 * g_network_address_parse_uri:
29962 * @uri: the hostname and optionally a port
29963 * @default_port: The default port if none is found in the URI
29964 * @error: a pointer to a #GError, or %NULL
29966 * Creates a new #GSocketConnectable for connecting to the given
29967 * @uri. May fail and return %NULL in case parsing @uri fails.
29969 * Using this rather than g_network_address_new() or
29970 * g_network_address_parse() allows #GSocketClient to determine
29971 * when to use application-specific proxy protocols.
29973 * Returns: (transfer full) (type GNetworkAddress): the new
29974 * #GNetworkAddress, or %NULL on error
29980 * g_network_monitor_base_add_network:
29981 * @monitor: the #GNetworkMonitorBase
29982 * @network: a #GInetAddressMask
29984 * Adds @network to @monitor's list of available networks.
29991 * g_network_monitor_base_remove_network:
29992 * @monitor: the #GNetworkMonitorBase
29993 * @network: a #GInetAddressMask
29995 * Removes @network from @monitor's list of available networks.
30002 * g_network_monitor_base_set_networks:
30003 * @monitor: the #GNetworkMonitorBase
30004 * @networks: (array length=length): an array of #GInetAddressMask
30005 * @length: length of @networks
30007 * Drops @monitor's current list of available networks and replaces
30008 * it with @networks.
30013 * g_network_monitor_can_reach:
30014 * @monitor: a #GNetworkMonitor
30015 * @connectable: a #GSocketConnectable
30016 * @cancellable: (allow-none): a #GCancellable, or %NULL
30017 * @error: return location for a #GError, or %NULL
30019 * Attempts to determine whether or not the host pointed to by
30020 * @connectable can be reached, without actually trying to connect to
30023 * This may return %TRUE even when #GNetworkMonitor:network-available
30024 * is %FALSE, if, for example, @monitor can determine that
30025 * @connectable refers to a host on a local network.
30027 * If @monitor believes that an attempt to connect to @connectable
30028 * will succeed, it will return %TRUE. Otherwise, it will return
30029 * %FALSE and set @error to an appropriate error (such as
30030 * %G_IO_ERROR_HOST_UNREACHABLE).
30032 * Note that although this does not attempt to connect to
30033 * @connectable, it may still block for a brief period of time (eg,
30034 * trying to do multicast DNS on the local network), so if you do not
30035 * want to block, you should use g_network_monitor_can_reach_async().
30037 * Returns: %TRUE if @connectable is reachable, %FALSE if not.
30043 * g_network_monitor_can_reach_async:
30044 * @monitor: a #GNetworkMonitor
30045 * @connectable: a #GSocketConnectable
30046 * @cancellable: (allow-none): a #GCancellable, or %NULL
30047 * @callback: (scope async): a #GAsyncReadyCallback to call when the
30048 * request is satisfied
30049 * @user_data: (closure): the data to pass to callback function
30051 * Asynchronously attempts to determine whether or not the host
30052 * pointed to by @connectable can be reached, without actually
30053 * trying to connect to it.
30055 * For more details, see g_network_monitor_can_reach().
30057 * When the operation is finished, @callback will be called.
30058 * You can then call g_network_monitor_can_reach_finish()
30059 * to get the result of the operation.
30064 * g_network_monitor_can_reach_finish:
30065 * @monitor: a #GNetworkMonitor
30066 * @result: a #GAsyncResult
30067 * @error: return location for errors, or %NULL
30069 * Finishes an async network connectivity test.
30070 * See g_network_monitor_can_reach_async().
30072 * Returns: %TRUE if network is reachable, %FALSE if not.
30077 * g_network_monitor_get_connectivity:
30078 * @monitor: the #GNetworkMonitor
30080 * Gets a more detailed networking state than
30081 * g_network_monitor_get_network_available().
30083 * If #GNetworkMonitor:network-available is %FALSE, then the
30084 * connectivity state will be %G_NETWORK_CONNECTIVITY_LOCAL.
30086 * If #GNetworkMonitor:network-available is %TRUE, then the
30087 * connectivity state will be %G_NETWORK_CONNECTIVITY_FULL (if there
30088 * is full Internet connectivity), %G_NETWORK_CONNECTIVITY_LIMITED (if
30089 * the host has a default route, but appears to be unable to actually
30090 * reach the full Internet), or %G_NETWORK_CONNECTIVITY_PORTAL (if the
30091 * host is trapped behind a "captive portal" that requires some sort
30092 * of login or acknowledgement before allowing full Internet access).
30094 * Note that in the case of %G_NETWORK_CONNECTIVITY_LIMITED and
30095 * %G_NETWORK_CONNECTIVITY_PORTAL, it is possible that some sites are
30096 * reachable but others are not. In this case, applications can
30097 * attempt to connect to remote servers, but should gracefully fall
30098 * back to their "offline" behavior if the connection attempt fails.
30100 * Returns: the network connectivity state
30106 * g_network_monitor_get_default:
30108 * Gets the default #GNetworkMonitor for the system.
30110 * Returns: (transfer none): a #GNetworkMonitor
30116 * g_network_monitor_get_network_available:
30117 * @monitor: the #GNetworkMonitor
30119 * Checks if the network is available. "Available" here means that the
30120 * system has a default route available for at least one of IPv4 or
30121 * IPv6. It does not necessarily imply that the public Internet is
30122 * reachable. See #GNetworkMonitor:network-available for more details.
30124 * Returns: whether the network is available
30130 * g_network_monitor_get_network_metered:
30131 * @monitor: the #GNetworkMonitor
30133 * Checks if the network is metered.
30134 * See #GNetworkMonitor:network-metered for more details.
30136 * Returns: whether the connection is metered
30142 * g_network_service_get_domain:
30143 * @srv: a #GNetworkService
30145 * Gets the domain that @srv serves. This might be either UTF-8 or
30146 * ASCII-encoded, depending on what @srv was created with.
30148 * Returns: @srv's domain name
30154 * g_network_service_get_protocol:
30155 * @srv: a #GNetworkService
30157 * Gets @srv's protocol name (eg, "tcp").
30159 * Returns: @srv's protocol name
30165 * g_network_service_get_scheme:
30166 * @srv: a #GNetworkService
30168 * Get's the URI scheme used to resolve proxies. By default, the service name
30169 * is used as scheme.
30171 * Returns: @srv's scheme name
30177 * g_network_service_get_service:
30178 * @srv: a #GNetworkService
30180 * Gets @srv's service name (eg, "ldap").
30182 * Returns: @srv's service name
30188 * g_network_service_new:
30189 * @service: the service type to look up (eg, "ldap")
30190 * @protocol: the networking protocol to use for @service (eg, "tcp")
30191 * @domain: the DNS domain to look up the service in
30193 * Creates a new #GNetworkService representing the given @service,
30194 * @protocol, and @domain. This will initially be unresolved; use the
30195 * #GSocketConnectable interface to resolve it.
30197 * Returns: (transfer full) (type GNetworkService): a new #GNetworkService
30203 * g_network_service_set_scheme:
30204 * @srv: a #GNetworkService
30205 * @scheme: a URI scheme
30207 * Set's the URI scheme used to resolve proxies. By default, the service name
30208 * is used as scheme.
30215 * g_networking_init:
30217 * Initializes the platform networking libraries (eg, on Windows, this
30218 * calls WSAStartup()). GLib will call this itself if it is needed, so
30219 * you only need to call it if you directly call system networking
30220 * functions (without calling any GLib networking functions first).
30227 * g_notification_add_button:
30228 * @notification: a #GNotification
30229 * @label: label of the button
30230 * @detailed_action: a detailed action name
30232 * Adds a button to @notification that activates the action in
30233 * @detailed_action when clicked. That action must be an
30234 * application-wide action (starting with "app."). If @detailed_action
30235 * contains a target, the action will be activated with that target as
30238 * See g_action_parse_detailed_name() for a description of the format
30239 * for @detailed_action.
30246 * g_notification_add_button_with_target: (skip)
30247 * @notification: a #GNotification
30248 * @label: label of the button
30249 * @action: an action name
30250 * @target_format: (allow-none): a #GVariant format string, or %NULL
30251 * @...: positional parameters, as determined by @target_format
30253 * Adds a button to @notification that activates @action when clicked.
30254 * @action must be an application-wide action (it must start with "app.").
30256 * If @target_format is given, it is used to collect remaining
30257 * positional parameters into a #GVariant instance, similar to
30258 * g_variant_new(). @action will be activated with that #GVariant as its
30266 * g_notification_add_button_with_target_value: (rename-to g_notification_add_button_with_target)
30267 * @notification: a #GNotification
30268 * @label: label of the button
30269 * @action: an action name
30270 * @target: (allow-none): a #GVariant to use as @action's parameter, or %NULL
30272 * Adds a button to @notification that activates @action when clicked.
30273 * @action must be an application-wide action (it must start with "app.").
30275 * If @target is non-%NULL, @action will be activated with @target as
30283 * g_notification_new:
30284 * @title: the title of the notification
30286 * Creates a new #GNotification with @title as its title.
30288 * After populating @notification with more details, it can be sent to
30289 * the desktop shell with g_application_send_notification(). Changing
30290 * any properties after this call will not have any effect until
30291 * resending @notification.
30293 * Returns: a new #GNotification instance
30299 * g_notification_set_body:
30300 * @notification: a #GNotification
30301 * @body: (allow-none): the new body for @notification, or %NULL
30303 * Sets the body of @notification to @body.
30310 * g_notification_set_default_action:
30311 * @notification: a #GNotification
30312 * @detailed_action: a detailed action name
30314 * Sets the default action of @notification to @detailed_action. This
30315 * action is activated when the notification is clicked on.
30317 * The action in @detailed_action must be an application-wide action (it
30318 * must start with "app."). If @detailed_action contains a target, the
30319 * given action will be activated with that target as its parameter.
30320 * See g_action_parse_detailed_name() for a description of the format
30321 * for @detailed_action.
30323 * When no default action is set, the application that the notification
30324 * was sent on is activated.
30331 * g_notification_set_default_action_and_target: (skip)
30332 * @notification: a #GNotification
30333 * @action: an action name
30334 * @target_format: (allow-none): a #GVariant format string, or %NULL
30335 * @...: positional parameters, as determined by @target_format
30337 * Sets the default action of @notification to @action. This action is
30338 * activated when the notification is clicked on. It must be an
30339 * application-wide action (it must start with "app.").
30341 * If @target_format is given, it is used to collect remaining
30342 * positional parameters into a #GVariant instance, similar to
30343 * g_variant_new(). @action will be activated with that #GVariant as its
30346 * When no default action is set, the application that the notification
30347 * was sent on is activated.
30354 * g_notification_set_default_action_and_target_value: (rename-to g_notification_set_default_action_and_target)
30355 * @notification: a #GNotification
30356 * @action: an action name
30357 * @target: (allow-none): a #GVariant to use as @action's parameter, or %NULL
30359 * Sets the default action of @notification to @action. This action is
30360 * activated when the notification is clicked on. It must be an
30361 * application-wide action (start with "app.").
30363 * If @target is non-%NULL, @action will be activated with @target as
30366 * When no default action is set, the application that the notification
30367 * was sent on is activated.
30374 * g_notification_set_icon:
30375 * @notification: a #GNotification
30376 * @icon: the icon to be shown in @notification, as a #GIcon
30378 * Sets the icon of @notification to @icon.
30385 * g_notification_set_priority:
30386 * @notification: a #GNotification
30387 * @priority: a #GNotificationPriority
30389 * Sets the priority of @notification to @priority. See
30390 * #GNotificationPriority for possible values.
30395 * g_notification_set_title:
30396 * @notification: a #GNotification
30397 * @title: the new title for @notification
30399 * Sets the title of @notification to @title.
30406 * g_notification_set_urgent:
30407 * @notification: a #GNotification
30408 * @urgent: %TRUE if @notification is urgent
30410 * Deprecated in favor of g_notification_set_priority().
30417 * g_null_settings_backend_new:
30419 * Creates a readonly #GSettingsBackend.
30421 * This backend does not allow changes to settings, so all settings
30422 * will always have their default values.
30424 * Returns: (transfer full): a newly created #GSettingsBackend
30430 * g_output_stream_clear_pending:
30431 * @stream: output stream
30433 * Clears the pending flag on @stream.
30438 * g_output_stream_close:
30439 * @stream: A #GOutputStream.
30440 * @cancellable: (allow-none): optional cancellable object
30441 * @error: location to store the error occurring, or %NULL to ignore
30443 * Closes the stream, releasing resources related to it.
30445 * Once the stream is closed, all other operations will return %G_IO_ERROR_CLOSED.
30446 * Closing a stream multiple times will not return an error.
30448 * Closing a stream will automatically flush any outstanding buffers in the
30451 * Streams will be automatically closed when the last reference
30452 * is dropped, but you might want to call this function to make sure
30453 * resources are released as early as possible.
30455 * Some streams might keep the backing store of the stream (e.g. a file descriptor)
30456 * open after the stream is closed. See the documentation for the individual
30457 * stream for details.
30459 * On failure the first error that happened will be reported, but the close
30460 * operation will finish as much as possible. A stream that failed to
30461 * close will still return %G_IO_ERROR_CLOSED for all operations. Still, it
30462 * is important to check and report the error to the user, otherwise
30463 * there might be a loss of data as all data might not be written.
30465 * If @cancellable is not %NULL, then the operation can be cancelled by
30466 * triggering the cancellable object from another thread. If the operation
30467 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
30468 * Cancelling a close will still leave the stream closed, but there some streams
30469 * can use a faster close that doesn't block to e.g. check errors. On
30470 * cancellation (as with any error) there is no guarantee that all written
30471 * data will reach the target.
30473 * Returns: %TRUE on success, %FALSE on failure
30478 * g_output_stream_close_async:
30479 * @stream: A #GOutputStream.
30480 * @io_priority: the io priority of the request.
30481 * @cancellable: (allow-none): optional cancellable object
30482 * @callback: (scope async): callback to call when the request is satisfied
30483 * @user_data: (closure): the data to pass to callback function
30485 * Requests an asynchronous close of the stream, releasing resources
30486 * related to it. When the operation is finished @callback will be
30487 * called. You can then call g_output_stream_close_finish() to get
30488 * the result of the operation.
30490 * For behaviour details see g_output_stream_close().
30492 * The asyncronous methods have a default fallback that uses threads
30493 * to implement asynchronicity, so they are optional for inheriting
30494 * classes. However, if you override one you must override all.
30499 * g_output_stream_close_finish:
30500 * @stream: a #GOutputStream.
30501 * @result: a #GAsyncResult.
30502 * @error: a #GError location to store the error occurring, or %NULL to
30505 * Closes an output stream.
30507 * Returns: %TRUE if stream was successfully closed, %FALSE otherwise.
30512 * g_output_stream_flush:
30513 * @stream: a #GOutputStream.
30514 * @cancellable: (allow-none): optional cancellable object
30515 * @error: location to store the error occurring, or %NULL to ignore
30517 * Forces a write of all user-space buffered data for the given
30518 * @stream. Will block during the operation. Closing the stream will
30519 * implicitly cause a flush.
30521 * This function is optional for inherited classes.
30523 * If @cancellable is not %NULL, then the operation can be cancelled by
30524 * triggering the cancellable object from another thread. If the operation
30525 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
30527 * Returns: %TRUE on success, %FALSE on error
30532 * g_output_stream_flush_async:
30533 * @stream: a #GOutputStream.
30534 * @io_priority: the io priority of the request.
30535 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
30536 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
30537 * @user_data: (closure): the data to pass to callback function
30539 * Forces an asynchronous write of all user-space buffered data for
30540 * the given @stream.
30541 * For behaviour details see g_output_stream_flush().
30543 * When the operation is finished @callback will be
30544 * called. You can then call g_output_stream_flush_finish() to get the
30545 * result of the operation.
30550 * g_output_stream_flush_finish:
30551 * @stream: a #GOutputStream.
30552 * @result: a GAsyncResult.
30553 * @error: a #GError location to store the error occurring, or %NULL to
30556 * Finishes flushing an output stream.
30558 * Returns: %TRUE if flush operation succeeded, %FALSE otherwise.
30563 * g_output_stream_has_pending:
30564 * @stream: a #GOutputStream.
30566 * Checks if an ouput stream has pending actions.
30568 * Returns: %TRUE if @stream has pending actions.
30573 * g_output_stream_is_closed:
30574 * @stream: a #GOutputStream.
30576 * Checks if an output stream has already been closed.
30578 * Returns: %TRUE if @stream is closed. %FALSE otherwise.
30583 * g_output_stream_is_closing:
30584 * @stream: a #GOutputStream.
30586 * Checks if an output stream is being closed. This can be
30587 * used inside e.g. a flush implementation to see if the
30588 * flush (or other i/o operation) is called from within
30589 * the closing operation.
30591 * Returns: %TRUE if @stream is being closed. %FALSE otherwise.
30597 * g_output_stream_printf:
30598 * @stream: a #GOutputStream.
30599 * @bytes_written: (out): location to store the number of bytes that was
30600 * written to the stream
30601 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
30602 * @error: location to store the error occurring, or %NULL to ignore
30603 * @format: the format string. See the printf() documentation
30604 * @...: the parameters to insert into the format string
30606 * This is a utility function around g_output_stream_write_all(). It
30607 * uses g_strdup_vprintf() to turn @format and @... into a string that
30608 * is then written to @stream.
30610 * See the documentation of g_output_stream_write_all() about the
30611 * behavior of the actual write operation.
30613 * Note that partial writes cannot be properly checked with this
30614 * function due to the variable length of the written string, if you
30615 * need precise control over partial write failures, you need to
30616 * create you own printf()-like wrapper around g_output_stream_write()
30617 * or g_output_stream_write_all().
30620 * Returns: %TRUE on success, %FALSE if there was an error
30625 * g_output_stream_set_pending:
30626 * @stream: a #GOutputStream.
30627 * @error: a #GError location to store the error occurring, or %NULL to
30630 * Sets @stream to have actions pending. If the pending flag is
30631 * already set or @stream is closed, it will return %FALSE and set
30634 * Returns: %TRUE if pending was previously unset and is now set.
30639 * g_output_stream_splice:
30640 * @stream: a #GOutputStream.
30641 * @source: a #GInputStream.
30642 * @flags: a set of #GOutputStreamSpliceFlags.
30643 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
30644 * @error: a #GError location to store the error occurring, or %NULL to
30647 * Splices an input stream into an output stream.
30649 * Returns: a #gssize containing the size of the data spliced, or
30650 * -1 if an error occurred. Note that if the number of bytes
30651 * spliced is greater than %G_MAXSSIZE, then that will be
30652 * returned, and there is no way to determine the actual number
30653 * of bytes spliced.
30658 * g_output_stream_splice_async:
30659 * @stream: a #GOutputStream.
30660 * @source: a #GInputStream.
30661 * @flags: a set of #GOutputStreamSpliceFlags.
30662 * @io_priority: the io priority of the request.
30663 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
30664 * @callback: (scope async): a #GAsyncReadyCallback.
30665 * @user_data: (closure): user data passed to @callback.
30667 * Splices a stream asynchronously.
30668 * When the operation is finished @callback will be called.
30669 * You can then call g_output_stream_splice_finish() to get the
30670 * result of the operation.
30672 * For the synchronous, blocking version of this function, see
30673 * g_output_stream_splice().
30678 * g_output_stream_splice_finish:
30679 * @stream: a #GOutputStream.
30680 * @result: a #GAsyncResult.
30681 * @error: a #GError location to store the error occurring, or %NULL to
30684 * Finishes an asynchronous stream splice operation.
30686 * Returns: a #gssize of the number of bytes spliced. Note that if the
30687 * number of bytes spliced is greater than %G_MAXSSIZE, then that
30688 * will be returned, and there is no way to determine the actual
30689 * number of bytes spliced.
30694 * g_output_stream_vprintf:
30695 * @stream: a #GOutputStream.
30696 * @bytes_written: (out): location to store the number of bytes that was
30697 * written to the stream
30698 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
30699 * @error: location to store the error occurring, or %NULL to ignore
30700 * @format: the format string. See the printf() documentation
30701 * @args: the parameters to insert into the format string
30703 * This is a utility function around g_output_stream_write_all(). It
30704 * uses g_strdup_vprintf() to turn @format and @args into a string that
30705 * is then written to @stream.
30707 * See the documentation of g_output_stream_write_all() about the
30708 * behavior of the actual write operation.
30710 * Note that partial writes cannot be properly checked with this
30711 * function due to the variable length of the written string, if you
30712 * need precise control over partial write failures, you need to
30713 * create you own printf()-like wrapper around g_output_stream_write()
30714 * or g_output_stream_write_all().
30717 * Returns: %TRUE on success, %FALSE if there was an error
30722 * g_output_stream_write: (virtual write_fn)
30723 * @stream: a #GOutputStream.
30724 * @buffer: (array length=count) (element-type guint8): the buffer containing the data to write.
30725 * @count: the number of bytes to write
30726 * @cancellable: (allow-none): optional cancellable object
30727 * @error: location to store the error occurring, or %NULL to ignore
30729 * Tries to write @count bytes from @buffer into the stream. Will block
30730 * during the operation.
30732 * If count is 0, returns 0 and does nothing. A value of @count
30733 * larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
30735 * On success, the number of bytes written to the stream is returned.
30736 * It is not an error if this is not the same as the requested size, as it
30737 * can happen e.g. on a partial I/O error, or if there is not enough
30738 * storage in the stream. All writes block until at least one byte
30739 * is written or an error occurs; 0 is never returned (unless
30742 * If @cancellable is not %NULL, then the operation can be cancelled by
30743 * triggering the cancellable object from another thread. If the operation
30744 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
30745 * operation was partially finished when the operation was cancelled the
30746 * partial result will be returned, without an error.
30748 * On error -1 is returned and @error is set accordingly.
30750 * Returns: Number of bytes written, or -1 on error
30755 * g_output_stream_write_all:
30756 * @stream: a #GOutputStream.
30757 * @buffer: (array length=count) (element-type guint8): the buffer containing the data to write.
30758 * @count: the number of bytes to write
30759 * @bytes_written: (out): location to store the number of bytes that was
30760 * written to the stream
30761 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
30762 * @error: location to store the error occurring, or %NULL to ignore
30764 * Tries to write @count bytes from @buffer into the stream. Will block
30765 * during the operation.
30767 * This function is similar to g_output_stream_write(), except it tries to
30768 * write as many bytes as requested, only stopping on an error.
30770 * On a successful write of @count bytes, %TRUE is returned, and @bytes_written
30771 * is set to @count.
30773 * If there is an error during the operation %FALSE is returned and @error
30774 * is set to indicate the error status.
30776 * As a special exception to the normal conventions for functions that
30777 * use #GError, if this function returns %FALSE (and sets @error) then
30778 * @bytes_written will be set to the number of bytes that were
30779 * successfully written before the error was encountered. This
30780 * functionality is only available from C. If you need it from another
30781 * language then you must write your own loop around
30782 * g_output_stream_write().
30784 * Returns: %TRUE on success, %FALSE if there was an error
30789 * g_output_stream_write_all_async:
30790 * @stream: A #GOutputStream
30791 * @buffer: (array length=count) (element-type guint8): the buffer containing the data to write
30792 * @count: the number of bytes to write
30793 * @io_priority: the io priority of the request
30794 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
30795 * @callback: (scope async): callback to call when the request is satisfied
30796 * @user_data: (closure): the data to pass to callback function
30798 * Request an asynchronous write of @count bytes from @buffer into
30799 * the stream. When the operation is finished @callback will be called.
30800 * You can then call g_output_stream_write_all_finish() to get the result of the
30803 * This is the asynchronous version of g_output_stream_write_all().
30805 * Call g_output_stream_write_all_finish() to collect the result.
30807 * Any outstanding I/O request with higher priority (lower numerical
30808 * value) will be executed before an outstanding request with lower
30809 * priority. Default priority is %G_PRIORITY_DEFAULT.
30811 * Note that no copy of @buffer will be made, so it must stay valid
30812 * until @callback is called.
30819 * g_output_stream_write_all_finish:
30820 * @stream: a #GOutputStream
30821 * @result: a #GAsyncResult
30822 * @bytes_written: (out): location to store the number of bytes that was written to the stream
30823 * @error: a #GError location to store the error occurring, or %NULL to ignore.
30825 * Finishes an asynchronous stream write operation started with
30826 * g_output_stream_write_all_async().
30828 * As a special exception to the normal conventions for functions that
30829 * use #GError, if this function returns %FALSE (and sets @error) then
30830 * @bytes_written will be set to the number of bytes that were
30831 * successfully written before the error was encountered. This
30832 * functionality is only available from C. If you need it from another
30833 * language then you must write your own loop around
30834 * g_output_stream_write_async().
30836 * Returns: %TRUE on success, %FALSE if there was an error
30842 * g_output_stream_write_async:
30843 * @stream: A #GOutputStream.
30844 * @buffer: (array length=count) (element-type guint8): the buffer containing the data to write.
30845 * @count: the number of bytes to write
30846 * @io_priority: the io priority of the request.
30847 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
30848 * @callback: (scope async): callback to call when the request is satisfied
30849 * @user_data: (closure): the data to pass to callback function
30851 * Request an asynchronous write of @count bytes from @buffer into
30852 * the stream. When the operation is finished @callback will be called.
30853 * You can then call g_output_stream_write_finish() to get the result of the
30856 * During an async request no other sync and async calls are allowed,
30857 * and will result in %G_IO_ERROR_PENDING errors.
30859 * A value of @count larger than %G_MAXSSIZE will cause a
30860 * %G_IO_ERROR_INVALID_ARGUMENT error.
30862 * On success, the number of bytes written will be passed to the
30863 * @callback. It is not an error if this is not the same as the
30864 * requested size, as it can happen e.g. on a partial I/O error,
30865 * but generally we try to write as many bytes as requested.
30867 * You are guaranteed that this method will never fail with
30868 * %G_IO_ERROR_WOULD_BLOCK - if @stream can't accept more data, the
30869 * method will just wait until this changes.
30871 * Any outstanding I/O request with higher priority (lower numerical
30872 * value) will be executed before an outstanding request with lower
30873 * priority. Default priority is %G_PRIORITY_DEFAULT.
30875 * The asyncronous methods have a default fallback that uses threads
30876 * to implement asynchronicity, so they are optional for inheriting
30877 * classes. However, if you override one you must override all.
30879 * For the synchronous, blocking version of this function, see
30880 * g_output_stream_write().
30882 * Note that no copy of @buffer will be made, so it must stay valid
30883 * until @callback is called. See g_output_stream_write_bytes_async()
30884 * for a #GBytes version that will automatically hold a reference to
30885 * the contents (without copying) for the duration of the call.
30890 * g_output_stream_write_bytes:
30891 * @stream: a #GOutputStream.
30892 * @bytes: the #GBytes to write
30893 * @cancellable: (allow-none): optional cancellable object
30894 * @error: location to store the error occurring, or %NULL to ignore
30896 * A wrapper function for g_output_stream_write() which takes a
30897 * #GBytes as input. This can be more convenient for use by language
30898 * bindings or in other cases where the refcounted nature of #GBytes
30899 * is helpful over a bare pointer interface.
30901 * However, note that this function may still perform partial writes,
30902 * just like g_output_stream_write(). If that occurs, to continue
30903 * writing, you will need to create a new #GBytes containing just the
30904 * remaining bytes, using g_bytes_new_from_bytes(). Passing the same
30905 * #GBytes instance multiple times potentially can result in duplicated
30906 * data in the output stream.
30908 * Returns: Number of bytes written, or -1 on error
30913 * g_output_stream_write_bytes_async:
30914 * @stream: A #GOutputStream.
30915 * @bytes: The bytes to write
30916 * @io_priority: the io priority of the request.
30917 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
30918 * @callback: (scope async): callback to call when the request is satisfied
30919 * @user_data: (closure): the data to pass to callback function
30921 * This function is similar to g_output_stream_write_async(), but
30922 * takes a #GBytes as input. Due to the refcounted nature of #GBytes,
30923 * this allows the stream to avoid taking a copy of the data.
30925 * However, note that this function may still perform partial writes,
30926 * just like g_output_stream_write_async(). If that occurs, to continue
30927 * writing, you will need to create a new #GBytes containing just the
30928 * remaining bytes, using g_bytes_new_from_bytes(). Passing the same
30929 * #GBytes instance multiple times potentially can result in duplicated
30930 * data in the output stream.
30932 * For the synchronous, blocking version of this function, see
30933 * g_output_stream_write_bytes().
30938 * g_output_stream_write_bytes_finish:
30939 * @stream: a #GOutputStream.
30940 * @result: a #GAsyncResult.
30941 * @error: a #GError location to store the error occurring, or %NULL to
30944 * Finishes a stream write-from-#GBytes operation.
30946 * Returns: a #gssize containing the number of bytes written to the stream.
30951 * g_output_stream_write_finish:
30952 * @stream: a #GOutputStream.
30953 * @result: a #GAsyncResult.
30954 * @error: a #GError location to store the error occurring, or %NULL to
30957 * Finishes a stream write operation.
30959 * Returns: a #gssize containing the number of bytes written to the stream.
30964 * g_permission_acquire:
30965 * @permission: a #GPermission instance
30966 * @cancellable: (allow-none): a #GCancellable, or %NULL
30967 * @error: a pointer to a %NULL #GError, or %NULL
30969 * Attempts to acquire the permission represented by @permission.
30971 * The precise method by which this happens depends on the permission
30972 * and the underlying authentication mechanism. A simple example is
30973 * that a dialog may appear asking the user to enter their password.
30975 * You should check with g_permission_get_can_acquire() before calling
30978 * If the permission is acquired then %TRUE is returned. Otherwise,
30979 * %FALSE is returned and @error is set appropriately.
30981 * This call is blocking, likely for a very long time (in the case that
30982 * user interaction is required). See g_permission_acquire_async() for
30983 * the non-blocking version.
30985 * Returns: %TRUE if the permission was successfully acquired
30991 * g_permission_acquire_async:
30992 * @permission: a #GPermission instance
30993 * @cancellable: (allow-none): a #GCancellable, or %NULL
30994 * @callback: the #GAsyncReadyCallback to call when done
30995 * @user_data: the user data to pass to @callback
30997 * Attempts to acquire the permission represented by @permission.
30999 * This is the first half of the asynchronous version of
31000 * g_permission_acquire().
31007 * g_permission_acquire_finish:
31008 * @permission: a #GPermission instance
31009 * @result: the #GAsyncResult given to the #GAsyncReadyCallback
31010 * @error: a pointer to a %NULL #GError, or %NULL
31012 * Collects the result of attempting to acquire the permission
31013 * represented by @permission.
31015 * This is the second half of the asynchronous version of
31016 * g_permission_acquire().
31018 * Returns: %TRUE if the permission was successfully acquired
31024 * g_permission_get_allowed:
31025 * @permission: a #GPermission instance
31027 * Gets the value of the 'allowed' property. This property is %TRUE if
31028 * the caller currently has permission to perform the action that
31029 * @permission represents the permission to perform.
31031 * Returns: the value of the 'allowed' property
31037 * g_permission_get_can_acquire:
31038 * @permission: a #GPermission instance
31040 * Gets the value of the 'can-acquire' property. This property is %TRUE
31041 * if it is generally possible to acquire the permission by calling
31042 * g_permission_acquire().
31044 * Returns: the value of the 'can-acquire' property
31050 * g_permission_get_can_release:
31051 * @permission: a #GPermission instance
31053 * Gets the value of the 'can-release' property. This property is %TRUE
31054 * if it is generally possible to release the permission by calling
31055 * g_permission_release().
31057 * Returns: the value of the 'can-release' property
31063 * g_permission_impl_update:
31064 * @permission: a #GPermission instance
31065 * @allowed: the new value for the 'allowed' property
31066 * @can_acquire: the new value for the 'can-acquire' property
31067 * @can_release: the new value for the 'can-release' property
31069 * This function is called by the #GPermission implementation to update
31070 * the properties of the permission. You should never call this
31071 * function except from a #GPermission implementation.
31073 * GObject notify signals are generated, as appropriate.
31080 * g_permission_release:
31081 * @permission: a #GPermission instance
31082 * @cancellable: (allow-none): a #GCancellable, or %NULL
31083 * @error: a pointer to a %NULL #GError, or %NULL
31085 * Attempts to release the permission represented by @permission.
31087 * The precise method by which this happens depends on the permission
31088 * and the underlying authentication mechanism. In most cases the
31089 * permission will be dropped immediately without further action.
31091 * You should check with g_permission_get_can_release() before calling
31094 * If the permission is released then %TRUE is returned. Otherwise,
31095 * %FALSE is returned and @error is set appropriately.
31097 * This call is blocking, likely for a very long time (in the case that
31098 * user interaction is required). See g_permission_release_async() for
31099 * the non-blocking version.
31101 * Returns: %TRUE if the permission was successfully released
31107 * g_permission_release_async:
31108 * @permission: a #GPermission instance
31109 * @cancellable: (allow-none): a #GCancellable, or %NULL
31110 * @callback: the #GAsyncReadyCallback to call when done
31111 * @user_data: the user data to pass to @callback
31113 * Attempts to release the permission represented by @permission.
31115 * This is the first half of the asynchronous version of
31116 * g_permission_release().
31123 * g_permission_release_finish:
31124 * @permission: a #GPermission instance
31125 * @result: the #GAsyncResult given to the #GAsyncReadyCallback
31126 * @error: a pointer to a %NULL #GError, or %NULL
31128 * Collects the result of attempting to release the permission
31129 * represented by @permission.
31131 * This is the second half of the asynchronous version of
31132 * g_permission_release().
31134 * Returns: %TRUE if the permission was successfully released
31140 * g_pollable_input_stream_can_poll:
31141 * @stream: a #GPollableInputStream.
31143 * Checks if @stream is actually pollable. Some classes may implement
31144 * #GPollableInputStream but have only certain instances of that class
31145 * be pollable. If this method returns %FALSE, then the behavior of
31146 * other #GPollableInputStream methods is undefined.
31148 * For any given stream, the value returned by this method is constant;
31149 * a stream cannot switch from pollable to non-pollable or vice versa.
31151 * Returns: %TRUE if @stream is pollable, %FALSE if not.
31157 * g_pollable_input_stream_create_source:
31158 * @stream: a #GPollableInputStream.
31159 * @cancellable: (allow-none): a #GCancellable, or %NULL
31161 * Creates a #GSource that triggers when @stream can be read, or
31162 * @cancellable is triggered or an error occurs. The callback on the
31163 * source is of the #GPollableSourceFunc type.
31165 * As with g_pollable_input_stream_is_readable(), it is possible that
31166 * the stream may not actually be readable even after the source
31167 * triggers, so you should use g_pollable_input_stream_read_nonblocking()
31168 * rather than g_input_stream_read() from the callback.
31170 * Returns: (transfer full): a new #GSource
31176 * g_pollable_input_stream_is_readable:
31177 * @stream: a #GPollableInputStream.
31179 * Checks if @stream can be read.
31181 * Note that some stream types may not be able to implement this 100%
31182 * reliably, and it is possible that a call to g_input_stream_read()
31183 * after this returns %TRUE would still block. To guarantee
31184 * non-blocking behavior, you should always use
31185 * g_pollable_input_stream_read_nonblocking(), which will return a
31186 * %G_IO_ERROR_WOULD_BLOCK error rather than blocking.
31188 * Returns: %TRUE if @stream is readable, %FALSE if not. If an error
31189 * has occurred on @stream, this will result in
31190 * g_pollable_input_stream_is_readable() returning %TRUE, and the
31191 * next attempt to read will return the error.
31197 * g_pollable_input_stream_read_nonblocking: (virtual read_nonblocking)
31198 * @stream: a #GPollableInputStream
31199 * @buffer: (array length=count) (element-type guint8): a buffer to
31200 * read data into (which should be at least @count bytes long).
31201 * @count: the number of bytes you want to read
31202 * @cancellable: (allow-none): a #GCancellable, or %NULL
31203 * @error: #GError for error reporting, or %NULL to ignore.
31205 * Attempts to read up to @count bytes from @stream into @buffer, as
31206 * with g_input_stream_read(). If @stream is not currently readable,
31207 * this will immediately return %G_IO_ERROR_WOULD_BLOCK, and you can
31208 * use g_pollable_input_stream_create_source() to create a #GSource
31209 * that will be triggered when @stream is readable.
31211 * Note that since this method never blocks, you cannot actually
31212 * use @cancellable to cancel it. However, it will return an error
31213 * if @cancellable has already been cancelled when you call, which
31214 * may happen if you call this method after a source triggers due
31215 * to having been cancelled.
31217 * Returns: the number of bytes read, or -1 on error (including
31218 * %G_IO_ERROR_WOULD_BLOCK).
31223 * g_pollable_output_stream_can_poll:
31224 * @stream: a #GPollableOutputStream.
31226 * Checks if @stream is actually pollable. Some classes may implement
31227 * #GPollableOutputStream but have only certain instances of that
31228 * class be pollable. If this method returns %FALSE, then the behavior
31229 * of other #GPollableOutputStream methods is undefined.
31231 * For any given stream, the value returned by this method is constant;
31232 * a stream cannot switch from pollable to non-pollable or vice versa.
31234 * Returns: %TRUE if @stream is pollable, %FALSE if not.
31240 * g_pollable_output_stream_create_source:
31241 * @stream: a #GPollableOutputStream.
31242 * @cancellable: (allow-none): a #GCancellable, or %NULL
31244 * Creates a #GSource that triggers when @stream can be written, or
31245 * @cancellable is triggered or an error occurs. The callback on the
31246 * source is of the #GPollableSourceFunc type.
31248 * As with g_pollable_output_stream_is_writable(), it is possible that
31249 * the stream may not actually be writable even after the source
31250 * triggers, so you should use g_pollable_output_stream_write_nonblocking()
31251 * rather than g_output_stream_write() from the callback.
31253 * Returns: (transfer full): a new #GSource
31259 * g_pollable_output_stream_is_writable:
31260 * @stream: a #GPollableOutputStream.
31262 * Checks if @stream can be written.
31264 * Note that some stream types may not be able to implement this 100%
31265 * reliably, and it is possible that a call to g_output_stream_write()
31266 * after this returns %TRUE would still block. To guarantee
31267 * non-blocking behavior, you should always use
31268 * g_pollable_output_stream_write_nonblocking(), which will return a
31269 * %G_IO_ERROR_WOULD_BLOCK error rather than blocking.
31271 * Returns: %TRUE if @stream is writable, %FALSE if not. If an error
31272 * has occurred on @stream, this will result in
31273 * g_pollable_output_stream_is_writable() returning %TRUE, and the
31274 * next attempt to write will return the error.
31280 * g_pollable_output_stream_write_nonblocking: (virtual write_nonblocking)
31281 * @stream: a #GPollableOutputStream
31282 * @buffer: (array length=count) (element-type guint8): a buffer to write
31284 * @count: the number of bytes you want to write
31285 * @cancellable: (allow-none): a #GCancellable, or %NULL
31286 * @error: #GError for error reporting, or %NULL to ignore.
31288 * Attempts to write up to @count bytes from @buffer to @stream, as
31289 * with g_output_stream_write(). If @stream is not currently writable,
31290 * this will immediately return %G_IO_ERROR_WOULD_BLOCK, and you can
31291 * use g_pollable_output_stream_create_source() to create a #GSource
31292 * that will be triggered when @stream is writable.
31294 * Note that since this method never blocks, you cannot actually
31295 * use @cancellable to cancel it. However, it will return an error
31296 * if @cancellable has already been cancelled when you call, which
31297 * may happen if you call this method after a source triggers due
31298 * to having been cancelled.
31300 * Returns: the number of bytes written, or -1 on error (including
31301 * %G_IO_ERROR_WOULD_BLOCK).
31306 * g_pollable_source_new:
31307 * @pollable_stream: the stream associated with the new source
31309 * Utility method for #GPollableInputStream and #GPollableOutputStream
31310 * implementations. Creates a new #GSource that expects a callback of
31311 * type #GPollableSourceFunc. The new source does not actually do
31312 * anything on its own; use g_source_add_child_source() to add other
31313 * sources to it to cause it to trigger.
31315 * Returns: (transfer full): the new #GSource.
31321 * g_pollable_source_new_full:
31322 * @pollable_stream: (type GObject): the stream associated with the
31324 * @child_source: (allow-none): optional child source to attach
31325 * @cancellable: (allow-none): optional #GCancellable to attach
31327 * Utility method for #GPollableInputStream and #GPollableOutputStream
31328 * implementations. Creates a new #GSource, as with
31329 * g_pollable_source_new(), but also attaching @child_source (with a
31330 * dummy callback), and @cancellable, if they are non-%NULL.
31332 * Returns: (transfer full): the new #GSource.
31338 * g_pollable_stream_read:
31339 * @stream: a #GInputStream
31340 * @buffer: (array length=count) (element-type guint8): a buffer to
31342 * @count: the number of bytes to read
31343 * @blocking: whether to do blocking I/O
31344 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
31345 * @error: location to store the error occurring, or %NULL to ignore
31347 * Tries to read from @stream, as with g_input_stream_read() (if
31348 * @blocking is %TRUE) or g_pollable_input_stream_read_nonblocking()
31349 * (if @blocking is %FALSE). This can be used to more easily share
31350 * code between blocking and non-blocking implementations of a method.
31352 * If @blocking is %FALSE, then @stream must be a
31353 * #GPollableInputStream for which g_pollable_input_stream_can_poll()
31354 * returns %TRUE, or else the behavior is undefined. If @blocking is
31355 * %TRUE, then @stream does not need to be a #GPollableInputStream.
31357 * Returns: the number of bytes read, or -1 on error.
31363 * g_pollable_stream_write:
31364 * @stream: a #GOutputStream.
31365 * @buffer: (array length=count) (element-type guint8): the buffer
31366 * containing the data to write.
31367 * @count: the number of bytes to write
31368 * @blocking: whether to do blocking I/O
31369 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
31370 * @error: location to store the error occurring, or %NULL to ignore
31372 * Tries to write to @stream, as with g_output_stream_write() (if
31373 * @blocking is %TRUE) or g_pollable_output_stream_write_nonblocking()
31374 * (if @blocking is %FALSE). This can be used to more easily share
31375 * code between blocking and non-blocking implementations of a method.
31377 * If @blocking is %FALSE, then @stream must be a
31378 * #GPollableOutputStream for which
31379 * g_pollable_output_stream_can_poll() returns %TRUE or else the
31380 * behavior is undefined. If @blocking is %TRUE, then @stream does not
31381 * need to be a #GPollableOutputStream.
31383 * Returns: the number of bytes written, or -1 on error.
31389 * g_pollable_stream_write_all:
31390 * @stream: a #GOutputStream.
31391 * @buffer: (array length=count) (element-type guint8): the buffer
31392 * containing the data to write.
31393 * @count: the number of bytes to write
31394 * @blocking: whether to do blocking I/O
31395 * @bytes_written: (out): location to store the number of bytes that was
31396 * written to the stream
31397 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
31398 * @error: location to store the error occurring, or %NULL to ignore
31400 * Tries to write @count bytes to @stream, as with
31401 * g_output_stream_write_all(), but using g_pollable_stream_write()
31402 * rather than g_output_stream_write().
31404 * On a successful write of @count bytes, %TRUE is returned, and
31405 * @bytes_written is set to @count.
31407 * If there is an error during the operation (including
31408 * %G_IO_ERROR_WOULD_BLOCK in the non-blocking case), %FALSE is
31409 * returned and @error is set to indicate the error status,
31410 * @bytes_written is updated to contain the number of bytes written
31411 * into the stream before the error occurred.
31413 * As with g_pollable_stream_write(), if @blocking is %FALSE, then
31414 * @stream must be a #GPollableOutputStream for which
31415 * g_pollable_output_stream_can_poll() returns %TRUE or else the
31416 * behavior is undefined. If @blocking is %TRUE, then @stream does not
31417 * need to be a #GPollableOutputStream.
31419 * Returns: %TRUE on success, %FALSE if there was an error
31425 * g_property_action_new:
31426 * @name: the name of the action to create
31427 * @object: (type GObject.Object): the object that has the property
31429 * @property_name: the name of the property
31431 * Creates a #GAction corresponding to the value of property
31432 * @property_name on @object.
31434 * The property must be existent and readable and writable (and not
31437 * This function takes a reference on @object and doesn't release it
31438 * until the action is destroyed.
31440 * Returns: a new #GPropertyAction
31446 * g_proxy_address_get_destination_hostname:
31447 * @proxy: a #GProxyAddress
31449 * Gets @proxy's destination hostname; that is, the name of the host
31450 * that will be connected to via the proxy, not the name of the proxy
31453 * Returns: the @proxy's destination hostname
31459 * g_proxy_address_get_destination_port:
31460 * @proxy: a #GProxyAddress
31462 * Gets @proxy's destination port; that is, the port on the
31463 * destination host that will be connected to via the proxy, not the
31464 * port number of the proxy itself.
31466 * Returns: the @proxy's destination port
31472 * g_proxy_address_get_destination_protocol:
31473 * @proxy: a #GProxyAddress
31475 * Gets the protocol that is being spoken to the destination
31476 * server; eg, "http" or "ftp".
31478 * Returns: the @proxy's destination protocol
31484 * g_proxy_address_get_password:
31485 * @proxy: a #GProxyAddress
31487 * Gets @proxy's password.
31489 * Returns: the @proxy's password
31495 * g_proxy_address_get_protocol:
31496 * @proxy: a #GProxyAddress
31498 * Gets @proxy's protocol. eg, "socks" or "http"
31500 * Returns: the @proxy's protocol
31506 * g_proxy_address_get_uri:
31507 * @proxy: a #GProxyAddress
31509 * Gets the proxy URI that @proxy was constructed from.
31511 * Returns: the @proxy's URI, or %NULL if unknown
31517 * g_proxy_address_get_username:
31518 * @proxy: a #GProxyAddress
31520 * Gets @proxy's username.
31522 * Returns: the @proxy's username
31528 * g_proxy_address_new:
31529 * @inetaddr: The proxy server #GInetAddress.
31530 * @port: The proxy server port.
31531 * @protocol: The proxy protocol to support, in lower case (e.g. socks, http).
31532 * @dest_hostname: The destination hostname the proxy should tunnel to.
31533 * @dest_port: The destination port to tunnel to.
31534 * @username: (allow-none): The username to authenticate to the proxy server
31536 * @password: (allow-none): The password to authenticate to the proxy server
31539 * Creates a new #GProxyAddress for @inetaddr with @protocol that should
31540 * tunnel through @dest_hostname and @dest_port.
31542 * (Note that this method doesn't set the #GProxyAddress:uri or
31543 * #GProxyAddress:destination-protocol fields; use g_object_new()
31544 * directly if you want to set those.)
31546 * Returns: a new #GProxyAddress
31553 * @proxy: a #GProxy
31554 * @connection: a #GIOStream
31555 * @proxy_address: a #GProxyAddress
31556 * @cancellable: (allow-none): a #GCancellable
31557 * @error: return #GError
31559 * Given @connection to communicate with a proxy (eg, a
31560 * #GSocketConnection that is connected to the proxy server), this
31561 * does the necessary handshake to connect to @proxy_address, and if
31562 * required, wraps the #GIOStream to handle proxy payload.
31564 * Returns: (transfer full): a #GIOStream that will replace @connection. This might
31565 * be the same as @connection, in which case a reference
31572 * g_proxy_connect_async:
31573 * @proxy: a #GProxy
31574 * @connection: a #GIOStream
31575 * @proxy_address: a #GProxyAddress
31576 * @cancellable: (allow-none): a #GCancellable
31577 * @callback: (scope async): a #GAsyncReadyCallback
31578 * @user_data: (closure): callback data
31580 * Asynchronous version of g_proxy_connect().
31587 * g_proxy_connect_finish:
31588 * @proxy: a #GProxy
31589 * @result: a #GAsyncResult
31590 * @error: return #GError
31592 * See g_proxy_connect().
31594 * Returns: (transfer full): a #GIOStream.
31600 * g_proxy_get_default_for_protocol:
31601 * @protocol: the proxy protocol name (e.g. http, socks, etc)
31603 * Lookup "gio-proxy" extension point for a proxy implementation that supports
31604 * specified protocol.
31606 * Returns: (transfer full): return a #GProxy or NULL if protocol
31607 * is not supported.
31613 * g_proxy_resolver_get_default:
31615 * Gets the default #GProxyResolver for the system.
31617 * Returns: (transfer none): the default #GProxyResolver.
31623 * g_proxy_resolver_is_supported:
31624 * @resolver: a #GProxyResolver
31626 * Checks if @resolver can be used on this system. (This is used
31627 * internally; g_proxy_resolver_get_default() will only return a proxy
31628 * resolver that returns %TRUE for this method.)
31630 * Returns: %TRUE if @resolver is supported.
31636 * g_proxy_resolver_lookup:
31637 * @resolver: a #GProxyResolver
31638 * @uri: a URI representing the destination to connect to
31639 * @cancellable: (allow-none): a #GCancellable, or %NULL
31640 * @error: return location for a #GError, or %NULL
31642 * Looks into the system proxy configuration to determine what proxy,
31643 * if any, to use to connect to @uri. The returned proxy URIs are of
31644 * the form `<protocol>://[user[:password]@]host:port` or
31645 * `direct://`, where <protocol> could be http, rtsp, socks
31646 * or other proxying protocol.
31648 * If you don't know what network protocol is being used on the
31649 * socket, you should use `none` as the URI protocol.
31650 * In this case, the resolver might still return a generic proxy type
31651 * (such as SOCKS), but would not return protocol-specific proxy types
31654 * `direct://` is used when no proxy is needed.
31655 * Direct connection should not be attempted unless it is part of the
31656 * returned array of proxies.
31658 * Returns: (transfer full) (array zero-terminated=1): A
31659 * NULL-terminated array of proxy URIs. Must be freed
31660 * with g_strfreev().
31666 * g_proxy_resolver_lookup_async:
31667 * @resolver: a #GProxyResolver
31668 * @uri: a URI representing the destination to connect to
31669 * @cancellable: (allow-none): a #GCancellable, or %NULL
31670 * @callback: (scope async): callback to call after resolution completes
31671 * @user_data: (closure): data for @callback
31673 * Asynchronous lookup of proxy. See g_proxy_resolver_lookup() for more
31681 * g_proxy_resolver_lookup_finish:
31682 * @resolver: a #GProxyResolver
31683 * @result: the result passed to your #GAsyncReadyCallback
31684 * @error: return location for a #GError, or %NULL
31686 * Call this function to obtain the array of proxy URIs when
31687 * g_proxy_resolver_lookup_async() is complete. See
31688 * g_proxy_resolver_lookup() for more details.
31690 * Returns: (transfer full) (array zero-terminated=1): A
31691 * NULL-terminated array of proxy URIs. Must be freed
31692 * with g_strfreev().
31698 * g_proxy_supports_hostname:
31699 * @proxy: a #GProxy
31701 * Some proxy protocols expect to be passed a hostname, which they
31702 * will resolve to an IP address themselves. Others, like SOCKS4, do
31703 * not allow this. This function will return %FALSE if @proxy is
31704 * implementing such a protocol. When %FALSE is returned, the caller
31705 * should resolve the destination hostname first, and then pass a
31706 * #GProxyAddress containing the stringified IP address to
31707 * g_proxy_connect() or g_proxy_connect_async().
31709 * Returns: %TRUE if hostname resolution is supported.
31715 * g_remote_action_group_activate_action_full:
31716 * @remote: a #GDBusActionGroup
31717 * @action_name: the name of the action to activate
31718 * @parameter: (allow-none): the optional parameter to the activation
31719 * @platform_data: the platform data to send
31721 * Activates the remote action.
31723 * This is the same as g_action_group_activate_action() except that it
31724 * allows for provision of "platform data" to be sent along with the
31725 * activation request. This typically contains details such as the user
31726 * interaction timestamp or startup notification information.
31728 * @platform_data must be non-%NULL and must have the type
31729 * %G_VARIANT_TYPE_VARDICT. If it is floating, it will be consumed.
31736 * g_remote_action_group_change_action_state_full:
31737 * @remote: a #GRemoteActionGroup
31738 * @action_name: the name of the action to change the state of
31739 * @value: the new requested value for the state
31740 * @platform_data: the platform data to send
31742 * Changes the state of a remote action.
31744 * This is the same as g_action_group_change_action_state() except that
31745 * it allows for provision of "platform data" to be sent along with the
31746 * state change request. This typically contains details such as the
31747 * user interaction timestamp or startup notification information.
31749 * @platform_data must be non-%NULL and must have the type
31750 * %G_VARIANT_TYPE_VARDICT. If it is floating, it will be consumed.
31757 * g_resolver_error_quark:
31759 * Gets the #GResolver Error Quark.
31761 * Returns: a #GQuark.
31767 * g_resolver_free_addresses: (skip)
31768 * @addresses: a #GList of #GInetAddress
31770 * Frees @addresses (which should be the return value from
31771 * g_resolver_lookup_by_name() or g_resolver_lookup_by_name_finish()).
31772 * (This is a convenience method; you can also simply free the results
31780 * g_resolver_free_targets: (skip)
31781 * @targets: a #GList of #GSrvTarget
31783 * Frees @targets (which should be the return value from
31784 * g_resolver_lookup_service() or g_resolver_lookup_service_finish()).
31785 * (This is a convenience method; you can also simply free the
31786 * results by hand.)
31793 * g_resolver_get_default:
31795 * Gets the default #GResolver. You should unref it when you are done
31796 * with it. #GResolver may use its reference count as a hint about how
31797 * many threads it should allocate for concurrent DNS resolutions.
31799 * Returns: (transfer full): the default #GResolver.
31805 * g_resolver_lookup_by_address:
31806 * @resolver: a #GResolver
31807 * @address: the address to reverse-resolve
31808 * @cancellable: (allow-none): a #GCancellable, or %NULL
31809 * @error: return location for a #GError, or %NULL
31811 * Synchronously reverse-resolves @address to determine its
31812 * associated hostname.
31814 * If the DNS resolution fails, @error (if non-%NULL) will be set to
31815 * a value from #GResolverError.
31817 * If @cancellable is non-%NULL, it can be used to cancel the
31818 * operation, in which case @error (if non-%NULL) will be set to
31819 * %G_IO_ERROR_CANCELLED.
31821 * Returns: a hostname (either ASCII-only, or in ASCII-encoded
31822 * form), or %NULL on error.
31828 * g_resolver_lookup_by_address_async:
31829 * @resolver: a #GResolver
31830 * @address: the address to reverse-resolve
31831 * @cancellable: (allow-none): a #GCancellable, or %NULL
31832 * @callback: (scope async): callback to call after resolution completes
31833 * @user_data: (closure): data for @callback
31835 * Begins asynchronously reverse-resolving @address to determine its
31836 * associated hostname, and eventually calls @callback, which must
31837 * call g_resolver_lookup_by_address_finish() to get the final result.
31844 * g_resolver_lookup_by_address_finish:
31845 * @resolver: a #GResolver
31846 * @result: the result passed to your #GAsyncReadyCallback
31847 * @error: return location for a #GError, or %NULL
31849 * Retrieves the result of a previous call to
31850 * g_resolver_lookup_by_address_async().
31852 * If the DNS resolution failed, @error (if non-%NULL) will be set to
31853 * a value from #GResolverError. If the operation was cancelled,
31854 * @error will be set to %G_IO_ERROR_CANCELLED.
31856 * Returns: a hostname (either ASCII-only, or in ASCII-encoded
31857 * form), or %NULL on error.
31863 * g_resolver_lookup_by_name:
31864 * @resolver: a #GResolver
31865 * @hostname: the hostname to look up
31866 * @cancellable: (allow-none): a #GCancellable, or %NULL
31867 * @error: return location for a #GError, or %NULL
31869 * Synchronously resolves @hostname to determine its associated IP
31870 * address(es). @hostname may be an ASCII-only or UTF-8 hostname, or
31871 * the textual form of an IP address (in which case this just becomes
31872 * a wrapper around g_inet_address_new_from_string()).
31874 * On success, g_resolver_lookup_by_name() will return a non-empty #GList of
31875 * #GInetAddress, sorted in order of preference and guaranteed to not
31876 * contain duplicates. That is, if using the result to connect to
31877 * @hostname, you should attempt to connect to the first address
31878 * first, then the second if the first fails, etc. If you are using
31879 * the result to listen on a socket, it is appropriate to add each
31880 * result using e.g. g_socket_listener_add_address().
31882 * If the DNS resolution fails, @error (if non-%NULL) will be set to a
31883 * value from #GResolverError and %NULL will be returned.
31885 * If @cancellable is non-%NULL, it can be used to cancel the
31886 * operation, in which case @error (if non-%NULL) will be set to
31887 * %G_IO_ERROR_CANCELLED.
31889 * If you are planning to connect to a socket on the resolved IP
31890 * address, it may be easier to create a #GNetworkAddress and use its
31891 * #GSocketConnectable interface.
31893 * Returns: (element-type GInetAddress) (transfer full): a non-empty #GList
31894 * of #GInetAddress, or %NULL on error. You
31895 * must unref each of the addresses and free the list when you are
31896 * done with it. (You can use g_resolver_free_addresses() to do this.)
31902 * g_resolver_lookup_by_name_async:
31903 * @resolver: a #GResolver
31904 * @hostname: the hostname to look up the address of
31905 * @cancellable: (allow-none): a #GCancellable, or %NULL
31906 * @callback: (scope async): callback to call after resolution completes
31907 * @user_data: (closure): data for @callback
31909 * Begins asynchronously resolving @hostname to determine its
31910 * associated IP address(es), and eventually calls @callback, which
31911 * must call g_resolver_lookup_by_name_finish() to get the result.
31912 * See g_resolver_lookup_by_name() for more details.
31919 * g_resolver_lookup_by_name_finish:
31920 * @resolver: a #GResolver
31921 * @result: the result passed to your #GAsyncReadyCallback
31922 * @error: return location for a #GError, or %NULL
31924 * Retrieves the result of a call to
31925 * g_resolver_lookup_by_name_async().
31927 * If the DNS resolution failed, @error (if non-%NULL) will be set to
31928 * a value from #GResolverError. If the operation was cancelled,
31929 * @error will be set to %G_IO_ERROR_CANCELLED.
31931 * Returns: (element-type GInetAddress) (transfer full): a #GList
31932 * of #GInetAddress, or %NULL on error. See g_resolver_lookup_by_name()
31933 * for more details.
31939 * g_resolver_lookup_records:
31940 * @resolver: a #GResolver
31941 * @rrname: the DNS name to lookup the record for
31942 * @record_type: the type of DNS record to lookup
31943 * @cancellable: (allow-none): a #GCancellable, or %NULL
31944 * @error: return location for a #GError, or %NULL
31946 * Synchronously performs a DNS record lookup for the given @rrname and returns
31947 * a list of records as #GVariant tuples. See #GResolverRecordType for
31948 * information on what the records contain for each @record_type.
31950 * If the DNS resolution fails, @error (if non-%NULL) will be set to
31951 * a value from #GResolverError and %NULL will be returned.
31953 * If @cancellable is non-%NULL, it can be used to cancel the
31954 * operation, in which case @error (if non-%NULL) will be set to
31955 * %G_IO_ERROR_CANCELLED.
31957 * Returns: (element-type GVariant) (transfer full): a non-empty #GList of
31958 * #GVariant, or %NULL on error. You must free each of the records and the list
31959 * when you are done with it. (You can use g_list_free_full() with
31960 * g_variant_unref() to do this.)
31966 * g_resolver_lookup_records_async:
31967 * @resolver: a #GResolver
31968 * @rrname: the DNS name to lookup the record for
31969 * @record_type: the type of DNS record to lookup
31970 * @cancellable: (allow-none): a #GCancellable, or %NULL
31971 * @callback: (scope async): callback to call after resolution completes
31972 * @user_data: (closure): data for @callback
31974 * Begins asynchronously performing a DNS lookup for the given
31975 * @rrname, and eventually calls @callback, which must call
31976 * g_resolver_lookup_records_finish() to get the final result. See
31977 * g_resolver_lookup_records() for more details.
31984 * g_resolver_lookup_records_finish:
31985 * @resolver: a #GResolver
31986 * @result: the result passed to your #GAsyncReadyCallback
31987 * @error: return location for a #GError, or %NULL
31989 * Retrieves the result of a previous call to
31990 * g_resolver_lookup_records_async(). Returns a non-empty list of records as
31991 * #GVariant tuples. See #GResolverRecordType for information on what the
31994 * If the DNS resolution failed, @error (if non-%NULL) will be set to
31995 * a value from #GResolverError. If the operation was cancelled,
31996 * @error will be set to %G_IO_ERROR_CANCELLED.
31998 * Returns: (element-type GVariant) (transfer full): a non-empty #GList of
31999 * #GVariant, or %NULL on error. You must free each of the records and the list
32000 * when you are done with it. (You can use g_list_free_full() with
32001 * g_variant_unref() to do this.)
32007 * g_resolver_lookup_service:
32008 * @resolver: a #GResolver
32009 * @service: the service type to look up (eg, "ldap")
32010 * @protocol: the networking protocol to use for @service (eg, "tcp")
32011 * @domain: the DNS domain to look up the service in
32012 * @cancellable: (allow-none): a #GCancellable, or %NULL
32013 * @error: return location for a #GError, or %NULL
32015 * Synchronously performs a DNS SRV lookup for the given @service and
32016 * @protocol in the given @domain and returns an array of #GSrvTarget.
32017 * @domain may be an ASCII-only or UTF-8 hostname. Note also that the
32018 * @service and @protocol arguments do not include the leading underscore
32019 * that appears in the actual DNS entry.
32021 * On success, g_resolver_lookup_service() will return a non-empty #GList of
32022 * #GSrvTarget, sorted in order of preference. (That is, you should
32023 * attempt to connect to the first target first, then the second if
32024 * the first fails, etc.)
32026 * If the DNS resolution fails, @error (if non-%NULL) will be set to
32027 * a value from #GResolverError and %NULL will be returned.
32029 * If @cancellable is non-%NULL, it can be used to cancel the
32030 * operation, in which case @error (if non-%NULL) will be set to
32031 * %G_IO_ERROR_CANCELLED.
32033 * If you are planning to connect to the service, it is usually easier
32034 * to create a #GNetworkService and use its #GSocketConnectable
32037 * Returns: (element-type GSrvTarget) (transfer full): a non-empty #GList of
32038 * #GSrvTarget, or %NULL on error. You must free each of the targets and the
32039 * list when you are done with it. (You can use g_resolver_free_targets() to do
32046 * g_resolver_lookup_service_async:
32047 * @resolver: a #GResolver
32048 * @service: the service type to look up (eg, "ldap")
32049 * @protocol: the networking protocol to use for @service (eg, "tcp")
32050 * @domain: the DNS domain to look up the service in
32051 * @cancellable: (allow-none): a #GCancellable, or %NULL
32052 * @callback: (scope async): callback to call after resolution completes
32053 * @user_data: (closure): data for @callback
32055 * Begins asynchronously performing a DNS SRV lookup for the given
32056 * @service and @protocol in the given @domain, and eventually calls
32057 * @callback, which must call g_resolver_lookup_service_finish() to
32058 * get the final result. See g_resolver_lookup_service() for more
32066 * g_resolver_lookup_service_finish:
32067 * @resolver: a #GResolver
32068 * @result: the result passed to your #GAsyncReadyCallback
32069 * @error: return location for a #GError, or %NULL
32071 * Retrieves the result of a previous call to
32072 * g_resolver_lookup_service_async().
32074 * If the DNS resolution failed, @error (if non-%NULL) will be set to
32075 * a value from #GResolverError. If the operation was cancelled,
32076 * @error will be set to %G_IO_ERROR_CANCELLED.
32078 * Returns: (element-type GSrvTarget) (transfer full): a non-empty #GList of
32079 * #GSrvTarget, or %NULL on error. See g_resolver_lookup_service() for more
32086 * g_resolver_set_default:
32087 * @resolver: the new default #GResolver
32089 * Sets @resolver to be the application's default resolver (reffing
32090 * @resolver, and unreffing the previous default resolver, if any).
32091 * Future calls to g_resolver_get_default() will return this resolver.
32093 * This can be used if an application wants to perform any sort of DNS
32094 * caching or "pinning"; it can implement its own #GResolver that
32095 * calls the original default resolver for DNS operations, and
32096 * implements its own cache policies on top of that, and then set
32097 * itself as the default resolver for all later code to use.
32104 * g_resource_enumerate_children:
32105 * @resource: A #GResource
32106 * @path: A pathname inside the resource
32107 * @lookup_flags: A #GResourceLookupFlags
32108 * @error: return location for a #GError, or %NULL
32110 * Returns all the names of children at the specified @path in the resource.
32111 * The return result is a %NULL terminated list of strings which should
32112 * be released with g_strfreev().
32114 * If @path is invalid or does not exist in the #GResource,
32115 * %G_RESOURCE_ERROR_NOT_FOUND will be returned.
32117 * @lookup_flags controls the behaviour of the lookup.
32119 * Returns: (array zero-terminated=1) (transfer full): an array of constant strings
32125 * g_resource_error_quark:
32127 * Gets the #GResource Error Quark.
32129 * Returns: a #GQuark
32135 * g_resource_get_info:
32136 * @resource: A #GResource
32137 * @path: A pathname inside the resource
32138 * @lookup_flags: A #GResourceLookupFlags
32139 * @size: (out) (allow-none): a location to place the length of the contents of the file,
32140 * or %NULL if the length is not needed
32141 * @flags: (out) (allow-none): a location to place the flags about the file,
32142 * or %NULL if the length is not needed
32143 * @error: return location for a #GError, or %NULL
32145 * Looks for a file at the specified @path in the resource and
32146 * if found returns information about it.
32148 * @lookup_flags controls the behaviour of the lookup.
32150 * Returns: %TRUE if the file was found. %FALSE if there were errors
32157 * @filename: (type filename): the path of a filename to load, in the GLib filename encoding
32158 * @error: return location for a #GError, or %NULL
32160 * Loads a binary resource bundle and creates a #GResource representation of it, allowing
32161 * you to query it for data.
32163 * If you want to use this resource in the global resource namespace you need
32164 * to register it with g_resources_register().
32166 * Returns: (transfer full): a new #GResource, or %NULL on error
32172 * g_resource_lookup_data:
32173 * @resource: A #GResource
32174 * @path: A pathname inside the resource
32175 * @lookup_flags: A #GResourceLookupFlags
32176 * @error: return location for a #GError, or %NULL
32178 * Looks for a file at the specified @path in the resource and
32179 * returns a #GBytes that lets you directly access the data in
32182 * The data is always followed by a zero byte, so you
32183 * can safely use the data as a C string. However, that byte
32184 * is not included in the size of the GBytes.
32186 * For uncompressed resource files this is a pointer directly into
32187 * the resource bundle, which is typically in some readonly data section
32188 * in the program binary. For compressed files we allocate memory on
32189 * the heap and automatically uncompress the data.
32191 * @lookup_flags controls the behaviour of the lookup.
32193 * Returns: (transfer full): #GBytes or %NULL on error.
32194 * Free the returned object with g_bytes_unref()
32200 * g_resource_new_from_data:
32202 * @error: return location for a #GError, or %NULL
32204 * Creates a GResource from a reference to the binary resource bundle.
32205 * This will keep a reference to @data while the resource lives, so
32206 * the data should not be modified or freed.
32208 * If you want to use this resource in the global resource namespace you need
32209 * to register it with g_resources_register().
32211 * Returns: (transfer full): a new #GResource, or %NULL on error
32217 * g_resource_open_stream:
32218 * @resource: A #GResource
32219 * @path: A pathname inside the resource
32220 * @lookup_flags: A #GResourceLookupFlags
32221 * @error: return location for a #GError, or %NULL
32223 * Looks for a file at the specified @path in the resource and
32224 * returns a #GInputStream that lets you read the data.
32226 * @lookup_flags controls the behaviour of the lookup.
32228 * Returns: (transfer full): #GInputStream or %NULL on error.
32229 * Free the returned object with g_object_unref()
32236 * @resource: A #GResource
32238 * Atomically increments the reference count of @resource by one. This
32239 * function is MT-safe and may be called from any thread.
32241 * Returns: The passed in #GResource
32247 * g_resource_unref:
32248 * @resource: A #GResource
32250 * Atomically decrements the reference count of @resource by one. If the
32251 * reference count drops to 0, all memory allocated by the resource is
32252 * released. This function is MT-safe and may be called from any
32260 * g_resources_enumerate_children:
32261 * @path: A pathname inside the resource
32262 * @lookup_flags: A #GResourceLookupFlags
32263 * @error: return location for a #GError, or %NULL
32265 * Returns all the names of children at the specified @path in the set of
32266 * globally registered resources.
32267 * The return result is a %NULL terminated list of strings which should
32268 * be released with g_strfreev().
32270 * @lookup_flags controls the behaviour of the lookup.
32272 * Returns: (array zero-terminated=1) (transfer full): an array of constant strings
32278 * g_resources_get_info:
32279 * @path: A pathname inside the resource
32280 * @lookup_flags: A #GResourceLookupFlags
32281 * @size: (out) (allow-none): a location to place the length of the contents of the file,
32282 * or %NULL if the length is not needed
32283 * @flags: (out) (allow-none): a location to place the flags about the file,
32284 * or %NULL if the length is not needed
32285 * @error: return location for a #GError, or %NULL
32287 * Looks for a file at the specified @path in the set of
32288 * globally registered resources and if found returns information about it.
32290 * @lookup_flags controls the behaviour of the lookup.
32292 * Returns: %TRUE if the file was found. %FALSE if there were errors
32298 * g_resources_lookup_data:
32299 * @path: A pathname inside the resource
32300 * @lookup_flags: A #GResourceLookupFlags
32301 * @error: return location for a #GError, or %NULL
32303 * Looks for a file at the specified @path in the set of
32304 * globally registered resources and returns a #GBytes that
32305 * lets you directly access the data in memory.
32307 * The data is always followed by a zero byte, so you
32308 * can safely use the data as a C string. However, that byte
32309 * is not included in the size of the GBytes.
32311 * For uncompressed resource files this is a pointer directly into
32312 * the resource bundle, which is typically in some readonly data section
32313 * in the program binary. For compressed files we allocate memory on
32314 * the heap and automatically uncompress the data.
32316 * @lookup_flags controls the behaviour of the lookup.
32318 * Returns: (transfer full): #GBytes or %NULL on error.
32319 * Free the returned object with g_bytes_unref()
32325 * g_resources_open_stream:
32326 * @path: A pathname inside the resource
32327 * @lookup_flags: A #GResourceLookupFlags
32328 * @error: return location for a #GError, or %NULL
32330 * Looks for a file at the specified @path in the set of
32331 * globally registered resources and returns a #GInputStream
32332 * that lets you read the data.
32334 * @lookup_flags controls the behaviour of the lookup.
32336 * Returns: (transfer full): #GInputStream or %NULL on error.
32337 * Free the returned object with g_object_unref()
32343 * g_resources_register:
32344 * @resource: A #GResource
32346 * Registers the resource with the process-global set of resources.
32347 * Once a resource is registered the files in it can be accessed
32348 * with the global resource lookup functions like g_resources_lookup_data().
32355 * g_resources_unregister:
32356 * @resource: A #GResource
32358 * Unregisters the resource from the process-global set of resources.
32365 * g_seekable_can_seek:
32366 * @seekable: a #GSeekable.
32368 * Tests if the stream supports the #GSeekableIface.
32370 * Returns: %TRUE if @seekable can be seeked. %FALSE otherwise.
32375 * g_seekable_can_truncate:
32376 * @seekable: a #GSeekable.
32378 * Tests if the stream can be truncated.
32380 * Returns: %TRUE if the stream can be truncated, %FALSE otherwise.
32386 * @seekable: a #GSeekable.
32387 * @offset: a #goffset.
32388 * @type: a #GSeekType.
32389 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
32390 * @error: a #GError location to store the error occurring, or %NULL to
32393 * Seeks in the stream by the given @offset, modified by @type.
32395 * Attempting to seek past the end of the stream will have different
32396 * results depending on if the stream is fixed-sized or resizable. If
32397 * the stream is resizable then seeking past the end and then writing
32398 * will result in zeros filling the empty space. Seeking past the end
32399 * of a resizable stream and reading will result in EOF. Seeking past
32400 * the end of a fixed-sized stream will fail.
32402 * Any operation that would result in a negative offset will fail.
32404 * If @cancellable is not %NULL, then the operation can be cancelled by
32405 * triggering the cancellable object from another thread. If the operation
32406 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
32408 * Returns: %TRUE if successful. If an error
32409 * has occurred, this function will return %FALSE and set @error
32410 * appropriately if present.
32416 * @seekable: a #GSeekable.
32418 * Tells the current position within the stream.
32420 * Returns: the offset from the beginning of the buffer.
32425 * g_seekable_truncate: (virtual truncate_fn)
32426 * @seekable: a #GSeekable.
32427 * @offset: a #goffset.
32428 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
32429 * @error: a #GError location to store the error occurring, or %NULL to
32432 * Truncates a stream with a given #offset.
32434 * If @cancellable is not %NULL, then the operation can be cancelled by
32435 * triggering the cancellable object from another thread. If the operation
32436 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
32437 * operation was partially finished when the operation was cancelled the
32438 * partial result will be returned, without an error.
32440 * Returns: %TRUE if successful. If an error
32441 * has occurred, this function will return %FALSE and set @error
32442 * appropriately if present.
32447 * g_settings_apply:
32448 * @settings: a #GSettings instance
32450 * Applies any changes that have been made to the settings. This
32451 * function does nothing unless @settings is in 'delay-apply' mode;
32452 * see g_settings_delay(). In the normal case settings are always
32453 * applied immediately.
32458 * g_settings_backend_changed:
32459 * @backend: a #GSettingsBackend implementation
32460 * @key: the name of the key
32461 * @origin_tag: the origin tag
32463 * Signals that a single key has possibly changed. Backend
32464 * implementations should call this if a key has possibly changed its
32467 * @key must be a valid key (ie starting with a slash, not containing
32468 * '//', and not ending with a slash).
32470 * The implementation must call this function during any call to
32471 * g_settings_backend_write(), before the call returns (except in the
32472 * case that no keys are actually changed and it cares to detect this
32473 * fact). It may not rely on the existence of a mainloop for
32474 * dispatching the signal later.
32476 * The implementation may call this function at any other time it likes
32477 * in response to other events (such as changes occurring outside of the
32478 * program). These calls may originate from a mainloop or may originate
32479 * in response to any other action (including from calls to
32480 * g_settings_backend_write()).
32482 * In the case that this call is in response to a call to
32483 * g_settings_backend_write() then @origin_tag must be set to the same
32484 * value that was passed to that call.
32491 * g_settings_backend_changed_tree:
32492 * @backend: a #GSettingsBackend implementation
32493 * @tree: a #GTree containing the changes
32494 * @origin_tag: the origin tag
32496 * This call is a convenience wrapper. It gets the list of changes from
32497 * @tree, computes the longest common prefix and calls
32498 * g_settings_backend_changed().
32505 * g_settings_backend_flatten_tree:
32506 * @tree: a #GTree containing the changes
32507 * @path: (out): the location to save the path
32508 * @keys: (out) (transfer container) (array zero-terminated=1): the
32509 * location to save the relative keys
32510 * @values: (out) (allow-none) (transfer container) (array zero-terminated=1):
32511 * the location to save the values, or %NULL
32513 * Calculate the longest common prefix of all keys in a tree and write
32514 * out an array of the key names relative to that prefix and,
32515 * optionally, the value to store at each of those keys.
32517 * You must free the value returned in @path, @keys and @values using
32518 * g_free(). You should not attempt to free or unref the contents of
32519 * @keys or @values.
32526 * g_settings_backend_get_default:
32528 * Returns the default #GSettingsBackend. It is possible to override
32529 * the default by setting the `GSETTINGS_BACKEND` environment variable
32530 * to the name of a settings backend.
32532 * The user gets a reference to the backend.
32534 * Returns: (transfer full): the default #GSettingsBackend
32540 * g_settings_backend_keys_changed:
32541 * @backend: a #GSettingsBackend implementation
32542 * @path: the path containing the changes
32543 * @items: (array zero-terminated=1): the %NULL-terminated list of changed keys
32544 * @origin_tag: the origin tag
32546 * Signals that a list of keys have possibly changed. Backend
32547 * implementations should call this if keys have possibly changed their
32550 * @path must be a valid path (ie starting and ending with a slash and
32551 * not containing '//'). Each string in @items must form a valid key
32552 * name when @path is prefixed to it (ie: each item must not start or
32553 * end with '/' and must not contain '//').
32555 * The meaning of this signal is that any of the key names resulting
32556 * from the contatenation of @path with each item in @items may have
32559 * The same rules for when notifications must occur apply as per
32560 * g_settings_backend_changed(). These two calls can be used
32561 * interchangeably if exactly one item has changed (although in that
32562 * case g_settings_backend_changed() is definitely preferred).
32564 * For efficiency reasons, the implementation should strive for @path to
32565 * be as long as possible (ie: the longest common prefix of all of the
32566 * keys that were changed) but this is not strictly required.
32573 * g_settings_backend_path_changed:
32574 * @backend: a #GSettingsBackend implementation
32575 * @path: the path containing the changes
32576 * @origin_tag: the origin tag
32578 * Signals that all keys below a given path may have possibly changed.
32579 * Backend implementations should call this if an entire path of keys
32580 * have possibly changed their values.
32582 * @path must be a valid path (ie starting and ending with a slash and
32583 * not containing '//').
32585 * The meaning of this signal is that any of the key which has a name
32586 * starting with @path may have changed.
32588 * The same rules for when notifications must occur apply as per
32589 * g_settings_backend_changed(). This call might be an appropriate
32590 * reasponse to a 'reset' call but implementations are also free to
32591 * explicitly list the keys that were affected by that call if they can
32594 * For efficiency reasons, the implementation should strive for @path to
32595 * be as long as possible (ie: the longest common prefix of all of the
32596 * keys that were changed) but this is not strictly required. As an
32597 * example, if this function is called with the path of "/" then every
32598 * single key in the application will be notified of a possible change.
32605 * g_settings_backend_path_writable_changed:
32606 * @backend: a #GSettingsBackend implementation
32607 * @path: the name of the path
32609 * Signals that the writability of all keys below a given path may have
32612 * Since GSettings performs no locking operations for itself, this call
32613 * will always be made in response to external events.
32620 * g_settings_backend_writable_changed:
32621 * @backend: a #GSettingsBackend implementation
32622 * @key: the name of the key
32624 * Signals that the writability of a single key has possibly changed.
32626 * Since GSettings performs no locking operations for itself, this call
32627 * will always be made in response to external events.
32635 * @settings: a #GSettings object
32636 * @key: the key to bind
32637 * @object: (type GObject.Object): a #GObject
32638 * @property: the name of the property to bind
32639 * @flags: flags for the binding
32641 * Create a binding between the @key in the @settings object
32642 * and the property @property of @object.
32644 * The binding uses the default GIO mapping functions to map
32645 * between the settings and property values. These functions
32646 * handle booleans, numeric types and string types in a
32647 * straightforward way. Use g_settings_bind_with_mapping() if
32648 * you need a custom mapping, or map between types that are not
32649 * supported by the default mapping functions.
32651 * Unless the @flags include %G_SETTINGS_BIND_NO_SENSITIVITY, this
32652 * function also establishes a binding between the writability of
32653 * @key and the "sensitive" property of @object (if @object has
32654 * a boolean property by that name). See g_settings_bind_writable()
32655 * for more details about writable bindings.
32657 * Note that the lifecycle of the binding is tied to the object,
32658 * and that you can have only one binding per object property.
32659 * If you bind the same property twice on the same object, the second
32660 * binding overrides the first one.
32667 * g_settings_bind_with_mapping: (skip)
32668 * @settings: a #GSettings object
32669 * @key: the key to bind
32670 * @object: (type GObject.Object): a #GObject
32671 * @property: the name of the property to bind
32672 * @flags: flags for the binding
32673 * @get_mapping: a function that gets called to convert values
32674 * from @settings to @object, or %NULL to use the default GIO mapping
32675 * @set_mapping: a function that gets called to convert values
32676 * from @object to @settings, or %NULL to use the default GIO mapping
32677 * @user_data: data that gets passed to @get_mapping and @set_mapping
32678 * @destroy: #GDestroyNotify function for @user_data
32680 * Create a binding between the @key in the @settings object
32681 * and the property @property of @object.
32683 * The binding uses the provided mapping functions to map between
32684 * settings and property values.
32686 * Note that the lifecycle of the binding is tied to the object,
32687 * and that you can have only one binding per object property.
32688 * If you bind the same property twice on the same object, the second
32689 * binding overrides the first one.
32696 * g_settings_bind_writable:
32697 * @settings: a #GSettings object
32698 * @key: the key to bind
32699 * @object: (type GObject.Object): a #GObject
32700 * @property: the name of a boolean property to bind
32701 * @inverted: whether to 'invert' the value
32703 * Create a binding between the writability of @key in the
32704 * @settings object and the property @property of @object.
32705 * The property must be boolean; "sensitive" or "visible"
32706 * properties of widgets are the most likely candidates.
32708 * Writable bindings are always uni-directional; changes of the
32709 * writability of the setting will be propagated to the object
32710 * property, not the other way.
32712 * When the @inverted argument is %TRUE, the binding inverts the
32713 * value as it passes from the setting to the object, i.e. @property
32714 * will be set to %TRUE if the key is not writable.
32716 * Note that the lifecycle of the binding is tied to the object,
32717 * and that you can have only one binding per object property.
32718 * If you bind the same property twice on the same object, the second
32719 * binding overrides the first one.
32726 * g_settings_create_action:
32727 * @settings: a #GSettings
32728 * @key: the name of a key in @settings
32730 * Creates a #GAction corresponding to a given #GSettings key.
32732 * The action has the same name as the key.
32734 * The value of the key becomes the state of the action and the action
32735 * is enabled when the key is writable. Changing the state of the
32736 * action results in the key being written to. Changes to the value or
32737 * writability of the key cause appropriate change notifications to be
32738 * emitted for the action.
32740 * For boolean-valued keys, action activations take no parameter and
32741 * result in the toggling of the value. For all other types,
32742 * activations take the new value for the key (which must have the
32745 * Returns: (transfer full): a new #GAction
32751 * g_settings_delay:
32752 * @settings: a #GSettings object
32754 * Changes the #GSettings object into 'delay-apply' mode. In this
32755 * mode, changes to @settings are not immediately propagated to the
32756 * backend, but kept locally until g_settings_apply() is called.
32764 * @settings: a #GSettings object
32765 * @key: the key to get the value for
32766 * @format: a #GVariant format string
32767 * @...: arguments as per @format
32769 * Gets the value that is stored at @key in @settings.
32771 * A convenience function that combines g_settings_get_value() with
32774 * It is a programmer error to give a @key that isn't contained in the
32775 * schema for @settings or for the #GVariantType of @format to mismatch
32776 * the type given in the schema.
32783 * g_settings_get_boolean:
32784 * @settings: a #GSettings object
32785 * @key: the key to get the value for
32787 * Gets the value that is stored at @key in @settings.
32789 * A convenience variant of g_settings_get() for booleans.
32791 * It is a programmer error to give a @key that isn't specified as
32792 * having a boolean type in the schema for @settings.
32794 * Returns: a boolean
32800 * g_settings_get_child:
32801 * @settings: a #GSettings object
32802 * @name: the name of the child schema
32804 * Creates a child settings object which has a base path of
32805 * `base-path/@name`, where `base-path` is the base path of
32808 * The schema for the child settings object must have been declared
32809 * in the schema of @settings using a <child> element.
32811 * Returns: (transfer full): a 'child' settings object
32817 * g_settings_get_default_value:
32818 * @settings: a #GSettings object
32819 * @key: the key to get the default value for
32821 * Gets the "default value" of a key.
32823 * This is the value that would be read if g_settings_reset() were to be
32824 * called on the key.
32826 * Note that this may be a different value than returned by
32827 * g_settings_schema_key_get_default_value() if the system administrator
32828 * has provided a default value.
32830 * Comparing the return values of g_settings_get_default_value() and
32831 * g_settings_get_value() is not sufficient for determining if a value
32832 * has been set because the user may have explicitly set the value to
32833 * something that happens to be equal to the default. The difference
32834 * here is that if the default changes in the future, the user's key
32835 * will still be set.
32837 * This function may be useful for adding an indication to a UI of what
32838 * the default value was before the user set it.
32840 * It is a programmer error to give a @key that isn't contained in the
32841 * schema for @settings.
32843 * Returns: (allow-none) (transfer full): the default value
32849 * g_settings_get_double:
32850 * @settings: a #GSettings object
32851 * @key: the key to get the value for
32853 * Gets the value that is stored at @key in @settings.
32855 * A convenience variant of g_settings_get() for doubles.
32857 * It is a programmer error to give a @key that isn't specified as
32858 * having a 'double' type in the schema for @settings.
32860 * Returns: a double
32866 * g_settings_get_enum:
32867 * @settings: a #GSettings object
32868 * @key: the key to get the value for
32870 * Gets the value that is stored in @settings for @key and converts it
32871 * to the enum value that it represents.
32873 * In order to use this function the type of the value must be a string
32874 * and it must be marked in the schema file as an enumerated type.
32876 * It is a programmer error to give a @key that isn't contained in the
32877 * schema for @settings or is not marked as an enumerated type.
32879 * If the value stored in the configuration database is not a valid
32880 * value for the enumerated type then this function will return the
32883 * Returns: the enum value
32889 * g_settings_get_flags:
32890 * @settings: a #GSettings object
32891 * @key: the key to get the value for
32893 * Gets the value that is stored in @settings for @key and converts it
32894 * to the flags value that it represents.
32896 * In order to use this function the type of the value must be an array
32897 * of strings and it must be marked in the schema file as an flags type.
32899 * It is a programmer error to give a @key that isn't contained in the
32900 * schema for @settings or is not marked as a flags type.
32902 * If the value stored in the configuration database is not a valid
32903 * value for the flags type then this function will return the default
32906 * Returns: the flags value
32912 * g_settings_get_has_unapplied:
32913 * @settings: a #GSettings object
32915 * Returns whether the #GSettings object has any unapplied
32916 * changes. This can only be the case if it is in 'delayed-apply' mode.
32918 * Returns: %TRUE if @settings has unapplied changes
32924 * g_settings_get_int:
32925 * @settings: a #GSettings object
32926 * @key: the key to get the value for
32928 * Gets the value that is stored at @key in @settings.
32930 * A convenience variant of g_settings_get() for 32-bit integers.
32932 * It is a programmer error to give a @key that isn't specified as
32933 * having a int32 type in the schema for @settings.
32935 * Returns: an integer
32941 * g_settings_get_int64:
32942 * @settings: a #GSettings object
32943 * @key: the key to get the value for
32945 * Gets the value that is stored at @key in @settings.
32947 * A convenience variant of g_settings_get() for 64-bit integers.
32949 * It is a programmer error to give a @key that isn't specified as
32950 * having a int64 type in the schema for @settings.
32952 * Returns: a 64-bit integer
32958 * g_settings_get_mapped:
32959 * @settings: a #GSettings object
32960 * @key: the key to get the value for
32961 * @mapping: (scope call): the function to map the value in the
32962 * settings database to the value used by the application
32963 * @user_data: user data for @mapping
32965 * Gets the value that is stored at @key in @settings, subject to
32966 * application-level validation/mapping.
32968 * You should use this function when the application needs to perform
32969 * some processing on the value of the key (for example, parsing). The
32970 * @mapping function performs that processing. If the function
32971 * indicates that the processing was unsuccessful (due to a parse error,
32972 * for example) then the mapping is tried again with another value.
32974 * This allows a robust 'fall back to defaults' behaviour to be
32975 * implemented somewhat automatically.
32977 * The first value that is tried is the user's setting for the key. If
32978 * the mapping function fails to map this value, other values may be
32979 * tried in an unspecified order (system or site defaults, translated
32980 * schema default values, untranslated schema default values, etc).
32982 * If the mapping function fails for all possible values, one additional
32983 * attempt is made: the mapping function is called with a %NULL value.
32984 * If the mapping function still indicates failure at this point then
32985 * the application will be aborted.
32987 * The result parameter for the @mapping function is pointed to a
32988 * #gpointer which is initially set to %NULL. The same pointer is given
32989 * to each invocation of @mapping. The final value of that #gpointer is
32990 * what is returned by this function. %NULL is valid; it is returned
32991 * just as any other value would be.
32993 * Returns: (transfer full): the result, which may be %NULL
32998 * g_settings_get_range:
32999 * @settings: a #GSettings
33000 * @key: the key to query the range of
33002 * Queries the range of a key.
33005 * Deprecated: 2.40: Use g_settings_schema_key_get_range() instead.
33010 * g_settings_get_string:
33011 * @settings: a #GSettings object
33012 * @key: the key to get the value for
33014 * Gets the value that is stored at @key in @settings.
33016 * A convenience variant of g_settings_get() for strings.
33018 * It is a programmer error to give a @key that isn't specified as
33019 * having a string type in the schema for @settings.
33021 * Returns: a newly-allocated string
33027 * g_settings_get_strv:
33028 * @settings: a #GSettings object
33029 * @key: the key to get the value for
33031 * A convenience variant of g_settings_get() for string arrays.
33033 * It is a programmer error to give a @key that isn't specified as
33034 * having an array of strings type in the schema for @settings.
33036 * Returns: (array zero-terminated=1) (transfer full): a
33037 * newly-allocated, %NULL-terminated array of strings, the value that
33038 * is stored at @key in @settings.
33044 * g_settings_get_uint:
33045 * @settings: a #GSettings object
33046 * @key: the key to get the value for
33048 * Gets the value that is stored at @key in @settings.
33050 * A convenience variant of g_settings_get() for 32-bit unsigned
33053 * It is a programmer error to give a @key that isn't specified as
33054 * having a uint32 type in the schema for @settings.
33056 * Returns: an unsigned integer
33062 * g_settings_get_uint64:
33063 * @settings: a #GSettings object
33064 * @key: the key to get the value for
33066 * Gets the value that is stored at @key in @settings.
33068 * A convenience variant of g_settings_get() for 64-bit unsigned
33071 * It is a programmer error to give a @key that isn't specified as
33072 * having a uint64 type in the schema for @settings.
33074 * Returns: a 64-bit unsigned integer
33080 * g_settings_get_user_value:
33081 * @settings: a #GSettings object
33082 * @key: the key to get the user value for
33084 * Checks the "user value" of a key, if there is one.
33086 * The user value of a key is the last value that was set by the user.
33088 * After calling g_settings_reset() this function should always return
33089 * %NULL (assuming something is not wrong with the system
33092 * It is possible that g_settings_get_value() will return a different
33093 * value than this function. This can happen in the case that the user
33094 * set a value for a key that was subsequently locked down by the system
33095 * administrator -- this function will return the user's old value.
33097 * This function may be useful for adding a "reset" option to a UI or
33098 * for providing indication that a particular value has been changed.
33100 * It is a programmer error to give a @key that isn't contained in the
33101 * schema for @settings.
33103 * Returns: (allow-none) (transfer full): the user's value, if set
33109 * g_settings_get_value:
33110 * @settings: a #GSettings object
33111 * @key: the key to get the value for
33113 * Gets the value that is stored in @settings for @key.
33115 * It is a programmer error to give a @key that isn't contained in the
33116 * schema for @settings.
33118 * Returns: a new #GVariant
33124 * g_settings_is_writable:
33125 * @settings: a #GSettings object
33126 * @name: the name of a key
33128 * Finds out if a key can be written or not
33130 * Returns: %TRUE if the key @name is writable
33136 * g_settings_list_children:
33137 * @settings: a #GSettings object
33139 * Gets the list of children on @settings.
33141 * The list is exactly the list of strings for which it is not an error
33142 * to call g_settings_get_child().
33144 * For GSettings objects that are lists, this value can change at any
33145 * time and you should connect to the "children-changed" signal to watch
33146 * for those changes. Note that there is a race condition here: you may
33147 * request a child after listing it only for it to have been destroyed
33148 * in the meantime. For this reason, g_settings_get_child() may return
33149 * %NULL even for a child that was listed by this function.
33151 * For GSettings objects that are not lists, you should probably not be
33152 * calling this function from "normal" code (since you should already
33153 * know what children are in your schema). This function may still be
33154 * useful there for introspection reasons, however.
33156 * You should free the return value with g_strfreev() when you are done
33159 * Returns: (transfer full) (element-type utf8): a list of the children on @settings
33164 * g_settings_list_keys:
33165 * @settings: a #GSettings object
33167 * Introspects the list of keys on @settings.
33169 * You should probably not be calling this function from "normal" code
33170 * (since you should already know what keys are in your schema). This
33171 * function is intended for introspection reasons.
33173 * You should free the return value with g_strfreev() when you are done
33176 * Returns: (transfer full) (element-type utf8): a list of the keys on @settings
33181 * g_settings_list_relocatable_schemas:
33185 * Returns: (element-type utf8) (transfer none): a list of relocatable
33186 * #GSettings schemas that are available. The list must not be
33187 * modified or freed.
33189 * Deprecated: 2.40: Use g_settings_schema_source_list_schemas() instead
33194 * g_settings_list_schemas:
33198 * Returns: (element-type utf8) (transfer none): a list of #GSettings
33199 * schemas that are available. The list must not be modified or
33202 * Deprecated: 2.40: Use g_settings_schema_source_list_schemas() instead.
33203 * If you used g_settings_list_schemas() to check for the presence of
33204 * a particular schema, use g_settings_schema_source_lookup() instead
33205 * of your whole loop.
33211 * @schema_id: the id of the schema
33213 * Creates a new #GSettings object with the schema specified by
33216 * Signals on the newly created #GSettings object will be dispatched
33217 * via the thread-default #GMainContext in effect at the time of the
33218 * call to g_settings_new(). The new #GSettings will hold a reference
33219 * on the context. See g_main_context_push_thread_default().
33221 * Returns: a new #GSettings object
33227 * g_settings_new_full:
33228 * @schema: a #GSettingsSchema
33229 * @backend: (allow-none): a #GSettingsBackend
33230 * @path: (allow-none): the path to use
33232 * Creates a new #GSettings object with a given schema, backend and
33235 * It should be extremely rare that you ever want to use this function.
33236 * It is made available for advanced use-cases (such as plugin systems
33237 * that want to provide access to schemas loaded from custom locations,
33240 * At the most basic level, a #GSettings object is a pure composition of
33241 * 4 things: a #GSettingsSchema, a #GSettingsBackend, a path within that
33242 * backend, and a #GMainContext to which signals are dispatched.
33244 * This constructor therefore gives you full control over constructing
33245 * #GSettings instances. The first 3 parameters are given directly as
33246 * @schema, @backend and @path, and the main context is taken from the
33247 * thread-default (as per g_settings_new()).
33249 * If @backend is %NULL then the default backend is used.
33251 * If @path is %NULL then the path from the schema is used. It is an
33252 * error if @path is %NULL and the schema has no path of its own or if
33253 * @path is non-%NULL and not equal to the path that the schema does
33256 * Returns: a new #GSettings object
33262 * g_settings_new_with_backend:
33263 * @schema_id: the id of the schema
33264 * @backend: the #GSettingsBackend to use
33266 * Creates a new #GSettings object with the schema specified by
33267 * @schema_id and a given #GSettingsBackend.
33269 * Creating a #GSettings object with a different backend allows accessing
33270 * settings from a database other than the usual one. For example, it may make
33271 * sense to pass a backend corresponding to the "defaults" settings database on
33272 * the system to get a settings object that modifies the system default
33273 * settings instead of the settings for this user.
33275 * Returns: a new #GSettings object
33281 * g_settings_new_with_backend_and_path:
33282 * @schema_id: the id of the schema
33283 * @backend: the #GSettingsBackend to use
33284 * @path: the path to use
33286 * Creates a new #GSettings object with the schema specified by
33287 * @schema_id and a given #GSettingsBackend and path.
33289 * This is a mix of g_settings_new_with_backend() and
33290 * g_settings_new_with_path().
33292 * Returns: a new #GSettings object
33298 * g_settings_new_with_path:
33299 * @schema_id: the id of the schema
33300 * @path: the path to use
33302 * Creates a new #GSettings object with the relocatable schema specified
33303 * by @schema_id and a given path.
33305 * You only need to do this if you want to directly create a settings
33306 * object with a schema that doesn't have a specified path of its own.
33307 * That's quite rare.
33309 * It is a programmer error to call this function for a schema that
33310 * has an explicitly specified path.
33312 * It is a programmer error if @path is not a valid path. A valid path
33313 * begins and ends with '/' and does not contain two consecutive '/'
33316 * Returns: a new #GSettings object
33322 * g_settings_range_check:
33323 * @settings: a #GSettings
33324 * @key: the key to check
33325 * @value: the value to check
33327 * Checks if the given @value is of the correct type and within the
33328 * permitted range for @key.
33330 * Returns: %TRUE if @value is valid for @key
33332 * Deprecated: 2.40: Use g_settings_schema_key_range_check() instead.
33337 * g_settings_reset:
33338 * @settings: a #GSettings object
33339 * @key: the name of a key
33341 * Resets @key to its default value.
33343 * This call resets the key, as much as possible, to its default value.
33344 * That might the value specified in the schema or the one set by the
33350 * g_settings_revert:
33351 * @settings: a #GSettings instance
33353 * Reverts all non-applied changes to the settings. This function
33354 * does nothing unless @settings is in 'delay-apply' mode; see
33355 * g_settings_delay(). In the normal case settings are always applied
33358 * Change notifications will be emitted for affected keys.
33363 * g_settings_schema_get_id:
33364 * @schema: a #GSettingsSchema
33366 * Get the ID of @schema.
33368 * Returns: (transfer none): the ID
33373 * g_settings_schema_get_key:
33374 * @schema: a #GSettingsSchema
33375 * @name: the name of a key
33377 * Gets the key named @name from @schema.
33379 * It is a programmer error to request a key that does not exist. See
33380 * g_settings_schema_list_keys().
33382 * Returns: (transfer full): the #GSettingsSchemaKey for @name
33388 * g_settings_schema_get_path:
33389 * @schema: a #GSettingsSchema
33391 * Gets the path associated with @schema, or %NULL.
33393 * Schemas may be single-instance or relocatable. Single-instance
33394 * schemas correspond to exactly one set of keys in the backend
33395 * database: those located at the path returned by this function.
33397 * Relocatable schemas can be referenced by other schemas and can
33398 * threfore describe multiple sets of keys at different locations. For
33399 * relocatable schemas, this function will return %NULL.
33401 * Returns: (transfer none): the path of the schema, or %NULL
33407 * g_settings_schema_has_key:
33408 * @schema: a #GSettingsSchema
33409 * @name: the name of a key
33411 * Checks if @schema has a key named @name.
33413 * Returns: %TRUE if such a key exists
33419 * g_settings_schema_key_get_default_value:
33420 * @key: a #GSettingsSchemaKey
33422 * Gets the default value for @key.
33424 * Note that this is the default value according to the schema. System
33425 * administrator defaults and lockdown are not visible via this API.
33427 * Returns: (transfer full): the default value for the key
33433 * g_settings_schema_key_get_description:
33434 * @key: a #GSettingsSchemaKey
33436 * Gets the description for @key.
33438 * If no description has been provided in the schema for @key, returns
33441 * The description can be one sentence to several paragraphs in length.
33442 * Paragraphs are delimited with a double newline. Descriptions can be
33443 * translated and the value returned from this function is is the
33446 * This function is slow. The summary and description information for
33447 * the schemas is not stored in the compiled schema database so this
33448 * function has to parse all of the source XML files in the schema
33451 * Returns: the description for @key, or %NULL
33457 * g_settings_schema_key_get_name:
33458 * @key: a #GSettingsSchemaKey
33460 * Gets the name of @key.
33462 * Returns: the name of @key.
33468 * g_settings_schema_key_get_range:
33469 * @key: a #GSettingsSchemaKey
33471 * Queries the range of a key.
33473 * This function will return a #GVariant that fully describes the range
33474 * of values that are valid for @key.
33476 * The type of #GVariant returned is `(sv)`. The string describes
33477 * the type of range restriction in effect. The type and meaning of
33478 * the value contained in the variant depends on the string.
33480 * If the string is `'type'` then the variant contains an empty array.
33481 * The element type of that empty array is the expected type of value
33482 * and all values of that type are valid.
33484 * If the string is `'enum'` then the variant contains an array
33485 * enumerating the possible values. Each item in the array is
33486 * a possible valid value and no other values are valid.
33488 * If the string is `'flags'` then the variant contains an array. Each
33489 * item in the array is a value that may appear zero or one times in an
33490 * array to be used as the value for this key. For example, if the
33491 * variant contained the array `['x', 'y']` then the valid values for
33492 * the key would be `[]`, `['x']`, `['y']`, `['x', 'y']` and
33495 * Finally, if the string is `'range'` then the variant contains a pair
33496 * of like-typed values -- the minimum and maximum permissible values
33499 * This information should not be used by normal programs. It is
33500 * considered to be a hint for introspection purposes. Normal programs
33501 * should already know what is permitted by their own schema. The
33502 * format may change in any way in the future -- but particularly, new
33503 * forms may be added to the possibilities described above.
33505 * You should free the returned value with g_variant_unref() when it is
33506 * no longer needed.
33508 * Returns: (transfer full): a #GVariant describing the range
33514 * g_settings_schema_key_get_summary:
33515 * @key: a #GSettingsSchemaKey
33517 * Gets the summary for @key.
33519 * If no summary has been provided in the schema for @key, returns
33522 * The summary is a short description of the purpose of the key; usually
33523 * one short sentence. Summaries can be translated and the value
33524 * returned from this function is is the current locale.
33526 * This function is slow. The summary and description information for
33527 * the schemas is not stored in the compiled schema database so this
33528 * function has to parse all of the source XML files in the schema
33531 * Returns: the summary for @key, or %NULL
33537 * g_settings_schema_key_get_value_type:
33538 * @key: a #GSettingsSchemaKey
33540 * Gets the #GVariantType of @key.
33542 * Returns: (transfer none): the type of @key
33548 * g_settings_schema_key_range_check:
33549 * @key: a #GSettingsSchemaKey
33550 * @value: the value to check
33552 * Checks if the given @value is of the correct type and within the
33553 * permitted range for @key.
33555 * It is a programmer error if @value is not of the correct type -- you
33556 * must check for this first.
33558 * Returns: %TRUE if @value is valid for @key
33564 * g_settings_schema_key_ref:
33565 * @key: a #GSettingsSchemaKey
33567 * Increase the reference count of @key, returning a new reference.
33569 * Returns: a new reference to @key
33575 * g_settings_schema_key_unref:
33576 * @key: a #GSettingsSchemaKey
33578 * Decrease the reference count of @key, possibly freeing it.
33585 * g_settings_schema_list_children:
33586 * @schema: a #GSettingsSchema
33588 * Gets the list of children in @schema.
33590 * You should free the return value with g_strfreev() when you are done
33593 * Returns: (transfer full) (element-type utf8): a list of the children on @settings
33599 * g_settings_schema_list_keys:
33600 * @schema: a #GSettingsSchema
33602 * Introspects the list of keys on @schema.
33604 * You should probably not be calling this function from "normal" code
33605 * (since you should already know what keys are in your schema). This
33606 * function is intended for introspection reasons.
33608 * Returns: (transfer full) (element-type utf8): a list of the keys on
33615 * g_settings_schema_ref:
33616 * @schema: a #GSettingsSchema
33618 * Increase the reference count of @schema, returning a new reference.
33620 * Returns: a new reference to @schema
33626 * g_settings_schema_source_get_default:
33628 * Gets the default system schema source.
33630 * This function is not required for normal uses of #GSettings but it
33631 * may be useful to authors of plugin management systems or to those who
33632 * want to introspect the content of schemas.
33634 * If no schemas are installed, %NULL will be returned.
33636 * The returned source may actually consist of multiple schema sources
33637 * from different directories, depending on which directories were given
33638 * in `XDG_DATA_DIRS` and `GSETTINGS_SCHEMA_DIR`. For this reason, all
33639 * lookups performed against the default source should probably be done
33642 * Returns: (transfer none): the default schema source
33648 * g_settings_schema_source_list_schemas:
33649 * @source: a #GSettingsSchemaSource
33650 * @recursive: if we should recurse
33651 * @non_relocatable: (out) (transfer full) (array zero-terminated=1): the
33652 * list of non-relocatable schemas
33653 * @relocatable: (out) (transfer full) (array zero-terminated=1): the list
33654 * of relocatable schemas
33656 * Lists the schemas in a given source.
33658 * If @recursive is %TRUE then include parent sources. If %FALSE then
33659 * only include the schemas from one source (ie: one directory). You
33660 * probably want %TRUE.
33662 * Non-relocatable schemas are those for which you can call
33663 * g_settings_new(). Relocatable schemas are those for which you must
33664 * use g_settings_new_with_path().
33666 * Do not call this function from normal programs. This is designed for
33667 * use by database editors, commandline tools, etc.
33674 * g_settings_schema_source_lookup:
33675 * @source: a #GSettingsSchemaSource
33676 * @schema_id: a schema ID
33677 * @recursive: %TRUE if the lookup should be recursive
33679 * Looks up a schema with the identifier @schema_id in @source.
33681 * This function is not required for normal uses of #GSettings but it
33682 * may be useful to authors of plugin management systems or to those who
33683 * want to introspect the content of schemas.
33685 * If the schema isn't found directly in @source and @recursive is %TRUE
33686 * then the parent sources will also be checked.
33688 * If the schema isn't found, %NULL is returned.
33690 * Returns: (nullable) (transfer full): a new #GSettingsSchema
33696 * g_settings_schema_source_new_from_directory:
33697 * @directory: (type filename): the filename of a directory
33698 * @parent: (allow-none): a #GSettingsSchemaSource, or %NULL
33699 * @trusted: %TRUE, if the directory is trusted
33700 * @error: a pointer to a #GError pointer set to %NULL, or %NULL
33702 * Attempts to create a new schema source corresponding to the contents
33703 * of the given directory.
33705 * This function is not required for normal uses of #GSettings but it
33706 * may be useful to authors of plugin management systems.
33708 * The directory should contain a file called `gschemas.compiled` as
33709 * produced by the [glib-compile-schemas][glib-compile-schemas] tool.
33711 * If @trusted is %TRUE then `gschemas.compiled` is trusted not to be
33712 * corrupted. This assumption has a performance advantage, but can result
33713 * in crashes or inconsistent behaviour in the case of a corrupted file.
33714 * Generally, you should set @trusted to %TRUE for files installed by the
33715 * system and to %FALSE for files in the home directory.
33717 * If @parent is non-%NULL then there are two effects.
33719 * First, if g_settings_schema_source_lookup() is called with the
33720 * @recursive flag set to %TRUE and the schema can not be found in the
33721 * source, the lookup will recurse to the parent.
33723 * Second, any references to other schemas specified within this
33724 * source (ie: `child` or `extends`) references may be resolved
33725 * from the @parent.
33727 * For this second reason, except in very unusual situations, the
33728 * @parent should probably be given as the default schema source, as
33729 * returned by g_settings_schema_source_get_default().
33736 * g_settings_schema_source_ref:
33737 * @source: a #GSettingsSchemaSource
33739 * Increase the reference count of @source, returning a new reference.
33741 * Returns: a new reference to @source
33747 * g_settings_schema_source_unref:
33748 * @source: a #GSettingsSchemaSource
33750 * Decrease the reference count of @source, possibly freeing it.
33757 * g_settings_schema_unref:
33758 * @schema: a #GSettingsSchema
33760 * Decrease the reference count of @schema, possibly freeing it.
33768 * @settings: a #GSettings object
33769 * @key: the name of the key to set
33770 * @format: a #GVariant format string
33771 * @...: arguments as per @format
33773 * Sets @key in @settings to @value.
33775 * A convenience function that combines g_settings_set_value() with
33778 * It is a programmer error to give a @key that isn't contained in the
33779 * schema for @settings or for the #GVariantType of @format to mismatch
33780 * the type given in the schema.
33782 * Returns: %TRUE if setting the key succeeded,
33783 * %FALSE if the key was not writable
33789 * g_settings_set_boolean:
33790 * @settings: a #GSettings object
33791 * @key: the name of the key to set
33792 * @value: the value to set it to
33794 * Sets @key in @settings to @value.
33796 * A convenience variant of g_settings_set() for booleans.
33798 * It is a programmer error to give a @key that isn't specified as
33799 * having a boolean type in the schema for @settings.
33801 * Returns: %TRUE if setting the key succeeded,
33802 * %FALSE if the key was not writable
33808 * g_settings_set_double:
33809 * @settings: a #GSettings object
33810 * @key: the name of the key to set
33811 * @value: the value to set it to
33813 * Sets @key in @settings to @value.
33815 * A convenience variant of g_settings_set() for doubles.
33817 * It is a programmer error to give a @key that isn't specified as
33818 * having a 'double' type in the schema for @settings.
33820 * Returns: %TRUE if setting the key succeeded,
33821 * %FALSE if the key was not writable
33827 * g_settings_set_enum:
33828 * @settings: a #GSettings object
33829 * @key: a key, within @settings
33830 * @value: an enumerated value
33832 * Looks up the enumerated type nick for @value and writes it to @key,
33833 * within @settings.
33835 * It is a programmer error to give a @key that isn't contained in the
33836 * schema for @settings or is not marked as an enumerated type, or for
33837 * @value not to be a valid value for the named type.
33839 * After performing the write, accessing @key directly with
33840 * g_settings_get_string() will return the 'nick' associated with
33843 * Returns: %TRUE, if the set succeeds
33848 * g_settings_set_flags:
33849 * @settings: a #GSettings object
33850 * @key: a key, within @settings
33851 * @value: a flags value
33853 * Looks up the flags type nicks for the bits specified by @value, puts
33854 * them in an array of strings and writes the array to @key, within
33857 * It is a programmer error to give a @key that isn't contained in the
33858 * schema for @settings or is not marked as a flags type, or for @value
33859 * to contain any bits that are not value for the named type.
33861 * After performing the write, accessing @key directly with
33862 * g_settings_get_strv() will return an array of 'nicks'; one for each
33865 * Returns: %TRUE, if the set succeeds
33870 * g_settings_set_int:
33871 * @settings: a #GSettings object
33872 * @key: the name of the key to set
33873 * @value: the value to set it to
33875 * Sets @key in @settings to @value.
33877 * A convenience variant of g_settings_set() for 32-bit integers.
33879 * It is a programmer error to give a @key that isn't specified as
33880 * having a int32 type in the schema for @settings.
33882 * Returns: %TRUE if setting the key succeeded,
33883 * %FALSE if the key was not writable
33889 * g_settings_set_int64:
33890 * @settings: a #GSettings object
33891 * @key: the name of the key to set
33892 * @value: the value to set it to
33894 * Sets @key in @settings to @value.
33896 * A convenience variant of g_settings_set() for 64-bit integers.
33898 * It is a programmer error to give a @key that isn't specified as
33899 * having a int64 type in the schema for @settings.
33901 * Returns: %TRUE if setting the key succeeded,
33902 * %FALSE if the key was not writable
33908 * g_settings_set_string:
33909 * @settings: a #GSettings object
33910 * @key: the name of the key to set
33911 * @value: the value to set it to
33913 * Sets @key in @settings to @value.
33915 * A convenience variant of g_settings_set() for strings.
33917 * It is a programmer error to give a @key that isn't specified as
33918 * having a string type in the schema for @settings.
33920 * Returns: %TRUE if setting the key succeeded,
33921 * %FALSE if the key was not writable
33927 * g_settings_set_strv:
33928 * @settings: a #GSettings object
33929 * @key: the name of the key to set
33930 * @value: (allow-none) (array zero-terminated=1): the value to set it to, or %NULL
33932 * Sets @key in @settings to @value.
33934 * A convenience variant of g_settings_set() for string arrays. If
33935 * @value is %NULL, then @key is set to be the empty array.
33937 * It is a programmer error to give a @key that isn't specified as
33938 * having an array of strings type in the schema for @settings.
33940 * Returns: %TRUE if setting the key succeeded,
33941 * %FALSE if the key was not writable
33947 * g_settings_set_uint:
33948 * @settings: a #GSettings object
33949 * @key: the name of the key to set
33950 * @value: the value to set it to
33952 * Sets @key in @settings to @value.
33954 * A convenience variant of g_settings_set() for 32-bit unsigned
33957 * It is a programmer error to give a @key that isn't specified as
33958 * having a uint32 type in the schema for @settings.
33960 * Returns: %TRUE if setting the key succeeded,
33961 * %FALSE if the key was not writable
33967 * g_settings_set_uint64:
33968 * @settings: a #GSettings object
33969 * @key: the name of the key to set
33970 * @value: the value to set it to
33972 * Sets @key in @settings to @value.
33974 * A convenience variant of g_settings_set() for 64-bit unsigned
33977 * It is a programmer error to give a @key that isn't specified as
33978 * having a uint64 type in the schema for @settings.
33980 * Returns: %TRUE if setting the key succeeded,
33981 * %FALSE if the key was not writable
33987 * g_settings_set_value:
33988 * @settings: a #GSettings object
33989 * @key: the name of the key to set
33990 * @value: a #GVariant of the correct type
33992 * Sets @key in @settings to @value.
33994 * It is a programmer error to give a @key that isn't contained in the
33995 * schema for @settings or for @value to have the incorrect type, per
33998 * If @value is floating then this function consumes the reference.
34000 * Returns: %TRUE if setting the key succeeded,
34001 * %FALSE if the key was not writable
34009 * Ensures that all pending operations for the given are complete for
34010 * the default backend.
34012 * Writes made to a #GSettings are handled asynchronously. For this
34013 * reason, it is very unlikely that the changes have it to disk by the
34014 * time g_settings_set() returns.
34016 * This call will block until all of the writes have made it to the
34017 * backend. Since the mainloop is not running, no change notifications
34018 * will be dispatched during this call (but some may be queued by the
34019 * time the call is done).
34024 * g_settings_unbind:
34025 * @object: (type GObject.Object): the object
34026 * @property: the property whose binding is removed
34028 * Removes an existing binding for @property on @object.
34030 * Note that bindings are automatically removed when the
34031 * object is finalized, so it is rarely necessary to call this
34039 * g_simple_action_group_add_entries:
34040 * @simple: a #GSimpleActionGroup
34041 * @entries: (array length=n_entries): a pointer to the first item in
34042 * an array of #GActionEntry structs
34043 * @n_entries: the length of @entries, or -1
34044 * @user_data: the user data for signal connections
34046 * A convenience function for creating multiple #GSimpleAction instances
34047 * and adding them to the action group.
34050 * Deprecated: 2.38: Use g_action_map_add_action_entries()
34055 * g_simple_action_group_insert:
34056 * @simple: a #GSimpleActionGroup
34057 * @action: a #GAction
34059 * Adds an action to the action group.
34061 * If the action group already contains an action with the same name as
34062 * @action then the old action is dropped from the group.
34064 * The action group takes its own reference on @action.
34067 * Deprecated: 2.38: Use g_action_map_add_action()
34072 * g_simple_action_group_lookup:
34073 * @simple: a #GSimpleActionGroup
34074 * @action_name: the name of an action
34076 * Looks up the action with the name @action_name in the group.
34078 * If no such action exists, returns %NULL.
34080 * Returns: (transfer none): a #GAction, or %NULL
34082 * Deprecated: 2.38: Use g_action_map_lookup_action()
34087 * g_simple_action_group_new:
34089 * Creates a new, empty, #GSimpleActionGroup.
34091 * Returns: a new #GSimpleActionGroup
34097 * g_simple_action_group_remove:
34098 * @simple: a #GSimpleActionGroup
34099 * @action_name: the name of the action
34101 * Removes the named action from the action group.
34103 * If no action of this name is in the group then nothing happens.
34106 * Deprecated: 2.38: Use g_action_map_remove_action()
34111 * g_simple_action_new:
34112 * @name: the name of the action
34113 * @parameter_type: (allow-none): the type of parameter to the activate function
34115 * Creates a new action.
34117 * The created action is stateless. See g_simple_action_new_stateful().
34119 * Returns: a new #GSimpleAction
34125 * g_simple_action_new_stateful:
34126 * @name: the name of the action
34127 * @parameter_type: (allow-none): the type of the parameter to the activate function
34128 * @state: the initial state of the action
34130 * Creates a new stateful action.
34132 * @state is the initial state of the action. All future state values
34133 * must have the same #GVariantType as the initial state.
34135 * If the @state GVariant is floating, it is consumed.
34137 * Returns: a new #GSimpleAction
34143 * g_simple_action_set_enabled:
34144 * @simple: a #GSimpleAction
34145 * @enabled: whether the action is enabled
34147 * Sets the action as enabled or not.
34149 * An action must be enabled in order to be activated or in order to
34150 * have its state changed from outside callers.
34152 * This should only be called by the implementor of the action. Users
34153 * of the action should not attempt to modify its enabled flag.
34160 * g_simple_action_set_state:
34161 * @simple: a #GSimpleAction
34162 * @value: the new #GVariant for the state
34164 * Sets the state of the action.
34166 * This directly updates the 'state' property to the given value.
34168 * This should only be called by the implementor of the action. Users
34169 * of the action should not attempt to directly modify the 'state'
34170 * property. Instead, they should call g_action_change_state() to
34171 * request the change.
34173 * If the @value GVariant is floating, it is consumed.
34180 * g_simple_action_set_state_hint:
34181 * @simple: a #GSimpleAction
34182 * @state_hint: (allow-none): a #GVariant representing the state hint
34184 * Sets the state hint for the action.
34186 * See g_action_get_state_hint() for more information about
34187 * action state hints.
34194 * g_simple_async_report_error_in_idle: (skip)
34195 * @object: (allow-none): a #GObject, or %NULL.
34196 * @callback: a #GAsyncReadyCallback.
34197 * @user_data: user data passed to @callback.
34198 * @domain: a #GQuark containing the error domain (usually #G_IO_ERROR).
34199 * @code: a specific error code.
34200 * @format: a formatted error reporting string.
34201 * @...: a list of variables to fill in @format.
34203 * Reports an error in an asynchronous function in an idle function by
34204 * directly setting the contents of the #GAsyncResult with the given error
34207 * Deprecated: 2.46: Use g_task_report_error().
34212 * g_simple_async_report_gerror_in_idle:
34213 * @object: (allow-none): a #GObject, or %NULL
34214 * @callback: (scope async): a #GAsyncReadyCallback.
34215 * @user_data: (closure): user data passed to @callback.
34216 * @error: the #GError to report
34218 * Reports an error in an idle function. Similar to
34219 * g_simple_async_report_error_in_idle(), but takes a #GError rather
34220 * than building a new one.
34222 * Deprecated: 2.46: Use g_task_report_error().
34227 * g_simple_async_report_take_gerror_in_idle: (skip)
34228 * @object: (allow-none): a #GObject, or %NULL
34229 * @callback: a #GAsyncReadyCallback.
34230 * @user_data: user data passed to @callback.
34231 * @error: the #GError to report
34233 * Reports an error in an idle function. Similar to
34234 * g_simple_async_report_gerror_in_idle(), but takes over the caller's
34235 * ownership of @error, so the caller does not have to free it any more.
34238 * Deprecated: 2.46: Use g_task_report_error().
34243 * g_simple_async_result_complete:
34244 * @simple: a #GSimpleAsyncResult.
34246 * Completes an asynchronous I/O job immediately. Must be called in
34247 * the thread where the asynchronous result was to be delivered, as it
34248 * invokes the callback directly. If you are in a different thread use
34249 * g_simple_async_result_complete_in_idle().
34251 * Calling this function takes a reference to @simple for as long as
34252 * is needed to complete the call.
34254 * Deprecated: 2.46: Use #GTask instead.
34259 * g_simple_async_result_complete_in_idle:
34260 * @simple: a #GSimpleAsyncResult.
34262 * Completes an asynchronous function in an idle handler in the
34263 * [thread-default main context][g-main-context-push-thread-default]
34264 * of the thread that @simple was initially created in
34265 * (and re-pushes that context around the invocation of the callback).
34267 * Calling this function takes a reference to @simple for as long as
34268 * is needed to complete the call.
34270 * Deprecated: 2.46: Use #GTask instead.
34275 * g_simple_async_result_get_op_res_gboolean:
34276 * @simple: a #GSimpleAsyncResult.
34278 * Gets the operation result boolean from within the asynchronous result.
34280 * Returns: %TRUE if the operation's result was %TRUE, %FALSE
34281 * if the operation's result was %FALSE.
34282 * Deprecated: 2.46: Use #GTask and g_task_propagate_boolean() instead.
34287 * g_simple_async_result_get_op_res_gpointer: (skip)
34288 * @simple: a #GSimpleAsyncResult.
34290 * Gets a pointer result as returned by the asynchronous function.
34292 * Returns: a pointer from the result.
34293 * Deprecated: 2.46: Use #GTask and g_task_propagate_pointer() instead.
34298 * g_simple_async_result_get_op_res_gssize:
34299 * @simple: a #GSimpleAsyncResult.
34301 * Gets a gssize from the asynchronous result.
34303 * Returns: a gssize returned from the asynchronous function.
34304 * Deprecated: 2.46: Use #GTask and g_task_propagate_int() instead.
34309 * g_simple_async_result_get_source_tag: (skip)
34310 * @simple: a #GSimpleAsyncResult.
34312 * Gets the source tag for the #GSimpleAsyncResult.
34314 * Returns: a #gpointer to the source object for the #GSimpleAsyncResult.
34315 * Deprecated: 2.46.: Use #GTask and g_task_get_source_tag() instead.
34320 * g_simple_async_result_is_valid:
34321 * @result: the #GAsyncResult passed to the _finish function.
34322 * @source: (allow-none): the #GObject passed to the _finish function.
34323 * @source_tag: (allow-none): the asynchronous function.
34325 * Ensures that the data passed to the _finish function of an async
34326 * operation is consistent. Three checks are performed.
34328 * First, @result is checked to ensure that it is really a
34329 * #GSimpleAsyncResult. Second, @source is checked to ensure that it
34330 * matches the source object of @result. Third, @source_tag is
34331 * checked to ensure that it is equal to the @source_tag argument given
34332 * to g_simple_async_result_new() (which, by convention, is a pointer
34333 * to the _async function corresponding to the _finish function from
34334 * which this function is called). (Alternatively, if either
34335 * @source_tag or @result's source tag is %NULL, then the source tag
34336 * check is skipped.)
34338 * Returns: #TRUE if all checks passed or #FALSE if any failed.
34340 * Deprecated: 2.46: Use #GTask and g_task_is_valid() instead.
34345 * g_simple_async_result_new:
34346 * @source_object: (allow-none): a #GObject, or %NULL.
34347 * @callback: (scope async): a #GAsyncReadyCallback.
34348 * @user_data: (closure): user data passed to @callback.
34349 * @source_tag: the asynchronous function.
34351 * Creates a #GSimpleAsyncResult.
34353 * The common convention is to create the #GSimpleAsyncResult in the
34354 * function that starts the asynchronous operation and use that same
34355 * function as the @source_tag.
34357 * If your operation supports cancellation with #GCancellable (which it
34358 * probably should) then you should provide the user's cancellable to
34359 * g_simple_async_result_set_check_cancellable() immediately after
34360 * this function returns.
34362 * Returns: a #GSimpleAsyncResult.
34363 * Deprecated: 2.46: Use g_task_new() instead.
34368 * g_simple_async_result_new_error:
34369 * @source_object: (allow-none): a #GObject, or %NULL.
34370 * @callback: (scope async): a #GAsyncReadyCallback.
34371 * @user_data: (closure): user data passed to @callback.
34372 * @domain: a #GQuark.
34373 * @code: an error code.
34374 * @format: a string with format characters.
34375 * @...: a list of values to insert into @format.
34377 * Creates a new #GSimpleAsyncResult with a set error.
34379 * Returns: a #GSimpleAsyncResult.
34380 * Deprecated: 2.46: Use g_task_new() and g_task_return_new_error() instead.
34385 * g_simple_async_result_new_from_error:
34386 * @source_object: (allow-none): a #GObject, or %NULL.
34387 * @callback: (scope async): a #GAsyncReadyCallback.
34388 * @user_data: (closure): user data passed to @callback.
34389 * @error: a #GError
34391 * Creates a #GSimpleAsyncResult from an error condition.
34393 * Returns: a #GSimpleAsyncResult.
34394 * Deprecated: 2.46: Use g_task_new() and g_task_return_error() instead.
34399 * g_simple_async_result_new_take_error: (skip)
34400 * @source_object: (allow-none): a #GObject, or %NULL
34401 * @callback: (scope async): a #GAsyncReadyCallback
34402 * @user_data: (closure): user data passed to @callback
34403 * @error: a #GError
34405 * Creates a #GSimpleAsyncResult from an error condition, and takes over the
34406 * caller's ownership of @error, so the caller does not need to free it anymore.
34408 * Returns: a #GSimpleAsyncResult
34410 * Deprecated: 2.46: Use g_task_new() and g_task_return_error() instead.
34415 * g_simple_async_result_propagate_error:
34416 * @simple: a #GSimpleAsyncResult.
34417 * @dest: (out): a location to propagate the error to.
34419 * Propagates an error from within the simple asynchronous result to
34420 * a given destination.
34422 * If the #GCancellable given to a prior call to
34423 * g_simple_async_result_set_check_cancellable() is cancelled then this
34424 * function will return %TRUE with @dest set appropriately.
34426 * Returns: %TRUE if the error was propagated to @dest. %FALSE otherwise.
34427 * Deprecated: 2.46: Use #GTask instead.
34432 * g_simple_async_result_run_in_thread: (skip)
34433 * @simple: a #GSimpleAsyncResult.
34434 * @func: a #GSimpleAsyncThreadFunc.
34435 * @io_priority: the io priority of the request.
34436 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
34438 * Runs the asynchronous job in a separate thread and then calls
34439 * g_simple_async_result_complete_in_idle() on @simple to return
34440 * the result to the appropriate main loop.
34442 * Calling this function takes a reference to @simple for as long as
34443 * is needed to run the job and report its completion.
34445 * Deprecated: 2.46: Use #GTask and g_task_run_in_thread() instead.
34450 * g_simple_async_result_set_check_cancellable:
34451 * @simple: a #GSimpleAsyncResult
34452 * @check_cancellable: (allow-none): a #GCancellable to check, or %NULL to unset
34454 * Sets a #GCancellable to check before dispatching results.
34456 * This function has one very specific purpose: the provided cancellable
34457 * is checked at the time of g_simple_async_result_propagate_error() If
34458 * it is cancelled, these functions will return an "Operation was
34459 * cancelled" error (%G_IO_ERROR_CANCELLED).
34461 * Implementors of cancellable asynchronous functions should use this in
34462 * order to provide a guarantee to their callers that cancelling an
34463 * async operation will reliably result in an error being returned for
34464 * that operation (even if a positive result for the operation has
34465 * already been sent as an idle to the main context to be dispatched).
34467 * The checking described above is done regardless of any call to the
34468 * unrelated g_simple_async_result_set_handle_cancellation() function.
34471 * Deprecated: 2.46: Use #GTask instead.
34476 * g_simple_async_result_set_error: (skip)
34477 * @simple: a #GSimpleAsyncResult.
34478 * @domain: a #GQuark (usually #G_IO_ERROR).
34479 * @code: an error code.
34480 * @format: a formatted error reporting string.
34481 * @...: a list of variables to fill in @format.
34483 * Sets an error within the asynchronous result without a #GError.
34485 * Deprecated: 2.46: Use #GTask and g_task_return_new_error() instead.
34490 * g_simple_async_result_set_error_va: (skip)
34491 * @simple: a #GSimpleAsyncResult.
34492 * @domain: a #GQuark (usually #G_IO_ERROR).
34493 * @code: an error code.
34494 * @format: a formatted error reporting string.
34495 * @args: va_list of arguments.
34497 * Sets an error within the asynchronous result without a #GError.
34498 * Unless writing a binding, see g_simple_async_result_set_error().
34500 * Deprecated: 2.46: Use #GTask and g_task_return_error() instead.
34505 * g_simple_async_result_set_from_error:
34506 * @simple: a #GSimpleAsyncResult.
34509 * Sets the result from a #GError.
34511 * Deprecated: 2.46: Use #GTask and g_task_return_error() instead.
34516 * g_simple_async_result_set_handle_cancellation:
34517 * @simple: a #GSimpleAsyncResult.
34518 * @handle_cancellation: a #gboolean.
34520 * Sets whether to handle cancellation within the asynchronous operation.
34522 * This function has nothing to do with
34523 * g_simple_async_result_set_check_cancellable(). It only refers to the
34524 * #GCancellable passed to g_simple_async_result_run_in_thread().
34531 * g_simple_async_result_set_op_res_gboolean:
34532 * @simple: a #GSimpleAsyncResult.
34533 * @op_res: a #gboolean.
34535 * Sets the operation result to a boolean within the asynchronous result.
34537 * Deprecated: 2.46: Use #GTask and g_task_return_boolean() instead.
34542 * g_simple_async_result_set_op_res_gpointer: (skip)
34543 * @simple: a #GSimpleAsyncResult.
34544 * @op_res: a pointer result from an asynchronous function.
34545 * @destroy_op_res: a #GDestroyNotify function.
34547 * Sets the operation result within the asynchronous result to a pointer.
34549 * Deprecated: 2.46: Use #GTask and g_task_return_pointer() instead.
34554 * g_simple_async_result_set_op_res_gssize:
34555 * @simple: a #GSimpleAsyncResult.
34556 * @op_res: a #gssize.
34558 * Sets the operation result within the asynchronous result to
34559 * the given @op_res.
34561 * Deprecated: 2.46: Use #GTask and g_task_return_int() instead.
34566 * g_simple_async_result_take_error: (skip)
34567 * @simple: a #GSimpleAsyncResult
34568 * @error: a #GError
34570 * Sets the result from @error, and takes over the caller's ownership
34571 * of @error, so the caller does not need to free it any more.
34574 * Deprecated: 2.46: Use #GTask and g_task_return_error() instead.
34579 * g_simple_io_stream_new:
34580 * @input_stream: a #GInputStream.
34581 * @output_stream: a #GOutputStream.
34583 * Creates a new #GSimpleIOStream wrapping @input_stream and @output_stream.
34584 * See also #GIOStream.
34586 * Returns: a new #GSimpleIOStream instance.
34592 * g_simple_permission_new:
34593 * @allowed: %TRUE if the action is allowed
34595 * Creates a new #GPermission instance that represents an action that is
34596 * either always or never allowed.
34598 * Returns: the #GSimplePermission, as a #GPermission
34604 * g_simple_proxy_resolver_new:
34605 * @default_proxy: (allow-none): the default proxy to use, eg
34606 * "socks://192.168.1.1"
34607 * @ignore_hosts: (allow-none): an optional list of hosts/IP addresses
34608 * to not use a proxy for.
34610 * Creates a new #GSimpleProxyResolver. See
34611 * #GSimpleProxyResolver:default-proxy and
34612 * #GSimpleProxyResolver:ignore-hosts for more details on how the
34613 * arguments are interpreted.
34615 * Returns: (transfer full): a new #GSimpleProxyResolver
34621 * g_simple_proxy_resolver_set_default_proxy:
34622 * @resolver: a #GSimpleProxyResolver
34623 * @default_proxy: the default proxy to use
34625 * Sets the default proxy on @resolver, to be used for any URIs that
34626 * don't match #GSimpleProxyResolver:ignore-hosts or a proxy set
34627 * via g_simple_proxy_resolver_set_uri_proxy().
34629 * If @default_proxy starts with "socks://",
34630 * #GSimpleProxyResolver will treat it as referring to all three of
34631 * the socks5, socks4a, and socks4 proxy types.
34638 * g_simple_proxy_resolver_set_ignore_hosts:
34639 * @resolver: a #GSimpleProxyResolver
34640 * @ignore_hosts: %NULL-terminated list of hosts/IP addresses
34641 * to not use a proxy for
34643 * Sets the list of ignored hosts.
34645 * See #GSimpleProxyResolver:ignore-hosts for more details on how the
34646 * @ignore_hosts argument is interpreted.
34653 * g_simple_proxy_resolver_set_uri_proxy:
34654 * @resolver: a #GSimpleProxyResolver
34655 * @uri_scheme: the URI scheme to add a proxy for
34656 * @proxy: the proxy to use for @uri_scheme
34658 * Adds a URI-scheme-specific proxy to @resolver; URIs whose scheme
34659 * matches @uri_scheme (and which don't match
34660 * #GSimpleProxyResolver:ignore-hosts) will be proxied via @proxy.
34662 * As with #GSimpleProxyResolver:default-proxy, if @proxy starts with
34663 * "socks://", #GSimpleProxyResolver will treat it
34664 * as referring to all three of the socks5, socks4a, and socks4 proxy
34673 * @socket: a #GSocket.
34674 * @cancellable: (allow-none): a %GCancellable or %NULL
34675 * @error: #GError for error reporting, or %NULL to ignore.
34677 * Accept incoming connections on a connection-based socket. This removes
34678 * the first outstanding connection request from the listening socket and
34679 * creates a #GSocket object for it.
34681 * The @socket must be bound to a local address with g_socket_bind() and
34682 * must be listening for incoming connections (g_socket_listen()).
34684 * If there are no outstanding connections then the operation will block
34685 * or return %G_IO_ERROR_WOULD_BLOCK if non-blocking I/O is enabled.
34686 * To be notified of an incoming connection, wait for the %G_IO_IN condition.
34688 * Returns: (transfer full): a new #GSocket, or %NULL on error.
34689 * Free the returned object with g_object_unref().
34695 * g_socket_address_enumerator_next:
34696 * @enumerator: a #GSocketAddressEnumerator
34697 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
34698 * @error: a #GError.
34700 * Retrieves the next #GSocketAddress from @enumerator. Note that this
34701 * may block for some amount of time. (Eg, a #GNetworkAddress may need
34702 * to do a DNS lookup before it can return an address.) Use
34703 * g_socket_address_enumerator_next_async() if you need to avoid
34706 * If @enumerator is expected to yield addresses, but for some reason
34707 * is unable to (eg, because of a DNS error), then the first call to
34708 * g_socket_address_enumerator_next() will return an appropriate error
34709 * in *@error. However, if the first call to
34710 * g_socket_address_enumerator_next() succeeds, then any further
34711 * internal errors (other than @cancellable being triggered) will be
34714 * Returns: (transfer full): a #GSocketAddress (owned by the caller), or %NULL on
34715 * error (in which case *@error will be set) or if there are no
34721 * g_socket_address_enumerator_next_async:
34722 * @enumerator: a #GSocketAddressEnumerator
34723 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
34724 * @callback: (scope async): a #GAsyncReadyCallback to call when the request
34726 * @user_data: (closure): the data to pass to callback function
34728 * Asynchronously retrieves the next #GSocketAddress from @enumerator
34729 * and then calls @callback, which must call
34730 * g_socket_address_enumerator_next_finish() to get the result.
34735 * g_socket_address_enumerator_next_finish:
34736 * @enumerator: a #GSocketAddressEnumerator
34737 * @result: a #GAsyncResult
34738 * @error: a #GError
34740 * Retrieves the result of a completed call to
34741 * g_socket_address_enumerator_next_async(). See
34742 * g_socket_address_enumerator_next() for more information about
34745 * Returns: (transfer full): a #GSocketAddress (owned by the caller), or %NULL on
34746 * error (in which case *@error will be set) or if there are no
34752 * g_socket_address_get_family:
34753 * @address: a #GSocketAddress
34755 * Gets the socket family type of @address.
34757 * Returns: the socket family type of @address
34763 * g_socket_address_get_native_size:
34764 * @address: a #GSocketAddress
34766 * Gets the size of @address's native struct sockaddr.
34767 * You can use this to allocate memory to pass to
34768 * g_socket_address_to_native().
34770 * Returns: the size of the native struct sockaddr that
34771 * @address represents
34777 * g_socket_address_new_from_native:
34778 * @native: (not nullable): a pointer to a struct sockaddr
34779 * @len: the size of the memory location pointed to by @native
34781 * Creates a #GSocketAddress subclass corresponding to the native
34782 * struct sockaddr @native.
34784 * Returns: a new #GSocketAddress if @native could successfully
34785 * be converted, otherwise %NULL
34791 * g_socket_address_to_native:
34792 * @address: a #GSocketAddress
34793 * @dest: a pointer to a memory location that will contain the native
34795 * @destlen: the size of @dest. Must be at least as large as
34796 * g_socket_address_get_native_size()
34797 * @error: #GError for error reporting, or %NULL to ignore
34799 * Converts a #GSocketAddress to a native struct sockaddr, which can
34800 * be passed to low-level functions like connect() or bind().
34802 * If not enough space is available, a %G_IO_ERROR_NO_SPACE error
34803 * is returned. If the address type is not known on the system
34804 * then a %G_IO_ERROR_NOT_SUPPORTED error is returned.
34806 * Returns: %TRUE if @dest was filled in, %FALSE on error
34813 * @socket: a #GSocket.
34814 * @address: a #GSocketAddress specifying the local address.
34815 * @allow_reuse: whether to allow reusing this address
34816 * @error: #GError for error reporting, or %NULL to ignore.
34818 * When a socket is created it is attached to an address family, but it
34819 * doesn't have an address in this family. g_socket_bind() assigns the
34820 * address (sometimes called name) of the socket.
34822 * It is generally required to bind to a local address before you can
34823 * receive connections. (See g_socket_listen() and g_socket_accept() ).
34824 * In certain situations, you may also want to bind a socket that will be
34825 * used to initiate connections, though this is not normally required.
34827 * If @socket is a TCP socket, then @allow_reuse controls the setting
34828 * of the `SO_REUSEADDR` socket option; normally it should be %TRUE for
34829 * server sockets (sockets that you will eventually call
34830 * g_socket_accept() on), and %FALSE for client sockets. (Failing to
34831 * set this flag on a server socket may cause g_socket_bind() to return
34832 * %G_IO_ERROR_ADDRESS_IN_USE if the server program is stopped and then
34833 * immediately restarted.)
34835 * If @socket is a UDP socket, then @allow_reuse determines whether or
34836 * not other UDP sockets can be bound to the same address at the same
34837 * time. In particular, you can have several UDP sockets bound to the
34838 * same address, and they will all receive all of the multicast and
34839 * broadcast packets sent to that address. (The behavior of unicast
34840 * UDP packets to an address with multiple listeners is not defined.)
34842 * Returns: %TRUE on success, %FALSE on error.
34848 * g_socket_check_connect_result:
34849 * @socket: a #GSocket
34850 * @error: #GError for error reporting, or %NULL to ignore.
34852 * Checks and resets the pending connect error for the socket.
34853 * This is used to check for errors when g_socket_connect() is
34854 * used in non-blocking mode.
34856 * Returns: %TRUE if no error, %FALSE otherwise, setting @error to the error
34862 * g_socket_client_add_application_proxy:
34863 * @client: a #GSocketClient
34864 * @protocol: The proxy protocol
34866 * Enable proxy protocols to be handled by the application. When the
34867 * indicated proxy protocol is returned by the #GProxyResolver,
34868 * #GSocketClient will consider this protocol as supported but will
34869 * not try to find a #GProxy instance to handle handshaking. The
34870 * application must check for this case by calling
34871 * g_socket_connection_get_remote_address() on the returned
34872 * #GSocketConnection, and seeing if it's a #GProxyAddress of the
34873 * appropriate type, to determine whether or not it needs to handle
34874 * the proxy handshaking itself.
34876 * This should be used for proxy protocols that are dialects of
34877 * another protocol such as HTTP proxy. It also allows cohabitation of
34878 * proxy protocols that are reused between protocols. A good example
34879 * is HTTP. It can be used to proxy HTTP, FTP and Gopher and can also
34880 * be use as generic socket proxy through the HTTP CONNECT method.
34882 * When the proxy is detected as being an application proxy, TLS handshake
34883 * will be skipped. This is required to let the application do the proxy
34884 * specific handshake.
34889 * g_socket_client_connect:
34890 * @client: a #GSocketClient.
34891 * @connectable: a #GSocketConnectable specifying the remote address.
34892 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
34893 * @error: #GError for error reporting, or %NULL to ignore.
34895 * Tries to resolve the @connectable and make a network connection to it.
34897 * Upon a successful connection, a new #GSocketConnection is constructed
34898 * and returned. The caller owns this new object and must drop their
34899 * reference to it when finished with it.
34901 * The type of the #GSocketConnection object returned depends on the type of
34902 * the underlying socket that is used. For instance, for a TCP/IP connection
34903 * it will be a #GTcpConnection.
34905 * The socket created will be the same family as the address that the
34906 * @connectable resolves to, unless family is set with g_socket_client_set_family()
34907 * or indirectly via g_socket_client_set_local_address(). The socket type
34908 * defaults to %G_SOCKET_TYPE_STREAM but can be set with
34909 * g_socket_client_set_socket_type().
34911 * If a local address is specified with g_socket_client_set_local_address() the
34912 * socket will be bound to this address before connecting.
34914 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
34920 * g_socket_client_connect_async:
34921 * @client: a #GSocketClient
34922 * @connectable: a #GSocketConnectable specifying the remote address.
34923 * @cancellable: (allow-none): a #GCancellable, or %NULL
34924 * @callback: (scope async): a #GAsyncReadyCallback
34925 * @user_data: (closure): user data for the callback
34927 * This is the asynchronous version of g_socket_client_connect().
34929 * When the operation is finished @callback will be
34930 * called. You can then call g_socket_client_connect_finish() to get
34931 * the result of the operation.
34938 * g_socket_client_connect_finish:
34939 * @client: a #GSocketClient.
34940 * @result: a #GAsyncResult.
34941 * @error: a #GError location to store the error occurring, or %NULL to
34944 * Finishes an async connect operation. See g_socket_client_connect_async()
34946 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
34952 * g_socket_client_connect_to_host:
34953 * @client: a #GSocketClient
34954 * @host_and_port: the name and optionally port of the host to connect to
34955 * @default_port: the default port to connect to
34956 * @cancellable: (allow-none): a #GCancellable, or %NULL
34957 * @error: a pointer to a #GError, or %NULL
34959 * This is a helper function for g_socket_client_connect().
34961 * Attempts to create a TCP connection to the named host.
34963 * @host_and_port may be in any of a number of recognized formats; an IPv6
34964 * address, an IPv4 address, or a domain name (in which case a DNS
34965 * lookup is performed). Quoting with [] is supported for all address
34966 * types. A port override may be specified in the usual way with a
34967 * colon. Ports may be given as decimal numbers or symbolic names (in
34968 * which case an /etc/services lookup is performed).
34970 * If no port override is given in @host_and_port then @default_port will be
34971 * used as the port number to connect to.
34973 * In general, @host_and_port is expected to be provided by the user (allowing
34974 * them to give the hostname, and a port override if necessary) and
34975 * @default_port is expected to be provided by the application.
34977 * In the case that an IP address is given, a single connection
34978 * attempt is made. In the case that a name is given, multiple
34979 * connection attempts may be made, in turn and according to the
34980 * number of address records in DNS, until a connection succeeds.
34982 * Upon a successful connection, a new #GSocketConnection is constructed
34983 * and returned. The caller owns this new object and must drop their
34984 * reference to it when finished with it.
34986 * In the event of any failure (DNS error, service not found, no hosts
34987 * connectable) %NULL is returned and @error (if non-%NULL) is set
34990 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
34996 * g_socket_client_connect_to_host_async:
34997 * @client: a #GSocketClient
34998 * @host_and_port: the name and optionally the port of the host to connect to
34999 * @default_port: the default port to connect to
35000 * @cancellable: (allow-none): a #GCancellable, or %NULL
35001 * @callback: (scope async): a #GAsyncReadyCallback
35002 * @user_data: (closure): user data for the callback
35004 * This is the asynchronous version of g_socket_client_connect_to_host().
35006 * When the operation is finished @callback will be
35007 * called. You can then call g_socket_client_connect_to_host_finish() to get
35008 * the result of the operation.
35015 * g_socket_client_connect_to_host_finish:
35016 * @client: a #GSocketClient.
35017 * @result: a #GAsyncResult.
35018 * @error: a #GError location to store the error occurring, or %NULL to
35021 * Finishes an async connect operation. See g_socket_client_connect_to_host_async()
35023 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
35029 * g_socket_client_connect_to_service:
35030 * @client: a #GSocketConnection
35031 * @domain: a domain name
35032 * @service: the name of the service to connect to
35033 * @cancellable: (allow-none): a #GCancellable, or %NULL
35034 * @error: a pointer to a #GError, or %NULL
35036 * Attempts to create a TCP connection to a service.
35038 * This call looks up the SRV record for @service at @domain for the
35039 * "tcp" protocol. It then attempts to connect, in turn, to each of
35040 * the hosts providing the service until either a connection succeeds
35041 * or there are no hosts remaining.
35043 * Upon a successful connection, a new #GSocketConnection is constructed
35044 * and returned. The caller owns this new object and must drop their
35045 * reference to it when finished with it.
35047 * In the event of any failure (DNS error, service not found, no hosts
35048 * connectable) %NULL is returned and @error (if non-%NULL) is set
35051 * Returns: (transfer full): a #GSocketConnection if successful, or %NULL on error
35056 * g_socket_client_connect_to_service_async:
35057 * @client: a #GSocketClient
35058 * @domain: a domain name
35059 * @service: the name of the service to connect to
35060 * @cancellable: (allow-none): a #GCancellable, or %NULL
35061 * @callback: (scope async): a #GAsyncReadyCallback
35062 * @user_data: (closure): user data for the callback
35064 * This is the asynchronous version of
35065 * g_socket_client_connect_to_service().
35072 * g_socket_client_connect_to_service_finish:
35073 * @client: a #GSocketClient.
35074 * @result: a #GAsyncResult.
35075 * @error: a #GError location to store the error occurring, or %NULL to
35078 * Finishes an async connect operation. See g_socket_client_connect_to_service_async()
35080 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
35086 * g_socket_client_connect_to_uri:
35087 * @client: a #GSocketClient
35088 * @uri: A network URI
35089 * @default_port: the default port to connect to
35090 * @cancellable: (allow-none): a #GCancellable, or %NULL
35091 * @error: a pointer to a #GError, or %NULL
35093 * This is a helper function for g_socket_client_connect().
35095 * Attempts to create a TCP connection with a network URI.
35097 * @uri may be any valid URI containing an "authority" (hostname/port)
35098 * component. If a port is not specified in the URI, @default_port
35099 * will be used. TLS will be negotiated if #GSocketClient:tls is %TRUE.
35100 * (#GSocketClient does not know to automatically assume TLS for
35101 * certain URI schemes.)
35103 * Using this rather than g_socket_client_connect() or
35104 * g_socket_client_connect_to_host() allows #GSocketClient to
35105 * determine when to use application-specific proxy protocols.
35107 * Upon a successful connection, a new #GSocketConnection is constructed
35108 * and returned. The caller owns this new object and must drop their
35109 * reference to it when finished with it.
35111 * In the event of any failure (DNS error, service not found, no hosts
35112 * connectable) %NULL is returned and @error (if non-%NULL) is set
35115 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
35121 * g_socket_client_connect_to_uri_async:
35122 * @client: a #GSocketClient
35123 * @uri: a network uri
35124 * @default_port: the default port to connect to
35125 * @cancellable: (allow-none): a #GCancellable, or %NULL
35126 * @callback: (scope async): a #GAsyncReadyCallback
35127 * @user_data: (closure): user data for the callback
35129 * This is the asynchronous version of g_socket_client_connect_to_uri().
35131 * When the operation is finished @callback will be
35132 * called. You can then call g_socket_client_connect_to_uri_finish() to get
35133 * the result of the operation.
35140 * g_socket_client_connect_to_uri_finish:
35141 * @client: a #GSocketClient.
35142 * @result: a #GAsyncResult.
35143 * @error: a #GError location to store the error occurring, or %NULL to
35146 * Finishes an async connect operation. See g_socket_client_connect_to_uri_async()
35148 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
35154 * g_socket_client_get_enable_proxy:
35155 * @client: a #GSocketClient.
35157 * Gets the proxy enable state; see g_socket_client_set_enable_proxy()
35159 * Returns: whether proxying is enabled
35165 * g_socket_client_get_family:
35166 * @client: a #GSocketClient.
35168 * Gets the socket family of the socket client.
35170 * See g_socket_client_set_family() for details.
35172 * Returns: a #GSocketFamily
35178 * g_socket_client_get_local_address:
35179 * @client: a #GSocketClient.
35181 * Gets the local address of the socket client.
35183 * See g_socket_client_set_local_address() for details.
35185 * Returns: (transfer none): a #GSocketAddress or %NULL. Do not free.
35191 * g_socket_client_get_protocol:
35192 * @client: a #GSocketClient
35194 * Gets the protocol name type of the socket client.
35196 * See g_socket_client_set_protocol() for details.
35198 * Returns: a #GSocketProtocol
35204 * g_socket_client_get_proxy_resolver:
35205 * @client: a #GSocketClient.
35207 * Gets the #GProxyResolver being used by @client. Normally, this will
35208 * be the resolver returned by g_proxy_resolver_get_default(), but you
35209 * can override it with g_socket_client_set_proxy_resolver().
35211 * Returns: (transfer none): The #GProxyResolver being used by
35218 * g_socket_client_get_socket_type:
35219 * @client: a #GSocketClient.
35221 * Gets the socket type of the socket client.
35223 * See g_socket_client_set_socket_type() for details.
35225 * Returns: a #GSocketFamily
35231 * g_socket_client_get_timeout:
35232 * @client: a #GSocketClient
35234 * Gets the I/O timeout time for sockets created by @client.
35236 * See g_socket_client_set_timeout() for details.
35238 * Returns: the timeout in seconds
35244 * g_socket_client_get_tls:
35245 * @client: a #GSocketClient.
35247 * Gets whether @client creates TLS connections. See
35248 * g_socket_client_set_tls() for details.
35250 * Returns: whether @client uses TLS
35256 * g_socket_client_get_tls_validation_flags:
35257 * @client: a #GSocketClient.
35259 * Gets the TLS validation flags used creating TLS connections via
35262 * Returns: the TLS validation flags
35268 * g_socket_client_new:
35270 * Creates a new #GSocketClient with the default options.
35272 * Returns: a #GSocketClient.
35273 * Free the returned object with g_object_unref().
35279 * g_socket_client_set_enable_proxy:
35280 * @client: a #GSocketClient.
35281 * @enable: whether to enable proxies
35283 * Sets whether or not @client attempts to make connections via a
35284 * proxy server. When enabled (the default), #GSocketClient will use a
35285 * #GProxyResolver to determine if a proxy protocol such as SOCKS is
35286 * needed, and automatically do the necessary proxy negotiation.
35288 * See also g_socket_client_set_proxy_resolver().
35295 * g_socket_client_set_family:
35296 * @client: a #GSocketClient.
35297 * @family: a #GSocketFamily
35299 * Sets the socket family of the socket client.
35300 * If this is set to something other than %G_SOCKET_FAMILY_INVALID
35301 * then the sockets created by this object will be of the specified
35304 * This might be useful for instance if you want to force the local
35305 * connection to be an ipv4 socket, even though the address might
35306 * be an ipv6 mapped to ipv4 address.
35313 * g_socket_client_set_local_address:
35314 * @client: a #GSocketClient.
35315 * @address: (allow-none): a #GSocketAddress, or %NULL
35317 * Sets the local address of the socket client.
35318 * The sockets created by this object will bound to the
35319 * specified address (if not %NULL) before connecting.
35321 * This is useful if you want to ensure that the local
35322 * side of the connection is on a specific port, or on
35323 * a specific interface.
35330 * g_socket_client_set_protocol:
35331 * @client: a #GSocketClient.
35332 * @protocol: a #GSocketProtocol
35334 * Sets the protocol of the socket client.
35335 * The sockets created by this object will use of the specified
35338 * If @protocol is %0 that means to use the default
35339 * protocol for the socket family and type.
35346 * g_socket_client_set_proxy_resolver:
35347 * @client: a #GSocketClient.
35348 * @proxy_resolver: (allow-none): a #GProxyResolver, or %NULL for the
35351 * Overrides the #GProxyResolver used by @client. You can call this if
35352 * you want to use specific proxies, rather than using the system
35353 * default proxy settings.
35355 * Note that whether or not the proxy resolver is actually used
35356 * depends on the setting of #GSocketClient:enable-proxy, which is not
35357 * changed by this function (but which is %TRUE by default)
35364 * g_socket_client_set_socket_type:
35365 * @client: a #GSocketClient.
35366 * @type: a #GSocketType
35368 * Sets the socket type of the socket client.
35369 * The sockets created by this object will be of the specified
35372 * It doesn't make sense to specify a type of %G_SOCKET_TYPE_DATAGRAM,
35373 * as GSocketClient is used for connection oriented services.
35380 * g_socket_client_set_timeout:
35381 * @client: a #GSocketClient.
35382 * @timeout: the timeout
35384 * Sets the I/O timeout for sockets created by @client. @timeout is a
35385 * time in seconds, or 0 for no timeout (the default).
35387 * The timeout value affects the initial connection attempt as well,
35388 * so setting this may cause calls to g_socket_client_connect(), etc,
35389 * to fail with %G_IO_ERROR_TIMED_OUT.
35396 * g_socket_client_set_tls:
35397 * @client: a #GSocketClient.
35398 * @tls: whether to use TLS
35400 * Sets whether @client creates TLS (aka SSL) connections. If @tls is
35401 * %TRUE, @client will wrap its connections in a #GTlsClientConnection
35402 * and perform a TLS handshake when connecting.
35404 * Note that since #GSocketClient must return a #GSocketConnection,
35405 * but #GTlsClientConnection is not a #GSocketConnection, this
35406 * actually wraps the resulting #GTlsClientConnection in a
35407 * #GTcpWrapperConnection when returning it. You can use
35408 * g_tcp_wrapper_connection_get_base_io_stream() on the return value
35409 * to extract the #GTlsClientConnection.
35411 * If you need to modify the behavior of the TLS handshake (eg, by
35412 * setting a client-side certificate to use, or connecting to the
35413 * #GTlsConnection::accept-certificate signal), you can connect to
35414 * @client's #GSocketClient::event signal and wait for it to be
35415 * emitted with %G_SOCKET_CLIENT_TLS_HANDSHAKING, which will give you
35416 * a chance to see the #GTlsClientConnection before the handshake
35424 * g_socket_client_set_tls_validation_flags:
35425 * @client: a #GSocketClient.
35426 * @flags: the validation flags
35428 * Sets the TLS validation flags used when creating TLS connections
35429 * via @client. The default value is %G_TLS_CERTIFICATE_VALIDATE_ALL.
35437 * @socket: a #GSocket
35438 * @error: #GError for error reporting, or %NULL to ignore.
35440 * Closes the socket, shutting down any active connection.
35442 * Closing a socket does not wait for all outstanding I/O operations
35443 * to finish, so the caller should not rely on them to be guaranteed
35444 * to complete even if the close returns with no error.
35446 * Once the socket is closed, all other operations will return
35447 * %G_IO_ERROR_CLOSED. Closing a socket multiple times will not
35450 * Sockets will be automatically closed when the last reference
35451 * is dropped, but you might want to call this function to make sure
35452 * resources are released as early as possible.
35454 * Beware that due to the way that TCP works, it is possible for
35455 * recently-sent data to be lost if either you close a socket while the
35456 * %G_IO_IN condition is set, or else if the remote connection tries to
35457 * send something to you after you close the socket but before it has
35458 * finished reading all of the data you sent. There is no easy generic
35459 * way to avoid this problem; the easiest fix is to design the network
35460 * protocol such that the client will never send data "out of turn".
35461 * Another solution is for the server to half-close the connection by
35462 * calling g_socket_shutdown() with only the @shutdown_write flag set,
35463 * and then wait for the client to notice this and close its side of the
35464 * connection, after which the server can safely call g_socket_close().
35465 * (This is what #GTcpConnection does if you call
35466 * g_tcp_connection_set_graceful_disconnect(). But of course, this
35467 * only works if the client will close its connection after the server
35470 * Returns: %TRUE on success, %FALSE on error
35476 * g_socket_condition_check:
35477 * @socket: a #GSocket
35478 * @condition: a #GIOCondition mask to check
35480 * Checks on the readiness of @socket to perform operations.
35481 * The operations specified in @condition are checked for and masked
35482 * against the currently-satisfied conditions on @socket. The result
35485 * Note that on Windows, it is possible for an operation to return
35486 * %G_IO_ERROR_WOULD_BLOCK even immediately after
35487 * g_socket_condition_check() has claimed that the socket is ready for
35488 * writing. Rather than calling g_socket_condition_check() and then
35489 * writing to the socket if it succeeds, it is generally better to
35490 * simply try writing to the socket right away, and try again later if
35491 * the initial attempt returns %G_IO_ERROR_WOULD_BLOCK.
35493 * It is meaningless to specify %G_IO_ERR or %G_IO_HUP in condition;
35494 * these conditions will always be set in the output if they are true.
35496 * This call never blocks.
35498 * Returns: the @GIOCondition mask of the current state
35504 * g_socket_condition_timed_wait:
35505 * @socket: a #GSocket
35506 * @condition: a #GIOCondition mask to wait for
35507 * @timeout: the maximum time (in microseconds) to wait, or -1
35508 * @cancellable: (allow-none): a #GCancellable, or %NULL
35509 * @error: a #GError pointer, or %NULL
35511 * Waits for up to @timeout microseconds for @condition to become true
35512 * on @socket. If the condition is met, %TRUE is returned.
35514 * If @cancellable is cancelled before the condition is met, or if
35515 * @timeout (or the socket's #GSocket:timeout) is reached before the
35516 * condition is met, then %FALSE is returned and @error, if non-%NULL,
35517 * is set to the appropriate value (%G_IO_ERROR_CANCELLED or
35518 * %G_IO_ERROR_TIMED_OUT).
35520 * If you don't want a timeout, use g_socket_condition_wait().
35521 * (Alternatively, you can pass -1 for @timeout.)
35523 * Note that although @timeout is in microseconds for consistency with
35524 * other GLib APIs, this function actually only has millisecond
35525 * resolution, and the behavior is undefined if @timeout is not an
35526 * exact number of milliseconds.
35528 * Returns: %TRUE if the condition was met, %FALSE otherwise
35534 * g_socket_condition_wait:
35535 * @socket: a #GSocket
35536 * @condition: a #GIOCondition mask to wait for
35537 * @cancellable: (allow-none): a #GCancellable, or %NULL
35538 * @error: a #GError pointer, or %NULL
35540 * Waits for @condition to become true on @socket. When the condition
35541 * is met, %TRUE is returned.
35543 * If @cancellable is cancelled before the condition is met, or if the
35544 * socket has a timeout set and it is reached before the condition is
35545 * met, then %FALSE is returned and @error, if non-%NULL, is set to
35546 * the appropriate value (%G_IO_ERROR_CANCELLED or
35547 * %G_IO_ERROR_TIMED_OUT).
35549 * See also g_socket_condition_timed_wait().
35551 * Returns: %TRUE if the condition was met, %FALSE otherwise
35557 * g_socket_connect:
35558 * @socket: a #GSocket.
35559 * @address: a #GSocketAddress specifying the remote address.
35560 * @cancellable: (allow-none): a %GCancellable or %NULL
35561 * @error: #GError for error reporting, or %NULL to ignore.
35563 * Connect the socket to the specified remote address.
35565 * For connection oriented socket this generally means we attempt to make
35566 * a connection to the @address. For a connection-less socket it sets
35567 * the default address for g_socket_send() and discards all incoming datagrams
35568 * from other sources.
35570 * Generally connection oriented sockets can only connect once, but
35571 * connection-less sockets can connect multiple times to change the
35574 * If the connect call needs to do network I/O it will block, unless
35575 * non-blocking I/O is enabled. Then %G_IO_ERROR_PENDING is returned
35576 * and the user can be notified of the connection finishing by waiting
35577 * for the G_IO_OUT condition. The result of the connection must then be
35578 * checked with g_socket_check_connect_result().
35580 * Returns: %TRUE if connected, %FALSE on error.
35586 * g_socket_connectable_enumerate:
35587 * @connectable: a #GSocketConnectable
35589 * Creates a #GSocketAddressEnumerator for @connectable.
35591 * Returns: (transfer full): a new #GSocketAddressEnumerator.
35597 * g_socket_connectable_proxy_enumerate:
35598 * @connectable: a #GSocketConnectable
35600 * Creates a #GSocketAddressEnumerator for @connectable that will
35601 * return #GProxyAddresses for addresses that you must connect
35604 * If @connectable does not implement
35605 * g_socket_connectable_proxy_enumerate(), this will fall back to
35606 * calling g_socket_connectable_enumerate().
35608 * Returns: (transfer full): a new #GSocketAddressEnumerator.
35614 * g_socket_connectable_to_string:
35615 * @connectable: a #GSocketConnectable
35617 * Format a #GSocketConnectable as a string. This is a human-readable format for
35618 * use in debugging output, and is not a stable serialization format. It is not
35619 * suitable for use in user interfaces as it exposes too much information for a
35622 * If the #GSocketConnectable implementation does not support string formatting,
35623 * the implementation’s type name will be returned as a fallback.
35625 * Returns: (transfer full): the formatted string
35631 * g_socket_connection_connect:
35632 * @connection: a #GSocketConnection
35633 * @address: a #GSocketAddress specifying the remote address.
35634 * @cancellable: (allow-none): a %GCancellable or %NULL
35635 * @error: #GError for error reporting, or %NULL to ignore.
35637 * Connect @connection to the specified remote address.
35639 * Returns: %TRUE if the connection succeeded, %FALSE on error
35645 * g_socket_connection_connect_async:
35646 * @connection: a #GSocketConnection
35647 * @address: a #GSocketAddress specifying the remote address.
35648 * @cancellable: (allow-none): a %GCancellable or %NULL
35649 * @callback: (scope async): a #GAsyncReadyCallback
35650 * @user_data: (closure): user data for the callback
35652 * Asynchronously connect @connection to the specified remote address.
35654 * This clears the #GSocket:blocking flag on @connection's underlying
35655 * socket if it is currently set.
35657 * Use g_socket_connection_connect_finish() to retrieve the result.
35664 * g_socket_connection_connect_finish:
35665 * @connection: a #GSocketConnection
35666 * @result: the #GAsyncResult
35667 * @error: #GError for error reporting, or %NULL to ignore.
35669 * Gets the result of a g_socket_connection_connect_async() call.
35671 * Returns: %TRUE if the connection succeeded, %FALSE on error
35677 * g_socket_connection_factory_create_connection:
35678 * @socket: a #GSocket
35680 * Creates a #GSocketConnection subclass of the right type for
35683 * Returns: (transfer full): a #GSocketConnection
35689 * g_socket_connection_factory_lookup_type:
35690 * @family: a #GSocketFamily
35691 * @type: a #GSocketType
35692 * @protocol_id: a protocol id
35694 * Looks up the #GType to be used when creating socket connections on
35695 * sockets with the specified @family, @type and @protocol_id.
35697 * If no type is registered, the #GSocketConnection base type is returned.
35699 * Returns: a #GType
35705 * g_socket_connection_factory_register_type:
35706 * @g_type: a #GType, inheriting from %G_TYPE_SOCKET_CONNECTION
35707 * @family: a #GSocketFamily
35708 * @type: a #GSocketType
35709 * @protocol: a protocol id
35711 * Looks up the #GType to be used when creating socket connections on
35712 * sockets with the specified @family, @type and @protocol.
35714 * If no type is registered, the #GSocketConnection base type is returned.
35721 * g_socket_connection_get_local_address:
35722 * @connection: a #GSocketConnection
35723 * @error: #GError for error reporting, or %NULL to ignore.
35725 * Try to get the local address of a socket connection.
35727 * Returns: (transfer full): a #GSocketAddress or %NULL on error.
35728 * Free the returned object with g_object_unref().
35734 * g_socket_connection_get_remote_address:
35735 * @connection: a #GSocketConnection
35736 * @error: #GError for error reporting, or %NULL to ignore.
35738 * Try to get the remote address of a socket connection.
35740 * Since GLib 2.40, when used with g_socket_client_connect() or
35741 * g_socket_client_connect_async(), during emission of
35742 * %G_SOCKET_CLIENT_CONNECTING, this function will return the remote
35743 * address that will be used for the connection. This allows
35744 * applications to print e.g. "Connecting to example.com
35745 * (10.42.77.3)...".
35747 * Returns: (transfer full): a #GSocketAddress or %NULL on error.
35748 * Free the returned object with g_object_unref().
35754 * g_socket_connection_get_socket:
35755 * @connection: a #GSocketConnection
35757 * Gets the underlying #GSocket object of the connection.
35758 * This can be useful if you want to do something unusual on it
35759 * not supported by the #GSocketConnection APIs.
35761 * Returns: (transfer none): a #GSocket or %NULL on error.
35767 * g_socket_connection_is_connected:
35768 * @connection: a #GSocketConnection
35770 * Checks if @connection is connected. This is equivalent to calling
35771 * g_socket_is_connected() on @connection's underlying #GSocket.
35773 * Returns: whether @connection is connected
35779 * g_socket_control_message_deserialize:
35780 * @level: a socket level
35781 * @type: a socket control message type for the given @level
35782 * @size: the size of the data in bytes
35783 * @data: (array length=size) (element-type guint8): pointer to the message data
35785 * Tries to deserialize a socket control message of a given
35786 * @level and @type. This will ask all known (to GType) subclasses
35787 * of #GSocketControlMessage if they can understand this kind
35788 * of message and if so deserialize it into a #GSocketControlMessage.
35790 * If there is no implementation for this kind of control message, %NULL
35791 * will be returned.
35793 * Returns: (transfer full): the deserialized message or %NULL
35799 * g_socket_control_message_get_level:
35800 * @message: a #GSocketControlMessage
35802 * Returns the "level" (i.e. the originating protocol) of the control message.
35803 * This is often SOL_SOCKET.
35805 * Returns: an integer describing the level
35811 * g_socket_control_message_get_msg_type:
35812 * @message: a #GSocketControlMessage
35814 * Returns the protocol specific type of the control message.
35815 * For instance, for UNIX fd passing this would be SCM_RIGHTS.
35817 * Returns: an integer describing the type of control message
35823 * g_socket_control_message_get_size:
35824 * @message: a #GSocketControlMessage
35826 * Returns the space required for the control message, not including
35827 * headers or alignment.
35829 * Returns: The number of bytes required.
35835 * g_socket_control_message_serialize:
35836 * @message: a #GSocketControlMessage
35837 * @data: (not nullable): A buffer to write data to
35839 * Converts the data in the message to bytes placed in the
35842 * @data is guaranteed to have enough space to fit the size
35843 * returned by g_socket_control_message_get_size() on this
35851 * g_socket_create_source: (skip)
35852 * @socket: a #GSocket
35853 * @condition: a #GIOCondition mask to monitor
35854 * @cancellable: (allow-none): a %GCancellable or %NULL
35856 * Creates a #GSource that can be attached to a %GMainContext to monitor
35857 * for the availability of the specified @condition on the socket. The #GSource
35858 * keeps a reference to the @socket.
35860 * The callback on the source is of the #GSocketSourceFunc type.
35862 * It is meaningless to specify %G_IO_ERR or %G_IO_HUP in @condition;
35863 * these conditions will always be reported output if they are true.
35865 * @cancellable if not %NULL can be used to cancel the source, which will
35866 * cause the source to trigger, reporting the current condition (which
35867 * is likely 0 unless cancellation happened at the same time as a
35868 * condition change). You can check for this in the callback using
35869 * g_cancellable_is_cancelled().
35871 * If @socket has a timeout set, and it is reached before @condition
35872 * occurs, the source will then trigger anyway, reporting %G_IO_IN or
35873 * %G_IO_OUT depending on @condition. However, @socket will have been
35874 * marked as having had a timeout, and so the next #GSocket I/O method
35875 * you call will then fail with a %G_IO_ERROR_TIMED_OUT.
35877 * Returns: (transfer full): a newly allocated %GSource, free with g_source_unref().
35883 * g_socket_get_available_bytes:
35884 * @socket: a #GSocket
35886 * Get the amount of data pending in the OS input buffer, without blocking.
35888 * If @socket is a UDP or SCTP socket, this will return the size of
35889 * just the next packet, even if additional packets are buffered after
35892 * Note that on Windows, this function is rather inefficient in the
35893 * UDP case, and so if you know any plausible upper bound on the size
35894 * of the incoming packet, it is better to just do a
35895 * g_socket_receive() with a buffer of that size, rather than calling
35896 * g_socket_get_available_bytes() first and then doing a receive of
35897 * exactly the right size.
35899 * Returns: the number of bytes that can be read from the socket
35900 * without blocking or truncating, or -1 on error.
35906 * g_socket_get_blocking:
35907 * @socket: a #GSocket.
35909 * Gets the blocking mode of the socket. For details on blocking I/O,
35910 * see g_socket_set_blocking().
35912 * Returns: %TRUE if blocking I/O is used, %FALSE otherwise.
35918 * g_socket_get_broadcast:
35919 * @socket: a #GSocket.
35921 * Gets the broadcast setting on @socket; if %TRUE,
35922 * it is possible to send packets to broadcast
35925 * Returns: the broadcast setting on @socket
35931 * g_socket_get_credentials:
35932 * @socket: a #GSocket.
35933 * @error: #GError for error reporting, or %NULL to ignore.
35935 * Returns the credentials of the foreign process connected to this
35936 * socket, if any (e.g. it is only supported for %G_SOCKET_FAMILY_UNIX
35939 * If this operation isn't supported on the OS, the method fails with
35940 * the %G_IO_ERROR_NOT_SUPPORTED error. On Linux this is implemented
35941 * by reading the %SO_PEERCRED option on the underlying socket.
35943 * Other ways to obtain credentials from a foreign peer includes the
35944 * #GUnixCredentialsMessage type and
35945 * g_unix_connection_send_credentials() /
35946 * g_unix_connection_receive_credentials() functions.
35948 * Returns: (transfer full): %NULL if @error is set, otherwise a #GCredentials object
35949 * that must be freed with g_object_unref().
35955 * g_socket_get_family:
35956 * @socket: a #GSocket.
35958 * Gets the socket family of the socket.
35960 * Returns: a #GSocketFamily
35967 * @socket: a #GSocket.
35969 * Returns the underlying OS socket object. On unix this
35970 * is a socket file descriptor, and on Windows this is
35971 * a Winsock2 SOCKET handle. This may be useful for
35972 * doing platform specific or otherwise unusual operations
35975 * Returns: the file descriptor of the socket.
35981 * g_socket_get_keepalive:
35982 * @socket: a #GSocket.
35984 * Gets the keepalive mode of the socket. For details on this,
35985 * see g_socket_set_keepalive().
35987 * Returns: %TRUE if keepalive is active, %FALSE otherwise.
35993 * g_socket_get_listen_backlog:
35994 * @socket: a #GSocket.
35996 * Gets the listen backlog setting of the socket. For details on this,
35997 * see g_socket_set_listen_backlog().
35999 * Returns: the maximum number of pending connections.
36005 * g_socket_get_local_address:
36006 * @socket: a #GSocket.
36007 * @error: #GError for error reporting, or %NULL to ignore.
36009 * Try to get the local address of a bound socket. This is only
36010 * useful if the socket has been bound to a local address,
36011 * either explicitly or implicitly when connecting.
36013 * Returns: (transfer full): a #GSocketAddress or %NULL on error.
36014 * Free the returned object with g_object_unref().
36020 * g_socket_get_multicast_loopback:
36021 * @socket: a #GSocket.
36023 * Gets the multicast loopback setting on @socket; if %TRUE (the
36024 * default), outgoing multicast packets will be looped back to
36025 * multicast listeners on the same host.
36027 * Returns: the multicast loopback setting on @socket
36033 * g_socket_get_multicast_ttl:
36034 * @socket: a #GSocket.
36036 * Gets the multicast time-to-live setting on @socket; see
36037 * g_socket_set_multicast_ttl() for more details.
36039 * Returns: the multicast time-to-live setting on @socket
36045 * g_socket_get_option:
36046 * @socket: a #GSocket
36047 * @level: the "API level" of the option (eg, `SOL_SOCKET`)
36048 * @optname: the "name" of the option (eg, `SO_BROADCAST`)
36049 * @value: (out): return location for the option value
36050 * @error: #GError for error reporting, or %NULL to ignore.
36052 * Gets the value of an integer-valued option on @socket, as with
36053 * getsockopt(). (If you need to fetch a non-integer-valued option,
36054 * you will need to call getsockopt() directly.)
36056 * The [<gio/gnetworking.h>][gio-gnetworking.h]
36057 * header pulls in system headers that will define most of the
36058 * standard/portable socket options. For unusual socket protocols or
36059 * platform-dependent options, you may need to include additional
36062 * Note that even for socket options that are a single byte in size,
36063 * @value is still a pointer to a #gint variable, not a #guchar;
36064 * g_socket_get_option() will handle the conversion internally.
36066 * Returns: success or failure. On failure, @error will be set, and
36067 * the system error value (`errno` or WSAGetLastError()) will still
36068 * be set to the result of the getsockopt() call.
36074 * g_socket_get_protocol:
36075 * @socket: a #GSocket.
36077 * Gets the socket protocol id the socket was created with.
36078 * In case the protocol is unknown, -1 is returned.
36080 * Returns: a protocol id, or -1 if unknown
36086 * g_socket_get_remote_address:
36087 * @socket: a #GSocket.
36088 * @error: #GError for error reporting, or %NULL to ignore.
36090 * Try to get the remove address of a connected socket. This is only
36091 * useful for connection oriented sockets that have been connected.
36093 * Returns: (transfer full): a #GSocketAddress or %NULL on error.
36094 * Free the returned object with g_object_unref().
36100 * g_socket_get_socket_type:
36101 * @socket: a #GSocket.
36103 * Gets the socket type of the socket.
36105 * Returns: a #GSocketType
36111 * g_socket_get_timeout:
36112 * @socket: a #GSocket.
36114 * Gets the timeout setting of the socket. For details on this, see
36115 * g_socket_set_timeout().
36117 * Returns: the timeout in seconds
36123 * g_socket_get_ttl:
36124 * @socket: a #GSocket.
36126 * Gets the unicast time-to-live setting on @socket; see
36127 * g_socket_set_ttl() for more details.
36129 * Returns: the time-to-live setting on @socket
36135 * g_socket_is_closed:
36136 * @socket: a #GSocket
36138 * Checks whether a socket is closed.
36140 * Returns: %TRUE if socket is closed, %FALSE otherwise
36146 * g_socket_is_connected:
36147 * @socket: a #GSocket.
36149 * Check whether the socket is connected. This is only useful for
36150 * connection-oriented sockets.
36152 * If using g_socket_shutdown(), this function will return %TRUE until the
36153 * socket has been shut down for reading and writing. If you do a non-blocking
36154 * connect, this function will not return %TRUE until after you call
36155 * g_socket_check_connect_result().
36157 * Returns: %TRUE if socket is connected, %FALSE otherwise.
36163 * g_socket_join_multicast_group:
36164 * @socket: a #GSocket.
36165 * @group: a #GInetAddress specifying the group address to join.
36166 * @iface: (allow-none): Name of the interface to use, or %NULL
36167 * @source_specific: %TRUE if source-specific multicast should be used
36168 * @error: #GError for error reporting, or %NULL to ignore.
36170 * Registers @socket to receive multicast messages sent to @group.
36171 * @socket must be a %G_SOCKET_TYPE_DATAGRAM socket, and must have
36172 * been bound to an appropriate interface and port with
36175 * If @iface is %NULL, the system will automatically pick an interface
36176 * to bind to based on @group.
36178 * If @source_specific is %TRUE, source-specific multicast as defined
36179 * in RFC 4604 is used. Note that on older platforms this may fail
36180 * with a %G_IO_ERROR_NOT_SUPPORTED error.
36182 * Returns: %TRUE on success, %FALSE on error.
36188 * g_socket_leave_multicast_group:
36189 * @socket: a #GSocket.
36190 * @group: a #GInetAddress specifying the group address to leave.
36191 * @iface: (allow-none): Interface used
36192 * @source_specific: %TRUE if source-specific multicast was used
36193 * @error: #GError for error reporting, or %NULL to ignore.
36195 * Removes @socket from the multicast group defined by @group, @iface,
36196 * and @source_specific (which must all have the same values they had
36197 * when you joined the group).
36199 * @socket remains bound to its address and port, and can still receive
36200 * unicast messages after calling this.
36202 * Returns: %TRUE on success, %FALSE on error.
36209 * @socket: a #GSocket.
36210 * @error: #GError for error reporting, or %NULL to ignore.
36212 * Marks the socket as a server socket, i.e. a socket that is used
36213 * to accept incoming requests using g_socket_accept().
36215 * Before calling this the socket must be bound to a local address using
36218 * To set the maximum amount of outstanding clients, use
36219 * g_socket_set_listen_backlog().
36221 * Returns: %TRUE on success, %FALSE on error.
36227 * g_socket_listener_accept:
36228 * @listener: a #GSocketListener
36229 * @source_object: (out) (transfer none) (allow-none): location where #GObject pointer will be stored, or %NULL
36230 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
36231 * @error: #GError for error reporting, or %NULL to ignore.
36233 * Blocks waiting for a client to connect to any of the sockets added
36234 * to the listener. Returns a #GSocketConnection for the socket that was
36237 * If @source_object is not %NULL it will be filled out with the source
36238 * object specified when the corresponding socket or address was added
36241 * If @cancellable is not %NULL, then the operation can be cancelled by
36242 * triggering the cancellable object from another thread. If the operation
36243 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
36245 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
36251 * g_socket_listener_accept_async:
36252 * @listener: a #GSocketListener
36253 * @cancellable: (allow-none): a #GCancellable, or %NULL
36254 * @callback: (scope async): a #GAsyncReadyCallback
36255 * @user_data: (closure): user data for the callback
36257 * This is the asynchronous version of g_socket_listener_accept().
36259 * When the operation is finished @callback will be
36260 * called. You can then call g_socket_listener_accept_socket()
36261 * to get the result of the operation.
36268 * g_socket_listener_accept_finish:
36269 * @listener: a #GSocketListener
36270 * @result: a #GAsyncResult.
36271 * @source_object: (out) (transfer none) (allow-none): Optional #GObject identifying this source
36272 * @error: a #GError location to store the error occurring, or %NULL to
36275 * Finishes an async accept operation. See g_socket_listener_accept_async()
36277 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
36283 * g_socket_listener_accept_socket:
36284 * @listener: a #GSocketListener
36285 * @source_object: (out) (transfer none) (allow-none): location where #GObject pointer will be stored, or %NULL.
36286 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
36287 * @error: #GError for error reporting, or %NULL to ignore.
36289 * Blocks waiting for a client to connect to any of the sockets added
36290 * to the listener. Returns the #GSocket that was accepted.
36292 * If you want to accept the high-level #GSocketConnection, not a #GSocket,
36293 * which is often the case, then you should use g_socket_listener_accept()
36296 * If @source_object is not %NULL it will be filled out with the source
36297 * object specified when the corresponding socket or address was added
36300 * If @cancellable is not %NULL, then the operation can be cancelled by
36301 * triggering the cancellable object from another thread. If the operation
36302 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
36304 * Returns: (transfer full): a #GSocket on success, %NULL on error.
36310 * g_socket_listener_accept_socket_async:
36311 * @listener: a #GSocketListener
36312 * @cancellable: (allow-none): a #GCancellable, or %NULL
36313 * @callback: (scope async): a #GAsyncReadyCallback
36314 * @user_data: (closure): user data for the callback
36316 * This is the asynchronous version of g_socket_listener_accept_socket().
36318 * When the operation is finished @callback will be
36319 * called. You can then call g_socket_listener_accept_socket_finish()
36320 * to get the result of the operation.
36327 * g_socket_listener_accept_socket_finish:
36328 * @listener: a #GSocketListener
36329 * @result: a #GAsyncResult.
36330 * @source_object: (out) (transfer none) (allow-none): Optional #GObject identifying this source
36331 * @error: a #GError location to store the error occurring, or %NULL to
36334 * Finishes an async accept operation. See g_socket_listener_accept_socket_async()
36336 * Returns: (transfer full): a #GSocket on success, %NULL on error.
36342 * g_socket_listener_add_address:
36343 * @listener: a #GSocketListener
36344 * @address: a #GSocketAddress
36345 * @type: a #GSocketType
36346 * @protocol: a #GSocketProtocol
36347 * @source_object: (allow-none): Optional #GObject identifying this source
36348 * @effective_address: (out) (allow-none): location to store the address that was bound to, or %NULL.
36349 * @error: #GError for error reporting, or %NULL to ignore.
36351 * Creates a socket of type @type and protocol @protocol, binds
36352 * it to @address and adds it to the set of sockets we're accepting
36355 * Note that adding an IPv6 address, depending on the platform,
36356 * may or may not result in a listener that also accepts IPv4
36357 * connections. For more deterministic behavior, see
36358 * g_socket_listener_add_inet_port().
36360 * @source_object will be passed out in the various calls
36361 * to accept to identify this particular source, which is
36362 * useful if you're listening on multiple addresses and do
36363 * different things depending on what address is connected to.
36365 * If successful and @effective_address is non-%NULL then it will
36366 * be set to the address that the binding actually occurred at. This
36367 * is helpful for determining the port number that was used for when
36368 * requesting a binding to port 0 (ie: "any port"). This address, if
36369 * requested, belongs to the caller and must be freed.
36371 * Returns: %TRUE on success, %FALSE on error.
36377 * g_socket_listener_add_any_inet_port:
36378 * @listener: a #GSocketListener
36379 * @source_object: (allow-none): Optional #GObject identifying this source
36380 * @error: a #GError location to store the error occurring, or %NULL to
36383 * Listens for TCP connections on any available port number for both
36384 * IPv6 and IPv4 (if each is available).
36386 * This is useful if you need to have a socket for incoming connections
36387 * but don't care about the specific port number.
36389 * @source_object will be passed out in the various calls
36390 * to accept to identify this particular source, which is
36391 * useful if you're listening on multiple addresses and do
36392 * different things depending on what address is connected to.
36394 * Returns: the port number, or 0 in case of failure.
36400 * g_socket_listener_add_inet_port:
36401 * @listener: a #GSocketListener
36402 * @port: an IP port number (non-zero)
36403 * @source_object: (allow-none): Optional #GObject identifying this source
36404 * @error: #GError for error reporting, or %NULL to ignore.
36406 * Helper function for g_socket_listener_add_address() that
36407 * creates a TCP/IP socket listening on IPv4 and IPv6 (if
36408 * supported) on the specified port on all interfaces.
36410 * @source_object will be passed out in the various calls
36411 * to accept to identify this particular source, which is
36412 * useful if you're listening on multiple addresses and do
36413 * different things depending on what address is connected to.
36415 * Returns: %TRUE on success, %FALSE on error.
36421 * g_socket_listener_add_socket:
36422 * @listener: a #GSocketListener
36423 * @socket: a listening #GSocket
36424 * @source_object: (allow-none): Optional #GObject identifying this source
36425 * @error: #GError for error reporting, or %NULL to ignore.
36427 * Adds @socket to the set of sockets that we try to accept
36428 * new clients from. The socket must be bound to a local
36429 * address and listened to.
36431 * @source_object will be passed out in the various calls
36432 * to accept to identify this particular source, which is
36433 * useful if you're listening on multiple addresses and do
36434 * different things depending on what address is connected to.
36436 * The @socket will not be automatically closed when the @listener is finalized
36437 * unless the listener held the final reference to the socket. Before GLib 2.42,
36438 * the @socket was automatically closed on finalization of the @listener, even
36439 * if references to it were held elsewhere.
36441 * Returns: %TRUE on success, %FALSE on error.
36447 * g_socket_listener_close:
36448 * @listener: a #GSocketListener
36450 * Closes all the sockets in the listener.
36457 * g_socket_listener_new:
36459 * Creates a new #GSocketListener with no sockets to listen for.
36460 * New listeners can be added with e.g. g_socket_listener_add_address()
36461 * or g_socket_listener_add_inet_port().
36463 * Returns: a new #GSocketListener.
36469 * g_socket_listener_set_backlog:
36470 * @listener: a #GSocketListener
36471 * @listen_backlog: an integer
36473 * Sets the listen backlog on the sockets in the listener.
36475 * See g_socket_set_listen_backlog() for details
36483 * @family: the socket family to use, e.g. %G_SOCKET_FAMILY_IPV4.
36484 * @type: the socket type to use.
36485 * @protocol: the id of the protocol to use, or 0 for default.
36486 * @error: #GError for error reporting, or %NULL to ignore.
36488 * Creates a new #GSocket with the defined family, type and protocol.
36489 * If @protocol is 0 (%G_SOCKET_PROTOCOL_DEFAULT) the default protocol type
36490 * for the family and type is used.
36492 * The @protocol is a family and type specific int that specifies what
36493 * kind of protocol to use. #GSocketProtocol lists several common ones.
36494 * Many families only support one protocol, and use 0 for this, others
36495 * support several and using 0 means to use the default protocol for
36496 * the family and type.
36498 * The protocol id is passed directly to the operating
36499 * system, so you can use protocols not listed in #GSocketProtocol if you
36500 * know the protocol number used for it.
36502 * Returns: a #GSocket or %NULL on error.
36503 * Free the returned object with g_object_unref().
36509 * g_socket_new_from_fd:
36510 * @fd: a native socket file descriptor.
36511 * @error: #GError for error reporting, or %NULL to ignore.
36513 * Creates a new #GSocket from a native file descriptor
36514 * or winsock SOCKET handle.
36516 * This reads all the settings from the file descriptor so that
36517 * all properties should work. Note that the file descriptor
36518 * will be set to non-blocking mode, independent on the blocking
36519 * mode of the #GSocket.
36521 * On success, the returned #GSocket takes ownership of @fd. On failure, the
36522 * caller must close @fd themselves.
36524 * Since GLib 2.46, it is no longer a fatal error to call this on a non-socket
36525 * descriptor. Instead, a GError will be set with code %G_IO_ERROR_FAILED
36527 * Returns: a #GSocket or %NULL on error.
36528 * Free the returned object with g_object_unref().
36534 * g_socket_receive:
36535 * @socket: a #GSocket
36536 * @buffer: (array length=size) (element-type guint8): a buffer to
36537 * read data into (which should be at least @size bytes long).
36538 * @size: the number of bytes you want to read from the socket
36539 * @cancellable: (allow-none): a %GCancellable or %NULL
36540 * @error: #GError for error reporting, or %NULL to ignore.
36542 * Receive data (up to @size bytes) from a socket. This is mainly used by
36543 * connection-oriented sockets; it is identical to g_socket_receive_from()
36544 * with @address set to %NULL.
36546 * For %G_SOCKET_TYPE_DATAGRAM and %G_SOCKET_TYPE_SEQPACKET sockets,
36547 * g_socket_receive() will always read either 0 or 1 complete messages from
36548 * the socket. If the received message is too large to fit in @buffer, then
36549 * the data beyond @size bytes will be discarded, without any explicit
36550 * indication that this has occurred.
36552 * For %G_SOCKET_TYPE_STREAM sockets, g_socket_receive() can return any
36553 * number of bytes, up to @size. If more than @size bytes have been
36554 * received, the additional data will be returned in future calls to
36555 * g_socket_receive().
36557 * If the socket is in blocking mode the call will block until there
36558 * is some data to receive, the connection is closed, or there is an
36559 * error. If there is no data available and the socket is in
36560 * non-blocking mode, a %G_IO_ERROR_WOULD_BLOCK error will be
36561 * returned. To be notified when data is available, wait for the
36562 * %G_IO_IN condition.
36564 * On error -1 is returned and @error is set accordingly.
36566 * Returns: Number of bytes read, or 0 if the connection was closed by
36567 * the peer, or -1 on error
36573 * g_socket_receive_from:
36574 * @socket: a #GSocket
36575 * @address: (out) (allow-none): a pointer to a #GSocketAddress
36576 * pointer, or %NULL
36577 * @buffer: (array length=size) (element-type guint8): a buffer to
36578 * read data into (which should be at least @size bytes long).
36579 * @size: the number of bytes you want to read from the socket
36580 * @cancellable: (allow-none): a %GCancellable or %NULL
36581 * @error: #GError for error reporting, or %NULL to ignore.
36583 * Receive data (up to @size bytes) from a socket.
36585 * If @address is non-%NULL then @address will be set equal to the
36586 * source address of the received packet.
36587 * @address is owned by the caller.
36589 * See g_socket_receive() for additional information.
36591 * Returns: Number of bytes read, or 0 if the connection was closed by
36592 * the peer, or -1 on error
36598 * g_socket_receive_message:
36599 * @socket: a #GSocket
36600 * @address: (out) (nullable): a pointer to a #GSocketAddress
36601 * pointer, or %NULL
36602 * @vectors: (array length=num_vectors): an array of #GInputVector structs
36603 * @num_vectors: the number of elements in @vectors, or -1
36604 * @messages: (array length=num_messages) (out) (nullable): a pointer which
36605 * may be filled with an array of #GSocketControlMessages, or %NULL
36606 * @num_messages: (out): a pointer which will be filled with the number of
36607 * elements in @messages, or %NULL
36608 * @flags: (inout): a pointer to an int containing #GSocketMsgFlags flags
36609 * @cancellable: a %GCancellable or %NULL
36610 * @error: a #GError pointer, or %NULL
36612 * Receive data from a socket. For receiving multiple messages, see
36613 * g_socket_receive_messages(); for easier use, see
36614 * g_socket_receive() and g_socket_receive_from().
36616 * If @address is non-%NULL then @address will be set equal to the
36617 * source address of the received packet.
36618 * @address is owned by the caller.
36620 * @vector must point to an array of #GInputVector structs and
36621 * @num_vectors must be the length of this array. These structs
36622 * describe the buffers that received data will be scattered into.
36623 * If @num_vectors is -1, then @vectors is assumed to be terminated
36624 * by a #GInputVector with a %NULL buffer pointer.
36626 * As a special case, if @num_vectors is 0 (in which case, @vectors
36627 * may of course be %NULL), then a single byte is received and
36628 * discarded. This is to facilitate the common practice of sending a
36629 * single '\0' byte for the purposes of transferring ancillary data.
36631 * @messages, if non-%NULL, will be set to point to a newly-allocated
36632 * array of #GSocketControlMessage instances or %NULL if no such
36633 * messages was received. These correspond to the control messages
36634 * received from the kernel, one #GSocketControlMessage per message
36635 * from the kernel. This array is %NULL-terminated and must be freed
36636 * by the caller using g_free() after calling g_object_unref() on each
36637 * element. If @messages is %NULL, any control messages received will
36640 * @num_messages, if non-%NULL, will be set to the number of control
36641 * messages received.
36643 * If both @messages and @num_messages are non-%NULL, then
36644 * @num_messages gives the number of #GSocketControlMessage instances
36645 * in @messages (ie: not including the %NULL terminator).
36647 * @flags is an in/out parameter. The commonly available arguments
36648 * for this are available in the #GSocketMsgFlags enum, but the
36649 * values there are the same as the system values, and the flags
36650 * are passed in as-is, so you can pass in system-specific flags too
36651 * (and g_socket_receive_message() may pass system-specific flags out).
36652 * Flags passed in to the parameter affect the receive operation; flags returned
36653 * out of it are relevant to the specific returned message.
36655 * As with g_socket_receive(), data may be discarded if @socket is
36656 * %G_SOCKET_TYPE_DATAGRAM or %G_SOCKET_TYPE_SEQPACKET and you do not
36657 * provide enough buffer space to read a complete message. You can pass
36658 * %G_SOCKET_MSG_PEEK in @flags to peek at the current message without
36659 * removing it from the receive queue, but there is no portable way to find
36660 * out the length of the message other than by reading it into a
36661 * sufficiently-large buffer.
36663 * If the socket is in blocking mode the call will block until there
36664 * is some data to receive, the connection is closed, or there is an
36665 * error. If there is no data available and the socket is in
36666 * non-blocking mode, a %G_IO_ERROR_WOULD_BLOCK error will be
36667 * returned. To be notified when data is available, wait for the
36668 * %G_IO_IN condition.
36670 * On error -1 is returned and @error is set accordingly.
36672 * Returns: Number of bytes read, or 0 if the connection was closed by
36673 * the peer, or -1 on error
36679 * g_socket_receive_messages:
36680 * @socket: a #GSocket
36681 * @messages: (array length=num_messages): an array of #GInputMessage structs
36682 * @num_messages: the number of elements in @messages
36683 * @flags: an int containing #GSocketMsgFlags flags for the overall operation
36684 * @cancellable: (allow-none): a %GCancellable or %NULL
36685 * @error: #GError for error reporting, or %NULL to ignore
36687 * Receive multiple data messages from @socket in one go. This is the most
36688 * complicated and fully-featured version of this call. For easier use, see
36689 * g_socket_receive(), g_socket_receive_from(), and g_socket_receive_message().
36691 * @messages must point to an array of #GInputMessage structs and
36692 * @num_messages must be the length of this array. Each #GInputMessage
36693 * contains a pointer to an array of #GInputVector structs describing the
36694 * buffers that the data received in each message will be written to. Using
36695 * multiple #GInputVectors is more memory-efficient than manually copying data
36696 * out of a single buffer to multiple sources, and more system-call-efficient
36697 * than making multiple calls to g_socket_receive(), such as in scenarios where
36698 * a lot of data packets need to be received (e.g. high-bandwidth video
36699 * streaming over RTP/UDP).
36701 * @flags modify how all messages are received. The commonly available
36702 * arguments for this are available in the #GSocketMsgFlags enum, but the
36703 * values there are the same as the system values, and the flags
36704 * are passed in as-is, so you can pass in system-specific flags too. These
36705 * flags affect the overall receive operation. Flags affecting individual
36706 * messages are returned in #GInputMessage.flags.
36708 * The other members of #GInputMessage are treated as described in its
36711 * If #GSocket:blocking is %TRUE the call will block until @num_messages have
36712 * been received, or the end of the stream is reached.
36714 * If #GSocket:blocking is %FALSE the call will return up to @num_messages
36715 * without blocking, or %G_IO_ERROR_WOULD_BLOCK if no messages are queued in the
36716 * operating system to be received.
36718 * In blocking mode, if #GSocket:timeout is positive and is reached before any
36719 * messages are received, %G_IO_ERROR_TIMED_OUT is returned, otherwise up to
36720 * @num_messages are returned. (Note: This is effectively the
36721 * behaviour of `MSG_WAITFORONE` with recvmmsg().)
36723 * To be notified when messages are available, wait for the
36724 * %G_IO_IN condition. Note though that you may still receive
36725 * %G_IO_ERROR_WOULD_BLOCK from g_socket_receive_messages() even if you were
36726 * previously notified of a %G_IO_IN condition.
36728 * If the remote peer closes the connection, any messages queued in the
36729 * operating system will be returned, and subsequent calls to
36730 * g_socket_receive_messages() will return 0 (with no error set).
36732 * On error -1 is returned and @error is set accordingly. An error will only
36733 * be returned if zero messages could be received; otherwise the number of
36734 * messages successfully received before the error will be returned.
36736 * Returns: number of messages received, or -1 on error. Note that the number
36737 * of messages received may be smaller than @num_messages if in non-blocking
36738 * mode, if the peer closed the connection, or if @num_messages
36739 * was larger than `UIO_MAXIOV` (1024), in which case the caller may re-try
36740 * to receive the remaining messages.
36746 * g_socket_receive_with_blocking:
36747 * @socket: a #GSocket
36748 * @buffer: (array length=size) (element-type guint8): a buffer to
36749 * read data into (which should be at least @size bytes long).
36750 * @size: the number of bytes you want to read from the socket
36751 * @blocking: whether to do blocking or non-blocking I/O
36752 * @cancellable: (allow-none): a %GCancellable or %NULL
36753 * @error: #GError for error reporting, or %NULL to ignore.
36755 * This behaves exactly the same as g_socket_receive(), except that
36756 * the choice of blocking or non-blocking behavior is determined by
36757 * the @blocking argument rather than by @socket's properties.
36759 * Returns: Number of bytes read, or 0 if the connection was closed by
36760 * the peer, or -1 on error
36767 * @socket: a #GSocket
36768 * @buffer: (array length=size) (element-type guint8): the buffer
36769 * containing the data to send.
36770 * @size: the number of bytes to send
36771 * @cancellable: (allow-none): a %GCancellable or %NULL
36772 * @error: #GError for error reporting, or %NULL to ignore.
36774 * Tries to send @size bytes from @buffer on the socket. This is
36775 * mainly used by connection-oriented sockets; it is identical to
36776 * g_socket_send_to() with @address set to %NULL.
36778 * If the socket is in blocking mode the call will block until there is
36779 * space for the data in the socket queue. If there is no space available
36780 * and the socket is in non-blocking mode a %G_IO_ERROR_WOULD_BLOCK error
36781 * will be returned. To be notified when space is available, wait for the
36782 * %G_IO_OUT condition. Note though that you may still receive
36783 * %G_IO_ERROR_WOULD_BLOCK from g_socket_send() even if you were previously
36784 * notified of a %G_IO_OUT condition. (On Windows in particular, this is
36785 * very common due to the way the underlying APIs work.)
36787 * On error -1 is returned and @error is set accordingly.
36789 * Returns: Number of bytes written (which may be less than @size), or -1
36796 * g_socket_send_message:
36797 * @socket: a #GSocket
36798 * @address: (allow-none): a #GSocketAddress, or %NULL
36799 * @vectors: (array length=num_vectors): an array of #GOutputVector structs
36800 * @num_vectors: the number of elements in @vectors, or -1
36801 * @messages: (array length=num_messages) (allow-none): a pointer to an
36802 * array of #GSocketControlMessages, or %NULL.
36803 * @num_messages: number of elements in @messages, or -1.
36804 * @flags: an int containing #GSocketMsgFlags flags
36805 * @cancellable: (allow-none): a %GCancellable or %NULL
36806 * @error: #GError for error reporting, or %NULL to ignore.
36808 * Send data to @address on @socket. For sending multiple messages see
36809 * g_socket_send_messages(); for easier use, see
36810 * g_socket_send() and g_socket_send_to().
36812 * If @address is %NULL then the message is sent to the default receiver
36813 * (set by g_socket_connect()).
36815 * @vectors must point to an array of #GOutputVector structs and
36816 * @num_vectors must be the length of this array. (If @num_vectors is -1,
36817 * then @vectors is assumed to be terminated by a #GOutputVector with a
36818 * %NULL buffer pointer.) The #GOutputVector structs describe the buffers
36819 * that the sent data will be gathered from. Using multiple
36820 * #GOutputVectors is more memory-efficient than manually copying
36821 * data from multiple sources into a single buffer, and more
36822 * network-efficient than making multiple calls to g_socket_send().
36824 * @messages, if non-%NULL, is taken to point to an array of @num_messages
36825 * #GSocketControlMessage instances. These correspond to the control
36826 * messages to be sent on the socket.
36827 * If @num_messages is -1 then @messages is treated as a %NULL-terminated
36830 * @flags modify how the message is sent. The commonly available arguments
36831 * for this are available in the #GSocketMsgFlags enum, but the
36832 * values there are the same as the system values, and the flags
36833 * are passed in as-is, so you can pass in system-specific flags too.
36835 * If the socket is in blocking mode the call will block until there is
36836 * space for the data in the socket queue. If there is no space available
36837 * and the socket is in non-blocking mode a %G_IO_ERROR_WOULD_BLOCK error
36838 * will be returned. To be notified when space is available, wait for the
36839 * %G_IO_OUT condition. Note though that you may still receive
36840 * %G_IO_ERROR_WOULD_BLOCK from g_socket_send() even if you were previously
36841 * notified of a %G_IO_OUT condition. (On Windows in particular, this is
36842 * very common due to the way the underlying APIs work.)
36844 * On error -1 is returned and @error is set accordingly.
36846 * Returns: Number of bytes written (which may be less than @size), or -1
36853 * g_socket_send_messages:
36854 * @socket: a #GSocket
36855 * @messages: (array length=num_messages): an array of #GOutputMessage structs
36856 * @num_messages: the number of elements in @messages
36857 * @flags: an int containing #GSocketMsgFlags flags
36858 * @cancellable: (allow-none): a %GCancellable or %NULL
36859 * @error: #GError for error reporting, or %NULL to ignore.
36861 * Send multiple data messages from @socket in one go. This is the most
36862 * complicated and fully-featured version of this call. For easier use, see
36863 * g_socket_send(), g_socket_send_to(), and g_socket_send_message().
36865 * @messages must point to an array of #GOutputMessage structs and
36866 * @num_messages must be the length of this array. Each #GOutputMessage
36867 * contains an address to send the data to, and a pointer to an array of
36868 * #GOutputVector structs to describe the buffers that the data to be sent
36869 * for each message will be gathered from. Using multiple #GOutputVectors is
36870 * more memory-efficient than manually copying data from multiple sources
36871 * into a single buffer, and more network-efficient than making multiple
36872 * calls to g_socket_send(). Sending multiple messages in one go avoids the
36873 * overhead of making a lot of syscalls in scenarios where a lot of data
36874 * packets need to be sent (e.g. high-bandwidth video streaming over RTP/UDP),
36875 * or where the same data needs to be sent to multiple recipients.
36877 * @flags modify how the message is sent. The commonly available arguments
36878 * for this are available in the #GSocketMsgFlags enum, but the
36879 * values there are the same as the system values, and the flags
36880 * are passed in as-is, so you can pass in system-specific flags too.
36882 * If the socket is in blocking mode the call will block until there is
36883 * space for all the data in the socket queue. If there is no space available
36884 * and the socket is in non-blocking mode a %G_IO_ERROR_WOULD_BLOCK error
36885 * will be returned if no data was written at all, otherwise the number of
36886 * messages sent will be returned. To be notified when space is available,
36887 * wait for the %G_IO_OUT condition. Note though that you may still receive
36888 * %G_IO_ERROR_WOULD_BLOCK from g_socket_send() even if you were previously
36889 * notified of a %G_IO_OUT condition. (On Windows in particular, this is
36890 * very common due to the way the underlying APIs work.)
36892 * On error -1 is returned and @error is set accordingly. An error will only
36893 * be returned if zero messages could be sent; otherwise the number of messages
36894 * successfully sent before the error will be returned.
36896 * Returns: number of messages sent, or -1 on error. Note that the number of
36897 * messages sent may be smaller than @num_messages if the socket is
36898 * non-blocking or if @num_messages was larger than UIO_MAXIOV (1024),
36899 * in which case the caller may re-try to send the remaining messages.
36905 * g_socket_send_to:
36906 * @socket: a #GSocket
36907 * @address: (allow-none): a #GSocketAddress, or %NULL
36908 * @buffer: (array length=size) (element-type guint8): the buffer
36909 * containing the data to send.
36910 * @size: the number of bytes to send
36911 * @cancellable: (allow-none): a %GCancellable or %NULL
36912 * @error: #GError for error reporting, or %NULL to ignore.
36914 * Tries to send @size bytes from @buffer to @address. If @address is
36915 * %NULL then the message is sent to the default receiver (set by
36916 * g_socket_connect()).
36918 * See g_socket_send() for additional information.
36920 * Returns: Number of bytes written (which may be less than @size), or -1
36927 * g_socket_send_with_blocking:
36928 * @socket: a #GSocket
36929 * @buffer: (array length=size) (element-type guint8): the buffer
36930 * containing the data to send.
36931 * @size: the number of bytes to send
36932 * @blocking: whether to do blocking or non-blocking I/O
36933 * @cancellable: (allow-none): a %GCancellable or %NULL
36934 * @error: #GError for error reporting, or %NULL to ignore.
36936 * This behaves exactly the same as g_socket_send(), except that
36937 * the choice of blocking or non-blocking behavior is determined by
36938 * the @blocking argument rather than by @socket's properties.
36940 * Returns: Number of bytes written (which may be less than @size), or -1
36947 * g_socket_service_is_active:
36948 * @service: a #GSocketService
36950 * Check whether the service is active or not. An active
36951 * service will accept new clients that connect, while
36952 * a non-active service will let connecting clients queue
36953 * up until the service is started.
36955 * Returns: %TRUE if the service is active, %FALSE otherwise
36961 * g_socket_service_new:
36963 * Creates a new #GSocketService with no sockets to listen for.
36964 * New listeners can be added with e.g. g_socket_listener_add_address()
36965 * or g_socket_listener_add_inet_port().
36967 * New services are created active, there is no need to call
36968 * g_socket_service_start(), unless g_socket_service_stop() has been
36971 * Returns: a new #GSocketService.
36977 * g_socket_service_start:
36978 * @service: a #GSocketService
36980 * Restarts the service, i.e. start accepting connections
36981 * from the added sockets when the mainloop runs. This only needs
36982 * to be called after the service has been stopped from
36983 * g_socket_service_stop().
36985 * This call is thread-safe, so it may be called from a thread
36986 * handling an incoming client request.
36993 * g_socket_service_stop:
36994 * @service: a #GSocketService
36996 * Stops the service, i.e. stops accepting connections
36997 * from the added sockets when the mainloop runs.
36999 * This call is thread-safe, so it may be called from a thread
37000 * handling an incoming client request.
37002 * Note that this only stops accepting new connections; it does not
37003 * close the listening sockets, and you can call
37004 * g_socket_service_start() again later to begin listening again. To
37005 * close the listening sockets, call g_socket_listener_close(). (This
37006 * will happen automatically when the #GSocketService is finalized.)
37008 * This must be called before calling g_socket_listener_close() as
37009 * the socket service will start accepting connections immediately
37010 * when a new socket is added.
37017 * g_socket_set_blocking:
37018 * @socket: a #GSocket.
37019 * @blocking: Whether to use blocking I/O or not.
37021 * Sets the blocking mode of the socket. In blocking mode
37022 * all operations (which don’t take an explicit blocking parameter) block until
37023 * they succeed or there is an error. In
37024 * non-blocking mode all functions return results immediately or
37025 * with a %G_IO_ERROR_WOULD_BLOCK error.
37027 * All sockets are created in blocking mode. However, note that the
37028 * platform level socket is always non-blocking, and blocking mode
37029 * is a GSocket level feature.
37036 * g_socket_set_broadcast:
37037 * @socket: a #GSocket.
37038 * @broadcast: whether @socket should allow sending to broadcast
37041 * Sets whether @socket should allow sending to broadcast addresses.
37042 * This is %FALSE by default.
37049 * g_socket_set_keepalive:
37050 * @socket: a #GSocket.
37051 * @keepalive: Value for the keepalive flag
37053 * Sets or unsets the %SO_KEEPALIVE flag on the underlying socket. When
37054 * this flag is set on a socket, the system will attempt to verify that the
37055 * remote socket endpoint is still present if a sufficiently long period of
37056 * time passes with no data being exchanged. If the system is unable to
37057 * verify the presence of the remote endpoint, it will automatically close
37060 * This option is only functional on certain kinds of sockets. (Notably,
37061 * %G_SOCKET_PROTOCOL_TCP sockets.)
37063 * The exact time between pings is system- and protocol-dependent, but will
37064 * normally be at least two hours. Most commonly, you would set this flag
37065 * on a server socket if you want to allow clients to remain idle for long
37066 * periods of time, but also want to ensure that connections are eventually
37067 * garbage-collected if clients crash or become unreachable.
37074 * g_socket_set_listen_backlog:
37075 * @socket: a #GSocket.
37076 * @backlog: the maximum number of pending connections.
37078 * Sets the maximum number of outstanding connections allowed
37079 * when listening on this socket. If more clients than this are
37080 * connecting to the socket and the application is not handling them
37081 * on time then the new connections will be refused.
37083 * Note that this must be called before g_socket_listen() and has no
37084 * effect if called after that.
37091 * g_socket_set_multicast_loopback:
37092 * @socket: a #GSocket.
37093 * @loopback: whether @socket should receive messages sent to its
37094 * multicast groups from the local host
37096 * Sets whether outgoing multicast packets will be received by sockets
37097 * listening on that multicast address on the same host. This is %TRUE
37105 * g_socket_set_multicast_ttl:
37106 * @socket: a #GSocket.
37107 * @ttl: the time-to-live value for all multicast datagrams on @socket
37109 * Sets the time-to-live for outgoing multicast datagrams on @socket.
37110 * By default, this is 1, meaning that multicast packets will not leave
37111 * the local network.
37118 * g_socket_set_option:
37119 * @socket: a #GSocket
37120 * @level: the "API level" of the option (eg, `SOL_SOCKET`)
37121 * @optname: the "name" of the option (eg, `SO_BROADCAST`)
37122 * @value: the value to set the option to
37123 * @error: #GError for error reporting, or %NULL to ignore.
37125 * Sets the value of an integer-valued option on @socket, as with
37126 * setsockopt(). (If you need to set a non-integer-valued option,
37127 * you will need to call setsockopt() directly.)
37129 * The [<gio/gnetworking.h>][gio-gnetworking.h]
37130 * header pulls in system headers that will define most of the
37131 * standard/portable socket options. For unusual socket protocols or
37132 * platform-dependent options, you may need to include additional
37135 * Returns: success or failure. On failure, @error will be set, and
37136 * the system error value (`errno` or WSAGetLastError()) will still
37137 * be set to the result of the setsockopt() call.
37143 * g_socket_set_timeout:
37144 * @socket: a #GSocket.
37145 * @timeout: the timeout for @socket, in seconds, or 0 for none
37147 * Sets the time in seconds after which I/O operations on @socket will
37148 * time out if they have not yet completed.
37150 * On a blocking socket, this means that any blocking #GSocket
37151 * operation will time out after @timeout seconds of inactivity,
37152 * returning %G_IO_ERROR_TIMED_OUT.
37154 * On a non-blocking socket, calls to g_socket_condition_wait() will
37155 * also fail with %G_IO_ERROR_TIMED_OUT after the given time. Sources
37156 * created with g_socket_create_source() will trigger after
37157 * @timeout seconds of inactivity, with the requested condition
37158 * set, at which point calling g_socket_receive(), g_socket_send(),
37159 * g_socket_check_connect_result(), etc, will fail with
37160 * %G_IO_ERROR_TIMED_OUT.
37162 * If @timeout is 0 (the default), operations will never time out
37165 * Note that if an I/O operation is interrupted by a signal, this may
37166 * cause the timeout to be reset.
37173 * g_socket_set_ttl:
37174 * @socket: a #GSocket.
37175 * @ttl: the time-to-live value for all unicast packets on @socket
37177 * Sets the time-to-live for outgoing unicast packets on @socket.
37178 * By default the platform-specific default value is used.
37185 * g_socket_shutdown:
37186 * @socket: a #GSocket
37187 * @shutdown_read: whether to shut down the read side
37188 * @shutdown_write: whether to shut down the write side
37189 * @error: #GError for error reporting, or %NULL to ignore.
37191 * Shut down part or all of a full-duplex connection.
37193 * If @shutdown_read is %TRUE then the receiving side of the connection
37194 * is shut down, and further reading is disallowed.
37196 * If @shutdown_write is %TRUE then the sending side of the connection
37197 * is shut down, and further writing is disallowed.
37199 * It is allowed for both @shutdown_read and @shutdown_write to be %TRUE.
37201 * One example where it is useful to shut down only one side of a connection is
37202 * graceful disconnect for TCP connections where you close the sending side,
37203 * then wait for the other side to close the connection, thus ensuring that the
37204 * other side saw all sent data.
37206 * Returns: %TRUE on success, %FALSE on error
37212 * g_socket_speaks_ipv4:
37213 * @socket: a #GSocket
37215 * Checks if a socket is capable of speaking IPv4.
37217 * IPv4 sockets are capable of speaking IPv4. On some operating systems
37218 * and under some combinations of circumstances IPv6 sockets are also
37219 * capable of speaking IPv4. See RFC 3493 section 3.7 for more
37222 * No other types of sockets are currently considered as being capable
37223 * of speaking IPv4.
37225 * Returns: %TRUE if this socket can be used with IPv4.
37231 * g_srv_target_copy:
37232 * @target: a #GSrvTarget
37236 * Returns: a copy of @target
37242 * g_srv_target_free:
37243 * @target: a #GSrvTarget
37252 * g_srv_target_get_hostname:
37253 * @target: a #GSrvTarget
37255 * Gets @target's hostname (in ASCII form; if you are going to present
37256 * this to the user, you should use g_hostname_is_ascii_encoded() to
37257 * check if it contains encoded Unicode segments, and use
37258 * g_hostname_to_unicode() to convert it if it does.)
37260 * Returns: @target's hostname
37266 * g_srv_target_get_port:
37267 * @target: a #GSrvTarget
37269 * Gets @target's port
37271 * Returns: @target's port
37277 * g_srv_target_get_priority:
37278 * @target: a #GSrvTarget
37280 * Gets @target's priority. You should not need to look at this;
37281 * #GResolver already sorts the targets according to the algorithm in
37284 * Returns: @target's priority
37290 * g_srv_target_get_weight:
37291 * @target: a #GSrvTarget
37293 * Gets @target's weight. You should not need to look at this;
37294 * #GResolver already sorts the targets according to the algorithm in
37297 * Returns: @target's weight
37303 * g_srv_target_list_sort: (skip)
37304 * @targets: a #GList of #GSrvTarget
37306 * Sorts @targets in place according to the algorithm in RFC 2782.
37308 * Returns: (transfer full): the head of the sorted list.
37314 * g_srv_target_new:
37315 * @hostname: the host that the service is running on
37316 * @port: the port that the service is running on
37317 * @priority: the target's priority
37318 * @weight: the target's weight
37320 * Creates a new #GSrvTarget with the given parameters.
37322 * You should not need to use this; normally #GSrvTargets are
37323 * created by #GResolver.
37325 * Returns: a new #GSrvTarget.
37331 * g_static_resource_fini:
37332 * @static_resource: pointer to a static #GStaticResource
37334 * Finalized a GResource initialized by g_static_resource_init().
37336 * This is normally used by code generated by
37337 * [glib-compile-resources][glib-compile-resources]
37338 * and is not typically used by other code.
37345 * g_static_resource_get_resource:
37346 * @static_resource: pointer to a static #GStaticResource
37348 * Gets the GResource that was registered by a call to g_static_resource_init().
37350 * This is normally used by code generated by
37351 * [glib-compile-resources][glib-compile-resources]
37352 * and is not typically used by other code.
37354 * Returns: (transfer none): a #GResource
37360 * g_static_resource_init:
37361 * @static_resource: pointer to a static #GStaticResource
37363 * Initializes a GResource from static data using a
37366 * This is normally used by code generated by
37367 * [glib-compile-resources][glib-compile-resources]
37368 * and is not typically used by other code.
37375 * g_subprocess_communicate:
37376 * @subprocess: a #GSubprocess
37377 * @stdin_buf: (allow-none): data to send to the stdin of the subprocess, or %NULL
37378 * @cancellable: a #GCancellable
37379 * @stdout_buf: (out): data read from the subprocess stdout
37380 * @stderr_buf: (out): data read from the subprocess stderr
37381 * @error: a pointer to a %NULL #GError pointer, or %NULL
37383 * Communicate with the subprocess until it terminates, and all input
37384 * and output has been completed.
37386 * If @stdin_buf is given, the subprocess must have been created with
37387 * %G_SUBPROCESS_FLAGS_STDIN_PIPE. The given data is fed to the
37388 * stdin of the subprocess and the pipe is closed (ie: EOF).
37390 * At the same time (as not to cause blocking when dealing with large
37391 * amounts of data), if %G_SUBPROCESS_FLAGS_STDOUT_PIPE or
37392 * %G_SUBPROCESS_FLAGS_STDERR_PIPE were used, reads from those
37393 * streams. The data that was read is returned in @stdout and/or
37396 * If the subprocess was created with %G_SUBPROCESS_FLAGS_STDOUT_PIPE,
37397 * @stdout_buf will contain the data read from stdout. Otherwise, for
37398 * subprocesses not created with %G_SUBPROCESS_FLAGS_STDOUT_PIPE,
37399 * @stdout_buf will be set to %NULL. Similar provisions apply to
37400 * @stderr_buf and %G_SUBPROCESS_FLAGS_STDERR_PIPE.
37402 * As usual, any output variable may be given as %NULL to ignore it.
37404 * If you desire the stdout and stderr data to be interleaved, create
37405 * the subprocess with %G_SUBPROCESS_FLAGS_STDOUT_PIPE and
37406 * %G_SUBPROCESS_FLAGS_STDERR_MERGE. The merged result will be returned
37407 * in @stdout_buf and @stderr_buf will be set to %NULL.
37409 * In case of any error (including cancellation), %FALSE will be
37410 * returned with @error set. Some or all of the stdin data may have
37411 * been written. Any stdout or stderr data that has been read will be
37412 * discarded. None of the out variables (aside from @error) will have
37413 * been set to anything in particular and should not be inspected.
37415 * In the case that %TRUE is returned, the subprocess has exited and the
37416 * exit status inspection APIs (eg: g_subprocess_get_if_exited(),
37417 * g_subprocess_get_exit_status()) may be used.
37419 * You should not attempt to use any of the subprocess pipes after
37420 * starting this function, since they may be left in strange states,
37421 * even if the operation was cancelled. You should especially not
37422 * attempt to interact with the pipes while the operation is in progress
37423 * (either from another thread or if using the asynchronous version).
37425 * Returns: %TRUE if successful
37431 * g_subprocess_communicate_async:
37432 * @subprocess: Self
37433 * @stdin_buf: (allow-none): Input data, or %NULL
37434 * @cancellable: (allow-none): Cancellable
37435 * @callback: Callback
37436 * @user_data: User data
37438 * Asynchronous version of g_subprocess_communicate(). Complete
37439 * invocation with g_subprocess_communicate_finish().
37444 * g_subprocess_communicate_finish:
37445 * @subprocess: Self
37447 * @stdout_buf: (out): Return location for stdout data
37448 * @stderr_buf: (out): Return location for stderr data
37451 * Complete an invocation of g_subprocess_communicate_async().
37456 * g_subprocess_communicate_utf8:
37457 * @subprocess: a #GSubprocess
37458 * @stdin_buf: (allow-none): data to send to the stdin of the subprocess, or %NULL
37459 * @cancellable: a #GCancellable
37460 * @stdout_buf: (out): data read from the subprocess stdout
37461 * @stderr_buf: (out): data read from the subprocess stderr
37462 * @error: a pointer to a %NULL #GError pointer, or %NULL
37464 * Like g_subprocess_communicate(), but validates the output of the
37465 * process as UTF-8, and returns it as a regular NUL terminated string.
37470 * g_subprocess_communicate_utf8_async:
37471 * @subprocess: Self
37472 * @stdin_buf: (allow-none): Input data, or %NULL
37473 * @cancellable: Cancellable
37474 * @callback: Callback
37475 * @user_data: User data
37477 * Asynchronous version of g_subprocess_communicate_utf8(). Complete
37478 * invocation with g_subprocess_communicate_utf8_finish().
37483 * g_subprocess_communicate_utf8_finish:
37484 * @subprocess: Self
37486 * @stdout_buf: (out): Return location for stdout data
37487 * @stderr_buf: (out): Return location for stderr data
37490 * Complete an invocation of g_subprocess_communicate_utf8_async().
37495 * g_subprocess_force_exit:
37496 * @subprocess: a #GSubprocess
37498 * Use an operating-system specific method to attempt an immediate,
37499 * forceful termination of the process. There is no mechanism to
37500 * determine whether or not the request itself was successful;
37501 * however, you can use g_subprocess_wait() to monitor the status of
37502 * the process after calling this function.
37504 * On Unix, this function sends %SIGKILL.
37511 * g_subprocess_get_exit_status:
37512 * @subprocess: a #GSubprocess
37514 * Check the exit status of the subprocess, given that it exited
37515 * normally. This is the value passed to the exit() system call or the
37516 * return value from main.
37518 * This is equivalent to the system WEXITSTATUS macro.
37520 * It is an error to call this function before g_subprocess_wait() and
37521 * unless g_subprocess_get_if_exited() returned %TRUE.
37523 * Returns: the exit status
37529 * g_subprocess_get_identifier:
37530 * @subprocess: a #GSubprocess
37532 * On UNIX, returns the process ID as a decimal string.
37533 * On Windows, returns the result of GetProcessId() also as a string.
37538 * g_subprocess_get_if_exited:
37539 * @subprocess: a #GSubprocess
37541 * Check if the given subprocess exited normally (ie: by way of exit()
37542 * or return from main()).
37544 * This is equivalent to the system WIFEXITED macro.
37546 * It is an error to call this function before g_subprocess_wait() has
37549 * Returns: %TRUE if the case of a normal exit
37555 * g_subprocess_get_if_signaled:
37556 * @subprocess: a #GSubprocess
37558 * Check if the given subprocess terminated in response to a signal.
37560 * This is equivalent to the system WIFSIGNALED macro.
37562 * It is an error to call this function before g_subprocess_wait() has
37565 * Returns: %TRUE if the case of termination due to a signal
37571 * g_subprocess_get_status:
37572 * @subprocess: a #GSubprocess
37574 * Gets the raw status code of the process, as from waitpid().
37576 * This value has no particular meaning, but it can be used with the
37577 * macros defined by the system headers such as WIFEXITED. It can also
37578 * be used with g_spawn_check_exit_status().
37580 * It is more likely that you want to use g_subprocess_get_if_exited()
37581 * followed by g_subprocess_get_exit_status().
37583 * It is an error to call this function before g_subprocess_wait() has
37586 * Returns: the (meaningless) waitpid() exit status from the kernel
37592 * g_subprocess_get_stderr_pipe:
37593 * @subprocess: a #GSubprocess
37595 * Gets the #GInputStream from which to read the stderr output of
37598 * The process must have been created with
37599 * %G_SUBPROCESS_FLAGS_STDERR_PIPE.
37601 * Returns: (transfer none): the stderr pipe
37607 * g_subprocess_get_stdin_pipe:
37608 * @subprocess: a #GSubprocess
37610 * Gets the #GOutputStream that you can write to in order to give data
37611 * to the stdin of @subprocess.
37613 * The process must have been created with
37614 * %G_SUBPROCESS_FLAGS_STDIN_PIPE.
37616 * Returns: (transfer none): the stdout pipe
37622 * g_subprocess_get_stdout_pipe:
37623 * @subprocess: a #GSubprocess
37625 * Gets the #GInputStream from which to read the stdout output of
37628 * The process must have been created with
37629 * %G_SUBPROCESS_FLAGS_STDOUT_PIPE.
37631 * Returns: (transfer none): the stdout pipe
37637 * g_subprocess_get_successful:
37638 * @subprocess: a #GSubprocess
37640 * Checks if the process was "successful". A process is considered
37641 * successful if it exited cleanly with an exit status of 0, either by
37642 * way of the exit() system call or return from main().
37644 * It is an error to call this function before g_subprocess_wait() has
37647 * Returns: %TRUE if the process exited cleanly with a exit status of 0
37653 * g_subprocess_get_term_sig:
37654 * @subprocess: a #GSubprocess
37656 * Get the signal number that caused the subprocess to terminate, given
37657 * that it terminated due to a signal.
37659 * This is equivalent to the system WTERMSIG macro.
37661 * It is an error to call this function before g_subprocess_wait() and
37662 * unless g_subprocess_get_if_signaled() returned %TRUE.
37664 * Returns: the signal causing termination
37670 * g_subprocess_launcher_getenv:
37671 * @self: a #GSubprocess
37672 * @variable: the environment variable to get
37674 * Returns the value of the environment variable @variable in the
37675 * environment of processes launched from this launcher.
37677 * On UNIX, the returned string can be an arbitrary byte string.
37678 * On Windows, it will be UTF-8.
37680 * Returns: the value of the environment variable, %NULL if unset
37686 * g_subprocess_launcher_new:
37687 * @flags: #GSubprocessFlags
37689 * Creates a new #GSubprocessLauncher.
37691 * The launcher is created with the default options. A copy of the
37692 * environment of the calling process is made at the time of this call
37693 * and will be used as the environment that the process is launched in.
37700 * g_subprocess_launcher_set_child_setup:
37701 * @self: a #GSubprocessLauncher
37702 * @child_setup: a #GSpawnChildSetupFunc to use as the child setup function
37703 * @user_data: user data for @child_setup
37704 * @destroy_notify: a #GDestroyNotify for @user_data
37706 * Sets up a child setup function.
37708 * The child setup function will be called after fork() but before
37709 * exec() on the child's side.
37711 * @destroy_notify will not be automatically called on the child's side
37712 * of the fork(). It will only be called when the last reference on the
37713 * #GSubprocessLauncher is dropped or when a new child setup function is
37716 * %NULL can be given as @child_setup to disable the functionality.
37718 * Child setup functions are only available on UNIX.
37725 * g_subprocess_launcher_set_cwd:
37726 * @self: a #GSubprocess
37727 * @cwd: (type filename): the cwd for launched processes
37729 * Sets the current working directory that processes will be launched
37732 * By default processes are launched with the current working directory
37733 * of the launching process at the time of launch.
37740 * g_subprocess_launcher_set_environ:
37741 * @self: a #GSubprocess
37742 * @env: the replacement environment
37744 * Replace the entire environment of processes launched from this
37745 * launcher with the given 'environ' variable.
37747 * Typically you will build this variable by using g_listenv() to copy
37748 * the process 'environ' and using the functions g_environ_setenv(),
37749 * g_environ_unsetenv(), etc.
37751 * As an alternative, you can use g_subprocess_launcher_setenv(),
37752 * g_subprocess_launcher_unsetenv(), etc.
37754 * On UNIX, all strings in this array can be arbitrary byte strings.
37755 * On Windows, they should be in UTF-8.
37762 * g_subprocess_launcher_set_flags:
37763 * @self: a #GSubprocessLauncher
37764 * @flags: #GSubprocessFlags
37766 * Sets the flags on the launcher.
37768 * The default flags are %G_SUBPROCESS_FLAGS_NONE.
37770 * You may not set flags that specify conflicting options for how to
37771 * handle a particular stdio stream (eg: specifying both
37772 * %G_SUBPROCESS_FLAGS_STDIN_PIPE and
37773 * %G_SUBPROCESS_FLAGS_STDIN_INHERIT).
37775 * You may also not set a flag that conflicts with a previous call to a
37776 * function like g_subprocess_launcher_set_stdin_file_path() or
37777 * g_subprocess_launcher_take_stdout_fd().
37784 * g_subprocess_launcher_set_stderr_file_path:
37785 * @self: a #GSubprocessLauncher
37786 * @path: (type filename) (nullable): a filename or %NULL
37788 * Sets the file path to use as the stderr for spawned processes.
37790 * If @path is %NULL then any previously given path is unset.
37792 * The file will be created or truncated when the process is spawned, as
37793 * would be the case if using '2>' at the shell.
37795 * If you want to send both stdout and stderr to the same file then use
37796 * %G_SUBPROCESS_FLAGS_STDERR_MERGE.
37798 * You may not set a stderr file path if a stderr fd is already set or
37799 * if the launcher flags contain any flags directing stderr elsewhere.
37801 * This feature is only available on UNIX.
37808 * g_subprocess_launcher_set_stdin_file_path:
37809 * @self: a #GSubprocessLauncher
37812 * Sets the file path to use as the stdin for spawned processes.
37814 * If @path is %NULL then any previously given path is unset.
37816 * The file must exist or spawning the process will fail.
37818 * You may not set a stdin file path if a stdin fd is already set or if
37819 * the launcher flags contain any flags directing stdin elsewhere.
37821 * This feature is only available on UNIX.
37828 * g_subprocess_launcher_set_stdout_file_path:
37829 * @self: a #GSubprocessLauncher
37830 * @path: (type filename) (nullable): a filename or %NULL
37832 * Sets the file path to use as the stdout for spawned processes.
37834 * If @path is %NULL then any previously given path is unset.
37836 * The file will be created or truncated when the process is spawned, as
37837 * would be the case if using '>' at the shell.
37839 * You may not set a stdout file path if a stdout fd is already set or
37840 * if the launcher flags contain any flags directing stdout elsewhere.
37842 * This feature is only available on UNIX.
37849 * g_subprocess_launcher_setenv:
37850 * @self: a #GSubprocess
37851 * @variable: the environment variable to set, must not contain '='
37852 * @value: the new value for the variable
37853 * @overwrite: whether to change the variable if it already exists
37855 * Sets the environment variable @variable in the environment of
37856 * processes launched from this launcher.
37858 * On UNIX, both the variable's name and value can be arbitrary byte
37859 * strings, except that the variable's name cannot contain '='.
37860 * On Windows, they should be in UTF-8.
37867 * g_subprocess_launcher_spawn:
37868 * @self: a #GSubprocessLauncher
37870 * @argv0: Command line arguments
37871 * @...: Continued arguments, %NULL terminated
37873 * Creates a #GSubprocess given a provided varargs list of arguments.
37876 * Returns: (transfer full): A new #GSubprocess, or %NULL on error (and @error will be set)
37881 * g_subprocess_launcher_spawnv:
37882 * @self: a #GSubprocessLauncher
37883 * @argv: (array zero-terminated=1) (element-type utf8): Command line arguments
37886 * Creates a #GSubprocess given a provided array of arguments.
37889 * Returns: (transfer full): A new #GSubprocess, or %NULL on error (and @error will be set)
37894 * g_subprocess_launcher_take_fd:
37895 * @self: a #GSubprocessLauncher
37896 * @source_fd: File descriptor in parent process
37897 * @target_fd: Target descriptor for child process
37899 * Transfer an arbitrary file descriptor from parent process to the
37900 * child. This function takes "ownership" of the fd; it will be closed
37901 * in the parent when @self is freed.
37903 * By default, all file descriptors from the parent will be closed.
37904 * This function allows you to create (for example) a custom pipe() or
37905 * socketpair() before launching the process, and choose the target
37906 * descriptor in the child.
37908 * An example use case is GNUPG, which has a command line argument
37909 * --passphrase-fd providing a file descriptor number where it expects
37910 * the passphrase to be written.
37915 * g_subprocess_launcher_take_stderr_fd:
37916 * @self: a #GSubprocessLauncher
37917 * @fd: a file descriptor, or -1
37919 * Sets the file descriptor to use as the stderr for spawned processes.
37921 * If @fd is -1 then any previously given fd is unset.
37923 * Note that the default behaviour is to pass stderr through to the
37924 * stderr of the parent process.
37926 * The passed @fd belongs to the #GSubprocessLauncher. It will be
37927 * automatically closed when the launcher is finalized. The file
37928 * descriptor will also be closed on the child side when executing the
37931 * You may not set a stderr fd if a stderr file path is already set or
37932 * if the launcher flags contain any flags directing stderr elsewhere.
37934 * This feature is only available on UNIX.
37941 * g_subprocess_launcher_take_stdin_fd:
37942 * @self: a #GSubprocessLauncher
37943 * @fd: a file descriptor, or -1
37945 * Sets the file descriptor to use as the stdin for spawned processes.
37947 * If @fd is -1 then any previously given fd is unset.
37949 * Note that if your intention is to have the stdin of the calling
37950 * process inherited by the child then %G_SUBPROCESS_FLAGS_STDIN_INHERIT
37951 * is a better way to go about doing that.
37953 * The passed @fd is noted but will not be touched in the current
37954 * process. It is therefore necessary that it be kept open by the
37955 * caller until the subprocess is spawned. The file descriptor will
37956 * also not be explicitly closed on the child side, so it must be marked
37957 * O_CLOEXEC if that's what you want.
37959 * You may not set a stdin fd if a stdin file path is already set or if
37960 * the launcher flags contain any flags directing stdin elsewhere.
37962 * This feature is only available on UNIX.
37969 * g_subprocess_launcher_take_stdout_fd:
37970 * @self: a #GSubprocessLauncher
37971 * @fd: a file descriptor, or -1
37973 * Sets the file descriptor to use as the stdout for spawned processes.
37975 * If @fd is -1 then any previously given fd is unset.
37977 * Note that the default behaviour is to pass stdout through to the
37978 * stdout of the parent process.
37980 * The passed @fd is noted but will not be touched in the current
37981 * process. It is therefore necessary that it be kept open by the
37982 * caller until the subprocess is spawned. The file descriptor will
37983 * also not be explicitly closed on the child side, so it must be marked
37984 * O_CLOEXEC if that's what you want.
37986 * You may not set a stdout fd if a stdout file path is already set or
37987 * if the launcher flags contain any flags directing stdout elsewhere.
37989 * This feature is only available on UNIX.
37996 * g_subprocess_launcher_unsetenv:
37997 * @self: a #GSubprocess
37998 * @variable: the environment variable to unset, must not contain '='
38000 * Removes the environment variable @variable from the environment of
38001 * processes launched from this launcher.
38003 * On UNIX, the variable's name can be an arbitrary byte string not
38004 * containing '='. On Windows, it should be in UTF-8.
38011 * g_subprocess_new: (skip)
38012 * @flags: flags that define the behaviour of the subprocess
38013 * @error: (allow-none): return location for an error, or %NULL
38014 * @argv0: first commandline argument to pass to the subprocess
38015 * @...: more commandline arguments, followed by %NULL
38017 * Create a new process with the given flags and varargs argument
38018 * list. By default, matching the g_spawn_async() defaults, the
38019 * child's stdin will be set to the system null device, and
38020 * stdout/stderr will be inherited from the parent. You can use
38021 * @flags to control this behavior.
38023 * The argument list must be terminated with %NULL.
38025 * Returns: A newly created #GSubprocess, or %NULL on error (and @error
38032 * g_subprocess_newv: (rename-to g_subprocess_new)
38033 * @argv: (array zero-terminated=1) (element-type utf8): commandline arguments for the subprocess
38034 * @flags: flags that define the behaviour of the subprocess
38035 * @error: (allow-none): return location for an error, or %NULL
38037 * Create a new process with the given flags and argument list.
38039 * The argument list is expected to be %NULL-terminated.
38041 * Returns: A newly created #GSubprocess, or %NULL on error (and @error
38048 * g_subprocess_send_signal:
38049 * @subprocess: a #GSubprocess
38050 * @signal_num: the signal number to send
38052 * Sends the UNIX signal @signal_num to the subprocess, if it is still
38055 * This API is race-free. If the subprocess has terminated, it will not
38058 * This API is not available on Windows.
38065 * g_subprocess_wait:
38066 * @subprocess: a #GSubprocess
38067 * @cancellable: a #GCancellable
38068 * @error: a #GError
38070 * Synchronously wait for the subprocess to terminate.
38072 * After the process terminates you can query its exit status with
38073 * functions such as g_subprocess_get_if_exited() and
38074 * g_subprocess_get_exit_status().
38076 * This function does not fail in the case of the subprocess having
38077 * abnormal termination. See g_subprocess_wait_check() for that.
38079 * Cancelling @cancellable doesn't kill the subprocess. Call
38080 * g_subprocess_force_exit() if it is desirable.
38082 * Returns: %TRUE on success, %FALSE if @cancellable was cancelled
38088 * g_subprocess_wait_async:
38089 * @subprocess: a #GSubprocess
38090 * @cancellable: a #GCancellable, or %NULL
38091 * @callback: a #GAsyncReadyCallback to call when the operation is complete
38092 * @user_data: user_data for @callback
38094 * Wait for the subprocess to terminate.
38096 * This is the asynchronous version of g_subprocess_wait().
38103 * g_subprocess_wait_check:
38104 * @subprocess: a #GSubprocess
38105 * @cancellable: a #GCancellable
38106 * @error: a #GError
38108 * Combines g_subprocess_wait() with g_spawn_check_exit_status().
38110 * Returns: %TRUE on success, %FALSE if process exited abnormally, or
38111 * @cancellable was cancelled
38117 * g_subprocess_wait_check_async:
38118 * @subprocess: a #GSubprocess
38119 * @cancellable: a #GCancellable, or %NULL
38120 * @callback: a #GAsyncReadyCallback to call when the operation is complete
38121 * @user_data: user_data for @callback
38123 * Combines g_subprocess_wait_async() with g_spawn_check_exit_status().
38125 * This is the asynchronous version of g_subprocess_wait_check().
38132 * g_subprocess_wait_check_finish:
38133 * @subprocess: a #GSubprocess
38134 * @result: the #GAsyncResult passed to your #GAsyncReadyCallback
38135 * @error: a pointer to a %NULL #GError, or %NULL
38137 * Collects the result of a previous call to
38138 * g_subprocess_wait_check_async().
38140 * Returns: %TRUE if successful, or %FALSE with @error set
38146 * g_subprocess_wait_finish:
38147 * @subprocess: a #GSubprocess
38148 * @result: the #GAsyncResult passed to your #GAsyncReadyCallback
38149 * @error: a pointer to a %NULL #GError, or %NULL
38151 * Collects the result of a previous call to
38152 * g_subprocess_wait_async().
38154 * Returns: %TRUE if successful, or %FALSE with @error set
38160 * g_task_attach_source:
38162 * @source: the source to attach
38163 * @callback: the callback to invoke when @source triggers
38165 * A utility function for dealing with async operations where you need
38166 * to wait for a #GSource to trigger. Attaches @source to @task's
38167 * #GMainContext with @task's [priority][io-priority], and sets @source's
38168 * callback to @callback, with @task as the callback's `user_data`.
38170 * This takes a reference on @task until @source is destroyed.
38177 * g_task_get_cancellable:
38180 * Gets @task's #GCancellable
38182 * Returns: (transfer none): @task's #GCancellable
38188 * g_task_get_check_cancellable:
38189 * @task: the #GTask
38191 * Gets @task's check-cancellable flag. See
38192 * g_task_set_check_cancellable() for more details.
38199 * g_task_get_completed:
38202 * Gets the value of #GTask:completed. This changes from %FALSE to %TRUE after
38203 * the task’s callback is invoked, and will return %FALSE if called from inside
38206 * Returns: %TRUE if the task has completed, %FALSE otherwise.
38212 * g_task_get_context:
38215 * Gets the #GMainContext that @task will return its result in (that
38216 * is, the context that was the
38217 * [thread-default main context][g-main-context-push-thread-default]
38218 * at the point when @task was created).
38220 * This will always return a non-%NULL value, even if the task's
38221 * context is the default #GMainContext.
38223 * Returns: (transfer none): @task's #GMainContext
38229 * g_task_get_priority:
38232 * Gets @task's priority
38234 * Returns: @task's priority
38240 * g_task_get_return_on_cancel:
38241 * @task: the #GTask
38243 * Gets @task's return-on-cancel flag. See
38244 * g_task_set_return_on_cancel() for more details.
38251 * g_task_get_source_object:
38254 * Gets the source object from @task. Like
38255 * g_async_result_get_source_object(), but does not ref the object.
38257 * Returns: (transfer none) (type GObject): @task's source object, or %NULL
38263 * g_task_get_source_tag:
38266 * Gets @task's source tag. See g_task_set_source_tag().
38268 * Returns: (transfer none): @task's source tag
38274 * g_task_get_task_data:
38277 * Gets @task's `task_data`.
38279 * Returns: (transfer none): @task's `task_data`.
38285 * g_task_had_error:
38288 * Tests if @task resulted in an error.
38290 * Returns: %TRUE if the task resulted in an error, %FALSE otherwise.
38297 * @result: (type Gio.AsyncResult): A #GAsyncResult
38298 * @source_object: (allow-none) (type GObject): the source object
38299 * expected to be associated with the task
38301 * Checks that @result is a #GTask, and that @source_object is its
38302 * source object (or that @source_object is %NULL and @result has no
38303 * source object). This can be used in g_return_if_fail() checks.
38305 * Returns: %TRUE if @result and @source_object are valid, %FALSE
38313 * @source_object: (allow-none) (type GObject): the #GObject that owns
38314 * this task, or %NULL.
38315 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
38316 * @callback: (scope async): a #GAsyncReadyCallback.
38317 * @callback_data: (closure): user data passed to @callback.
38319 * Creates a #GTask acting on @source_object, which will eventually be
38320 * used to invoke @callback in the current
38321 * [thread-default main context][g-main-context-push-thread-default].
38323 * Call this in the "start" method of your asynchronous method, and
38324 * pass the #GTask around throughout the asynchronous operation. You
38325 * can use g_task_set_task_data() to attach task-specific data to the
38326 * object, which you can retrieve later via g_task_get_task_data().
38328 * By default, if @cancellable is cancelled, then the return value of
38329 * the task will always be %G_IO_ERROR_CANCELLED, even if the task had
38330 * already completed before the cancellation. This allows for
38331 * simplified handling in cases where cancellation may imply that
38332 * other objects that the task depends on have been destroyed. If you
38333 * do not want this behavior, you can use
38334 * g_task_set_check_cancellable() to change it.
38336 * Returns: a #GTask.
38342 * g_task_propagate_boolean:
38344 * @error: return location for a #GError
38346 * Gets the result of @task as a #gboolean.
38348 * If the task resulted in an error, or was cancelled, then this will
38349 * instead return %FALSE and set @error.
38351 * Since this method transfers ownership of the return value (or
38352 * error) to the caller, you may only call it once.
38354 * Returns: the task result, or %FALSE on error
38360 * g_task_propagate_int:
38362 * @error: return location for a #GError
38364 * Gets the result of @task as an integer (#gssize).
38366 * If the task resulted in an error, or was cancelled, then this will
38367 * instead return -1 and set @error.
38369 * Since this method transfers ownership of the return value (or
38370 * error) to the caller, you may only call it once.
38372 * Returns: the task result, or -1 on error
38378 * g_task_propagate_pointer:
38380 * @error: return location for a #GError
38382 * Gets the result of @task as a pointer, and transfers ownership
38383 * of that value to the caller.
38385 * If the task resulted in an error, or was cancelled, then this will
38386 * instead return %NULL and set @error.
38388 * Since this method transfers ownership of the return value (or
38389 * error) to the caller, you may only call it once.
38391 * Returns: (transfer full): the task result, or %NULL on error
38397 * g_task_report_error:
38398 * @source_object: (allow-none) (type GObject): the #GObject that owns
38399 * this task, or %NULL.
38400 * @callback: (scope async): a #GAsyncReadyCallback.
38401 * @callback_data: (closure): user data passed to @callback.
38402 * @source_tag: an opaque pointer indicating the source of this task
38403 * @error: (transfer full): error to report
38405 * Creates a #GTask and then immediately calls g_task_return_error()
38406 * on it. Use this in the wrapper function of an asynchronous method
38407 * when you want to avoid even calling the virtual method. You can
38408 * then use g_async_result_is_tagged() in the finish method wrapper to
38409 * check if the result there is tagged as having been created by the
38410 * wrapper method, and deal with it appropriately if so.
38412 * See also g_task_report_new_error().
38419 * g_task_report_new_error:
38420 * @source_object: (allow-none) (type GObject): the #GObject that owns
38421 * this task, or %NULL.
38422 * @callback: (scope async): a #GAsyncReadyCallback.
38423 * @callback_data: (closure): user data passed to @callback.
38424 * @source_tag: an opaque pointer indicating the source of this task
38425 * @domain: a #GQuark.
38426 * @code: an error code.
38427 * @format: a string with format characters.
38428 * @...: a list of values to insert into @format.
38430 * Creates a #GTask and then immediately calls
38431 * g_task_return_new_error() on it. Use this in the wrapper function
38432 * of an asynchronous method when you want to avoid even calling the
38433 * virtual method. You can then use g_async_result_is_tagged() in the
38434 * finish method wrapper to check if the result there is tagged as
38435 * having been created by the wrapper method, and deal with it
38436 * appropriately if so.
38438 * See also g_task_report_error().
38445 * g_task_return_boolean:
38447 * @result: the #gboolean result of a task function.
38449 * Sets @task's result to @result and completes the task (see
38450 * g_task_return_pointer() for more discussion of exactly what this
38458 * g_task_return_error:
38460 * @error: (transfer full): the #GError result of a task function.
38462 * Sets @task's result to @error (which @task assumes ownership of)
38463 * and completes the task (see g_task_return_pointer() for more
38464 * discussion of exactly what this means).
38466 * Note that since the task takes ownership of @error, and since the
38467 * task may be completed before returning from g_task_return_error(),
38468 * you cannot assume that @error is still valid after calling this.
38469 * Call g_error_copy() on the error if you need to keep a local copy
38472 * See also g_task_return_new_error().
38479 * g_task_return_error_if_cancelled:
38482 * Checks if @task's #GCancellable has been cancelled, and if so, sets
38483 * @task's error accordingly and completes the task (see
38484 * g_task_return_pointer() for more discussion of exactly what this
38487 * Returns: %TRUE if @task has been cancelled, %FALSE if not
38493 * g_task_return_int:
38495 * @result: the integer (#gssize) result of a task function.
38497 * Sets @task's result to @result and completes the task (see
38498 * g_task_return_pointer() for more discussion of exactly what this
38506 * g_task_return_new_error:
38508 * @domain: a #GQuark.
38509 * @code: an error code.
38510 * @format: a string with format characters.
38511 * @...: a list of values to insert into @format.
38513 * Sets @task's result to a new #GError created from @domain, @code,
38514 * @format, and the remaining arguments, and completes the task (see
38515 * g_task_return_pointer() for more discussion of exactly what this
38518 * See also g_task_return_error().
38525 * g_task_return_pointer:
38527 * @result: (allow-none) (transfer full): the pointer result of a task
38529 * @result_destroy: (allow-none): a #GDestroyNotify function.
38531 * Sets @task's result to @result and completes the task. If @result
38532 * is not %NULL, then @result_destroy will be used to free @result if
38533 * the caller does not take ownership of it with
38534 * g_task_propagate_pointer().
38536 * "Completes the task" means that for an ordinary asynchronous task
38537 * it will either invoke the task's callback, or else queue that
38538 * callback to be invoked in the proper #GMainContext, or in the next
38539 * iteration of the current #GMainContext. For a task run via
38540 * g_task_run_in_thread() or g_task_run_in_thread_sync(), calling this
38541 * method will save @result to be returned to the caller later, but
38542 * the task will not actually be completed until the #GTaskThreadFunc
38545 * Note that since the task may be completed before returning from
38546 * g_task_return_pointer(), you cannot assume that @result is still
38547 * valid after calling this, unless you are still holding another
38555 * g_task_run_in_thread:
38557 * @task_func: a #GTaskThreadFunc
38559 * Runs @task_func in another thread. When @task_func returns, @task's
38560 * #GAsyncReadyCallback will be invoked in @task's #GMainContext.
38562 * This takes a ref on @task until the task completes.
38564 * See #GTaskThreadFunc for more details about how @task_func is handled.
38566 * Although GLib currently rate-limits the tasks queued via
38567 * g_task_run_in_thread(), you should not assume that it will always
38568 * do this. If you have a very large number of tasks to run, but don't
38569 * want them to all run at once, you should only queue a limited
38570 * number of them at a time.
38577 * g_task_run_in_thread_sync:
38579 * @task_func: a #GTaskThreadFunc
38581 * Runs @task_func in another thread, and waits for it to return or be
38582 * cancelled. You can use g_task_propagate_pointer(), etc, afterward
38583 * to get the result of @task_func.
38585 * See #GTaskThreadFunc for more details about how @task_func is handled.
38587 * Normally this is used with tasks created with a %NULL
38588 * `callback`, but note that even if the task does
38589 * have a callback, it will not be invoked when @task_func returns.
38590 * #GTask:completed will be set to %TRUE just before this function returns.
38592 * Although GLib currently rate-limits the tasks queued via
38593 * g_task_run_in_thread_sync(), you should not assume that it will
38594 * always do this. If you have a very large number of tasks to run,
38595 * but don't want them to all run at once, you should only queue a
38596 * limited number of them at a time.
38603 * g_task_set_check_cancellable:
38604 * @task: the #GTask
38605 * @check_cancellable: whether #GTask will check the state of
38606 * its #GCancellable for you.
38608 * Sets or clears @task's check-cancellable flag. If this is %TRUE
38609 * (the default), then g_task_propagate_pointer(), etc, and
38610 * g_task_had_error() will check the task's #GCancellable first, and
38611 * if it has been cancelled, then they will consider the task to have
38612 * returned an "Operation was cancelled" error
38613 * (%G_IO_ERROR_CANCELLED), regardless of any other error or return
38614 * value the task may have had.
38616 * If @check_cancellable is %FALSE, then the #GTask will not check the
38617 * cancellable itself, and it is up to @task's owner to do this (eg,
38618 * via g_task_return_error_if_cancelled()).
38620 * If you are using g_task_set_return_on_cancel() as well, then
38621 * you must leave check-cancellable set %TRUE.
38628 * g_task_set_priority:
38629 * @task: the #GTask
38630 * @priority: the [priority][io-priority] of the request
38632 * Sets @task's priority. If you do not call this, it will default to
38633 * %G_PRIORITY_DEFAULT.
38635 * This will affect the priority of #GSources created with
38636 * g_task_attach_source() and the scheduling of tasks run in threads,
38637 * and can also be explicitly retrieved later via
38638 * g_task_get_priority().
38645 * g_task_set_return_on_cancel:
38646 * @task: the #GTask
38647 * @return_on_cancel: whether the task returns automatically when
38650 * Sets or clears @task's return-on-cancel flag. This is only
38651 * meaningful for tasks run via g_task_run_in_thread() or
38652 * g_task_run_in_thread_sync().
38654 * If @return_on_cancel is %TRUE, then cancelling @task's
38655 * #GCancellable will immediately cause it to return, as though the
38656 * task's #GTaskThreadFunc had called
38657 * g_task_return_error_if_cancelled() and then returned.
38659 * This allows you to create a cancellable wrapper around an
38660 * uninterruptable function. The #GTaskThreadFunc just needs to be
38661 * careful that it does not modify any externally-visible state after
38662 * it has been cancelled. To do that, the thread should call
38663 * g_task_set_return_on_cancel() again to (atomically) set
38664 * return-on-cancel %FALSE before making externally-visible changes;
38665 * if the task gets cancelled before the return-on-cancel flag could
38666 * be changed, g_task_set_return_on_cancel() will indicate this by
38667 * returning %FALSE.
38669 * You can disable and re-enable this flag multiple times if you wish.
38670 * If the task's #GCancellable is cancelled while return-on-cancel is
38671 * %FALSE, then calling g_task_set_return_on_cancel() to set it %TRUE
38672 * again will cause the task to be cancelled at that point.
38674 * If the task's #GCancellable is already cancelled before you call
38675 * g_task_run_in_thread()/g_task_run_in_thread_sync(), then the
38676 * #GTaskThreadFunc will still be run (for consistency), but the task
38677 * will also be completed right away.
38679 * Returns: %TRUE if @task's return-on-cancel flag was changed to
38680 * match @return_on_cancel. %FALSE if @task has already been
38687 * g_task_set_source_tag:
38688 * @task: the #GTask
38689 * @source_tag: an opaque pointer indicating the source of this task
38691 * Sets @task's source tag. You can use this to tag a task return
38692 * value with a particular pointer (usually a pointer to the function
38693 * doing the tagging) and then later check it using
38694 * g_task_get_source_tag() (or g_async_result_is_tagged()) in the
38695 * task's "finish" function, to figure out if the response came from a
38696 * particular place.
38703 * g_task_set_task_data:
38704 * @task: the #GTask
38705 * @task_data: (allow-none): task-specific data
38706 * @task_data_destroy: (allow-none): #GDestroyNotify for @task_data
38708 * Sets @task's task data (freeing the existing task data, if any).
38715 * g_tcp_connection_get_graceful_disconnect:
38716 * @connection: a #GTcpConnection
38718 * Checks if graceful disconnects are used. See
38719 * g_tcp_connection_set_graceful_disconnect().
38721 * Returns: %TRUE if graceful disconnect is used on close, %FALSE otherwise
38727 * g_tcp_connection_set_graceful_disconnect:
38728 * @connection: a #GTcpConnection
38729 * @graceful_disconnect: Whether to do graceful disconnects or not
38731 * This enables graceful disconnects on close. A graceful disconnect
38732 * means that we signal the receiving end that the connection is terminated
38733 * and wait for it to close the connection before closing the connection.
38735 * A graceful disconnect means that we can be sure that we successfully sent
38736 * all the outstanding data to the other end, or get an error reported.
38737 * However, it also means we have to wait for all the data to reach the
38738 * other side and for it to acknowledge this by closing the socket, which may
38739 * take a while. For this reason it is disabled by default.
38746 * g_tcp_wrapper_connection_get_base_io_stream:
38747 * @conn: a #GTcpWrapperConnection
38749 * Get's @conn's base #GIOStream
38751 * Returns: (transfer none): @conn's base #GIOStream
38756 * g_tcp_wrapper_connection_new:
38757 * @base_io_stream: the #GIOStream to wrap
38758 * @socket: the #GSocket associated with @base_io_stream
38760 * Wraps @base_io_stream and @socket together as a #GSocketConnection.
38762 * Returns: the new #GSocketConnection.
38768 * g_test_dbus_add_service_dir:
38769 * @self: a #GTestDBus
38770 * @path: path to a directory containing .service files
38772 * Add a path where dbus-daemon will look up .service files. This can't be
38773 * called after g_test_dbus_up().
38778 * g_test_dbus_down:
38779 * @self: a #GTestDBus
38781 * Stop the session bus started by g_test_dbus_up().
38783 * This will wait for the singleton returned by g_bus_get() or g_bus_get_sync()
38784 * is destroyed. This is done to ensure that the next unit test won't get a
38785 * leaked singleton from this test.
38790 * g_test_dbus_get_bus_address:
38791 * @self: a #GTestDBus
38793 * Get the address on which dbus-daemon is running. If g_test_dbus_up() has not
38794 * been called yet, %NULL is returned. This can be used with
38795 * g_dbus_connection_new_for_address().
38797 * Returns: (allow-none): the address of the bus, or %NULL.
38802 * g_test_dbus_get_flags:
38803 * @self: a #GTestDBus
38805 * Get the flags of the #GTestDBus object.
38807 * Returns: the value of #GTestDBus:flags property
38813 * @flags: a #GTestDBusFlags
38815 * Create a new #GTestDBus object.
38817 * Returns: (transfer full): a new #GTestDBus.
38822 * g_test_dbus_stop:
38823 * @self: a #GTestDBus
38825 * Stop the session bus started by g_test_dbus_up().
38827 * Unlike g_test_dbus_down(), this won't verify the #GDBusConnection
38828 * singleton returned by g_bus_get() or g_bus_get_sync() is destroyed. Unit
38829 * tests wanting to verify behaviour after the session bus has been stopped
38830 * can use this function but should still call g_test_dbus_down() when done.
38835 * g_test_dbus_unset:
38837 * Unset DISPLAY and DBUS_SESSION_BUS_ADDRESS env variables to ensure the test
38838 * won't use user's session bus.
38840 * This is useful for unit tests that want to verify behaviour when no session
38841 * bus is running. It is not necessary to call this if unit test already calls
38842 * g_test_dbus_up() before acquiring the session bus.
38848 * @self: a #GTestDBus
38850 * Start a dbus-daemon instance and set DBUS_SESSION_BUS_ADDRESS. After this
38851 * call, it is safe for unit tests to start sending messages on the session bus.
38853 * If this function is called from setup callback of g_test_add(),
38854 * g_test_dbus_down() must be called in its teardown callback.
38856 * If this function is called from unit test's main(), then g_test_dbus_down()
38857 * must be called after g_test_run().
38862 * g_themed_icon_append_name:
38863 * @icon: a #GThemedIcon
38864 * @iconname: name of icon to append to list of icons from within @icon.
38866 * Append a name to the list of icons from within @icon.
38868 * Note that doing so invalidates the hash computed by prior calls
38869 * to g_icon_hash().
38874 * g_themed_icon_get_names:
38875 * @icon: a #GThemedIcon.
38877 * Gets the names of icons from within @icon.
38879 * Returns: (transfer none): a list of icon names.
38884 * g_themed_icon_new:
38885 * @iconname: a string containing an icon name.
38887 * Creates a new themed icon for @iconname.
38889 * Returns: (transfer full) (type GThemedIcon): a new #GThemedIcon.
38894 * g_themed_icon_new_from_names:
38895 * @iconnames: (array length=len): an array of strings containing icon names.
38896 * @len: the length of the @iconnames array, or -1 if @iconnames is
38899 * Creates a new themed icon for @iconnames.
38901 * Returns: (transfer full) (type GThemedIcon): a new #GThemedIcon
38906 * g_themed_icon_new_with_default_fallbacks:
38907 * @iconname: a string containing an icon name
38909 * Creates a new themed icon for @iconname, and all the names
38910 * that can be created by shortening @iconname at '-' characters.
38912 * In the following example, @icon1 and @icon2 are equivalent:
38913 * |[<!-- language="C" -->
38914 * const char *names[] = {
38915 * "gnome-dev-cdrom-audio",
38916 * "gnome-dev-cdrom",
38921 * icon1 = g_themed_icon_new_from_names (names, 4);
38922 * icon2 = g_themed_icon_new_with_default_fallbacks ("gnome-dev-cdrom-audio");
38925 * Returns: (transfer full) (type GThemedIcon): a new #GThemedIcon.
38930 * g_themed_icon_prepend_name:
38931 * @icon: a #GThemedIcon
38932 * @iconname: name of icon to prepend to list of icons from within @icon.
38934 * Prepend a name to the list of icons from within @icon.
38936 * Note that doing so invalidates the hash computed by prior calls
38937 * to g_icon_hash().
38944 * g_threaded_socket_service_new:
38945 * @max_threads: the maximal number of threads to execute concurrently
38946 * handling incoming clients, -1 means no limit
38948 * Creates a new #GThreadedSocketService with no listeners. Listeners
38949 * must be added with one of the #GSocketListener "add" methods.
38951 * Returns: a new #GSocketService.
38957 * g_tls_backend_get_certificate_type:
38958 * @backend: the #GTlsBackend
38960 * Gets the #GType of @backend's #GTlsCertificate implementation.
38962 * Returns: the #GType of @backend's #GTlsCertificate
38969 * g_tls_backend_get_client_connection_type:
38970 * @backend: the #GTlsBackend
38972 * Gets the #GType of @backend's #GTlsClientConnection implementation.
38974 * Returns: the #GType of @backend's #GTlsClientConnection
38981 * g_tls_backend_get_default:
38983 * Gets the default #GTlsBackend for the system.
38985 * Returns: (transfer none): a #GTlsBackend
38991 * g_tls_backend_get_default_database:
38992 * @backend: the #GTlsBackend
38994 * Gets the default #GTlsDatabase used to verify TLS connections.
38996 * Returns: (transfer full): the default database, which should be
38997 * unreffed when done.
39003 * g_tls_backend_get_dtls_client_connection_type:
39004 * @backend: the #GTlsBackend
39006 * Gets the #GType of @backend’s #GDtlsClientConnection implementation.
39008 * Returns: the #GType of @backend’s #GDtlsClientConnection
39015 * g_tls_backend_get_dtls_server_connection_type:
39016 * @backend: the #GTlsBackend
39018 * Gets the #GType of @backend’s #GDtlsServerConnection implementation.
39020 * Returns: the #GType of @backend’s #GDtlsServerConnection
39027 * g_tls_backend_get_file_database_type:
39028 * @backend: the #GTlsBackend
39030 * Gets the #GType of @backend's #GTlsFileDatabase implementation.
39032 * Returns: the #GType of backend's #GTlsFileDatabase implementation.
39038 * g_tls_backend_get_server_connection_type:
39039 * @backend: the #GTlsBackend
39041 * Gets the #GType of @backend's #GTlsServerConnection implementation.
39043 * Returns: the #GType of @backend's #GTlsServerConnection
39050 * g_tls_backend_supports_dtls:
39051 * @backend: the #GTlsBackend
39053 * Checks if DTLS is supported. DTLS support may not be available even if TLS
39054 * support is available, and vice-versa.
39056 * Returns: whether DTLS is supported
39062 * g_tls_backend_supports_tls:
39063 * @backend: the #GTlsBackend
39065 * Checks if TLS is supported; if this returns %FALSE for the default
39066 * #GTlsBackend, it means no "real" TLS backend is available.
39068 * Returns: whether or not TLS is supported
39074 * g_tls_certificate_get_issuer:
39075 * @cert: a #GTlsCertificate
39077 * Gets the #GTlsCertificate representing @cert's issuer, if known
39079 * Returns: (transfer none): The certificate of @cert's issuer,
39080 * or %NULL if @cert is self-signed or signed with an unknown
39087 * g_tls_certificate_is_same:
39088 * @cert_one: first certificate to compare
39089 * @cert_two: second certificate to compare
39091 * Check if two #GTlsCertificate objects represent the same certificate.
39092 * The raw DER byte data of the two certificates are checked for equality.
39093 * This has the effect that two certificates may compare equal even if
39094 * their #GTlsCertificate:issuer, #GTlsCertificate:private-key, or
39095 * #GTlsCertificate:private-key-pem properties differ.
39097 * Returns: whether the same or not
39103 * g_tls_certificate_list_new_from_file:
39104 * @file: (type filename): file containing PEM-encoded certificates to import
39105 * @error: #GError for error reporting, or %NULL to ignore.
39107 * Creates one or more #GTlsCertificates from the PEM-encoded
39108 * data in @file. If @file cannot be read or parsed, the function will
39109 * return %NULL and set @error. If @file does not contain any
39110 * PEM-encoded certificates, this will return an empty list and not
39113 * Returns: (element-type Gio.TlsCertificate) (transfer full): a
39114 * #GList containing #GTlsCertificate objects. You must free the list
39115 * and its contents when you are done with it.
39121 * g_tls_certificate_new_from_file:
39122 * @file: (type filename): file containing a PEM-encoded certificate to import
39123 * @error: #GError for error reporting, or %NULL to ignore.
39125 * Creates a #GTlsCertificate from the PEM-encoded data in @file. The
39126 * returned certificate will be the first certificate found in @file. As
39127 * of GLib 2.44, if @file contains more certificates it will try to load
39128 * a certificate chain. All certificates will be verified in the order
39129 * found (top-level certificate should be the last one in the file) and
39130 * the #GTlsCertificate:issuer property of each certificate will be set
39131 * accordingly if the verification succeeds. If any certificate in the
39132 * chain cannot be verified, the first certificate in the file will
39133 * still be returned.
39135 * If @file cannot be read or parsed, the function will return %NULL and
39136 * set @error. Otherwise, this behaves like
39137 * g_tls_certificate_new_from_pem().
39139 * Returns: the new certificate, or %NULL on error
39145 * g_tls_certificate_new_from_files:
39146 * @cert_file: (type filename): file containing one or more PEM-encoded
39147 * certificates to import
39148 * @key_file: (type filename): file containing a PEM-encoded private key
39150 * @error: #GError for error reporting, or %NULL to ignore.
39152 * Creates a #GTlsCertificate from the PEM-encoded data in @cert_file
39153 * and @key_file. The returned certificate will be the first certificate
39154 * found in @cert_file. As of GLib 2.44, if @cert_file contains more
39155 * certificates it will try to load a certificate chain. All
39156 * certificates will be verified in the order found (top-level
39157 * certificate should be the last one in the file) and the
39158 * #GTlsCertificate:issuer property of each certificate will be set
39159 * accordingly if the verification succeeds. If any certificate in the
39160 * chain cannot be verified, the first certificate in the file will
39161 * still be returned.
39163 * If either file cannot be read or parsed, the function will return
39164 * %NULL and set @error. Otherwise, this behaves like
39165 * g_tls_certificate_new_from_pem().
39167 * Returns: the new certificate, or %NULL on error
39173 * g_tls_certificate_new_from_pem:
39174 * @data: PEM-encoded certificate data
39175 * @length: the length of @data, or -1 if it's 0-terminated.
39176 * @error: #GError for error reporting, or %NULL to ignore.
39178 * Creates a #GTlsCertificate from the PEM-encoded data in @data. If
39179 * @data includes both a certificate and a private key, then the
39180 * returned certificate will include the private key data as well. (See
39181 * the #GTlsCertificate:private-key-pem property for information about
39182 * supported formats.)
39184 * The returned certificate will be the first certificate found in
39185 * @data. As of GLib 2.44, if @data contains more certificates it will
39186 * try to load a certificate chain. All certificates will be verified in
39187 * the order found (top-level certificate should be the last one in the
39188 * file) and the #GTlsCertificate:issuer property of each certificate
39189 * will be set accordingly if the verification succeeds. If any
39190 * certificate in the chain cannot be verified, the first certificate in
39191 * the file will still be returned.
39193 * Returns: the new certificate, or %NULL if @data is invalid
39199 * g_tls_certificate_verify:
39200 * @cert: a #GTlsCertificate
39201 * @identity: (allow-none): the expected peer identity
39202 * @trusted_ca: (allow-none): the certificate of a trusted authority
39204 * This verifies @cert and returns a set of #GTlsCertificateFlags
39205 * indicating any problems found with it. This can be used to verify a
39206 * certificate outside the context of making a connection, or to
39207 * check a certificate against a CA that is not part of the system
39210 * If @identity is not %NULL, @cert's name(s) will be compared against
39211 * it, and %G_TLS_CERTIFICATE_BAD_IDENTITY will be set in the return
39212 * value if it does not match. If @identity is %NULL, that bit will
39213 * never be set in the return value.
39215 * If @trusted_ca is not %NULL, then @cert (or one of the certificates
39216 * in its chain) must be signed by it, or else
39217 * %G_TLS_CERTIFICATE_UNKNOWN_CA will be set in the return value. If
39218 * @trusted_ca is %NULL, that bit will never be set in the return
39221 * (All other #GTlsCertificateFlags values will always be set or unset
39224 * Returns: the appropriate #GTlsCertificateFlags
39230 * g_tls_client_connection_copy_session_state:
39231 * @conn: a #GTlsClientConnection
39232 * @source: a #GTlsClientConnection
39234 * Copies session state from one connection to another. This is
39235 * not normally needed, but may be used when the same session
39236 * needs to be used between different endpoints as is required
39237 * by some protocols such as FTP over TLS. @source should have
39238 * already completed a handshake, and @conn should not have
39239 * completed a handshake.
39246 * g_tls_client_connection_get_accepted_cas:
39247 * @conn: the #GTlsClientConnection
39249 * Gets the list of distinguished names of the Certificate Authorities
39250 * that the server will accept certificates from. This will be set
39251 * during the TLS handshake if the server requests a certificate.
39252 * Otherwise, it will be %NULL.
39254 * Each item in the list is a #GByteArray which contains the complete
39255 * subject DN of the certificate authority.
39257 * Returns: (element-type GByteArray) (transfer full): the list of
39258 * CA DNs. You should unref each element with g_byte_array_unref() and then
39259 * the free the list with g_list_free().
39265 * g_tls_client_connection_get_server_identity:
39266 * @conn: the #GTlsClientConnection
39268 * Gets @conn's expected server identity
39270 * Returns: (transfer none): a #GSocketConnectable describing the
39271 * expected server identity, or %NULL if the expected identity is not
39278 * g_tls_client_connection_get_use_ssl3:
39279 * @conn: the #GTlsClientConnection
39281 * Gets whether @conn will use SSL 3.0 rather than the
39282 * highest-supported version of TLS; see
39283 * g_tls_client_connection_set_use_ssl3().
39285 * Returns: whether @conn will use SSL 3.0
39291 * g_tls_client_connection_get_validation_flags:
39292 * @conn: the #GTlsClientConnection
39294 * Gets @conn's validation flags
39296 * Returns: the validation flags
39302 * g_tls_client_connection_new:
39303 * @base_io_stream: the #GIOStream to wrap
39304 * @server_identity: (allow-none): the expected identity of the server
39305 * @error: #GError for error reporting, or %NULL to ignore.
39307 * Creates a new #GTlsClientConnection wrapping @base_io_stream (which
39308 * must have pollable input and output streams) which is assumed to
39309 * communicate with the server identified by @server_identity.
39311 * See the documentation for #GTlsConnection:base-io-stream for restrictions
39312 * on when application code can run operations on the @base_io_stream after
39313 * this function has returned.
39315 * Returns: (transfer full) (type GTlsClientConnection): the new
39316 * #GTlsClientConnection, or %NULL on error
39322 * g_tls_client_connection_set_server_identity:
39323 * @conn: the #GTlsClientConnection
39324 * @identity: a #GSocketConnectable describing the expected server identity
39326 * Sets @conn's expected server identity, which is used both to tell
39327 * servers on virtual hosts which certificate to present, and also
39328 * to let @conn know what name to look for in the certificate when
39329 * performing %G_TLS_CERTIFICATE_BAD_IDENTITY validation, if enabled.
39336 * g_tls_client_connection_set_use_ssl3:
39337 * @conn: the #GTlsClientConnection
39338 * @use_ssl3: whether to use SSL 3.0
39340 * If @use_ssl3 is %TRUE, this forces @conn to use SSL 3.0 rather than
39341 * trying to properly negotiate the right version of TLS or SSL to use.
39342 * This can be used when talking to servers that do not implement the
39343 * fallbacks correctly and which will therefore fail to handshake with
39344 * a "modern" TLS handshake attempt.
39351 * g_tls_client_connection_set_validation_flags:
39352 * @conn: the #GTlsClientConnection
39353 * @flags: the #GTlsCertificateFlags to use
39355 * Sets @conn's validation flags, to override the default set of
39356 * checks performed when validating a server certificate. By default,
39357 * %G_TLS_CERTIFICATE_VALIDATE_ALL is used.
39364 * g_tls_connection_emit_accept_certificate:
39365 * @conn: a #GTlsConnection
39366 * @peer_cert: the peer's #GTlsCertificate
39367 * @errors: the problems with @peer_cert
39369 * Used by #GTlsConnection implementations to emit the
39370 * #GTlsConnection::accept-certificate signal.
39372 * Returns: %TRUE if one of the signal handlers has returned
39373 * %TRUE to accept @peer_cert
39379 * g_tls_connection_get_certificate:
39380 * @conn: a #GTlsConnection
39382 * Gets @conn's certificate, as set by
39383 * g_tls_connection_set_certificate().
39385 * Returns: (transfer none): @conn's certificate, or %NULL
39391 * g_tls_connection_get_database:
39392 * @conn: a #GTlsConnection
39394 * Gets the certificate database that @conn uses to verify
39395 * peer certificates. See g_tls_connection_set_database().
39397 * Returns: (transfer none): the certificate database that @conn uses or %NULL
39403 * g_tls_connection_get_interaction:
39404 * @conn: a connection
39406 * Get the object that will be used to interact with the user. It will be used
39407 * for things like prompting the user for passwords. If %NULL is returned, then
39408 * no user interaction will occur for this connection.
39410 * Returns: (transfer none): The interaction object.
39416 * g_tls_connection_get_peer_certificate:
39417 * @conn: a #GTlsConnection
39419 * Gets @conn's peer's certificate after the handshake has completed.
39420 * (It is not set during the emission of
39421 * #GTlsConnection::accept-certificate.)
39423 * Returns: (transfer none): @conn's peer's certificate, or %NULL
39429 * g_tls_connection_get_peer_certificate_errors:
39430 * @conn: a #GTlsConnection
39432 * Gets the errors associated with validating @conn's peer's
39433 * certificate, after the handshake has completed. (It is not set
39434 * during the emission of #GTlsConnection::accept-certificate.)
39436 * Returns: @conn's peer's certificate errors
39442 * g_tls_connection_get_rehandshake_mode:
39443 * @conn: a #GTlsConnection
39445 * Gets @conn rehandshaking mode. See
39446 * g_tls_connection_set_rehandshake_mode() for details.
39448 * Returns: @conn's rehandshaking mode
39454 * g_tls_connection_get_require_close_notify:
39455 * @conn: a #GTlsConnection
39457 * Tests whether or not @conn expects a proper TLS close notification
39458 * when the connection is closed. See
39459 * g_tls_connection_set_require_close_notify() for details.
39461 * Returns: %TRUE if @conn requires a proper TLS close
39468 * g_tls_connection_get_use_system_certdb:
39469 * @conn: a #GTlsConnection
39471 * Gets whether @conn uses the system certificate database to verify
39472 * peer certificates. See g_tls_connection_set_use_system_certdb().
39474 * Returns: whether @conn uses the system certificate database
39475 * Deprecated: 2.30: Use g_tls_connection_get_database() instead
39480 * g_tls_connection_handshake:
39481 * @conn: a #GTlsConnection
39482 * @cancellable: (allow-none): a #GCancellable, or %NULL
39483 * @error: a #GError, or %NULL
39485 * Attempts a TLS handshake on @conn.
39487 * On the client side, it is never necessary to call this method;
39488 * although the connection needs to perform a handshake after
39489 * connecting (or after sending a "STARTTLS"-type command) and may
39490 * need to rehandshake later if the server requests it,
39491 * #GTlsConnection will handle this for you automatically when you try
39492 * to send or receive data on the connection. However, you can call
39493 * g_tls_connection_handshake() manually if you want to know for sure
39494 * whether the initial handshake succeeded or failed (as opposed to
39495 * just immediately trying to write to @conn's output stream, in which
39496 * case if it fails, it may not be possible to tell if it failed
39497 * before or after completing the handshake).
39499 * Likewise, on the server side, although a handshake is necessary at
39500 * the beginning of the communication, you do not need to call this
39501 * function explicitly unless you want clearer error reporting.
39502 * However, you may call g_tls_connection_handshake() later on to
39503 * renegotiate parameters (encryption methods, etc) with the client.
39505 * #GTlsConnection::accept_certificate may be emitted during the
39508 * Returns: success or failure
39514 * g_tls_connection_handshake_async:
39515 * @conn: a #GTlsConnection
39516 * @io_priority: the [I/O priority][io-priority] of the request
39517 * @cancellable: (allow-none): a #GCancellable, or %NULL
39518 * @callback: callback to call when the handshake is complete
39519 * @user_data: the data to pass to the callback function
39521 * Asynchronously performs a TLS handshake on @conn. See
39522 * g_tls_connection_handshake() for more information.
39529 * g_tls_connection_handshake_finish:
39530 * @conn: a #GTlsConnection
39531 * @result: a #GAsyncResult.
39532 * @error: a #GError pointer, or %NULL
39534 * Finish an asynchronous TLS handshake operation. See
39535 * g_tls_connection_handshake() for more information.
39537 * Returns: %TRUE on success, %FALSE on failure, in which
39538 * case @error will be set.
39544 * g_tls_connection_set_certificate:
39545 * @conn: a #GTlsConnection
39546 * @certificate: the certificate to use for @conn
39548 * This sets the certificate that @conn will present to its peer
39549 * during the TLS handshake. For a #GTlsServerConnection, it is
39550 * mandatory to set this, and that will normally be done at construct
39553 * For a #GTlsClientConnection, this is optional. If a handshake fails
39554 * with %G_TLS_ERROR_CERTIFICATE_REQUIRED, that means that the server
39555 * requires a certificate, and if you try connecting again, you should
39556 * call this method first. You can call
39557 * g_tls_client_connection_get_accepted_cas() on the failed connection
39558 * to get a list of Certificate Authorities that the server will
39559 * accept certificates from.
39561 * (It is also possible that a server will allow the connection with
39562 * or without a certificate; in that case, if you don't provide a
39563 * certificate, you can tell that the server requested one by the fact
39564 * that g_tls_client_connection_get_accepted_cas() will return
39572 * g_tls_connection_set_database:
39573 * @conn: a #GTlsConnection
39574 * @database: a #GTlsDatabase
39576 * Sets the certificate database that is used to verify peer certificates.
39577 * This is set to the default database by default. See
39578 * g_tls_backend_get_default_database(). If set to %NULL, then
39579 * peer certificate validation will always set the
39580 * %G_TLS_CERTIFICATE_UNKNOWN_CA error (meaning
39581 * #GTlsConnection::accept-certificate will always be emitted on
39582 * client-side connections, unless that bit is not set in
39583 * #GTlsClientConnection:validation-flags).
39590 * g_tls_connection_set_interaction:
39591 * @conn: a connection
39592 * @interaction: (allow-none): an interaction object, or %NULL
39594 * Set the object that will be used to interact with the user. It will be used
39595 * for things like prompting the user for passwords.
39597 * The @interaction argument will normally be a derived subclass of
39598 * #GTlsInteraction. %NULL can also be provided if no user interaction
39599 * should occur for this connection.
39606 * g_tls_connection_set_rehandshake_mode:
39607 * @conn: a #GTlsConnection
39608 * @mode: the rehandshaking mode
39610 * Sets how @conn behaves with respect to rehandshaking requests.
39612 * %G_TLS_REHANDSHAKE_NEVER means that it will never agree to
39613 * rehandshake after the initial handshake is complete. (For a client,
39614 * this means it will refuse rehandshake requests from the server, and
39615 * for a server, this means it will close the connection with an error
39616 * if the client attempts to rehandshake.)
39618 * %G_TLS_REHANDSHAKE_SAFELY means that the connection will allow a
39619 * rehandshake only if the other end of the connection supports the
39620 * TLS `renegotiation_info` extension. This is the default behavior,
39621 * but means that rehandshaking will not work against older
39622 * implementations that do not support that extension.
39624 * %G_TLS_REHANDSHAKE_UNSAFELY means that the connection will allow
39625 * rehandshaking even without the `renegotiation_info` extension. On
39626 * the server side in particular, this is not recommended, since it
39627 * leaves the server open to certain attacks. However, this mode is
39628 * necessary if you need to allow renegotiation with older client
39636 * g_tls_connection_set_require_close_notify:
39637 * @conn: a #GTlsConnection
39638 * @require_close_notify: whether or not to require close notification
39640 * Sets whether or not @conn expects a proper TLS close notification
39641 * before the connection is closed. If this is %TRUE (the default),
39642 * then @conn will expect to receive a TLS close notification from its
39643 * peer before the connection is closed, and will return a
39644 * %G_TLS_ERROR_EOF error if the connection is closed without proper
39645 * notification (since this may indicate a network error, or
39646 * man-in-the-middle attack).
39648 * In some protocols, the application will know whether or not the
39649 * connection was closed cleanly based on application-level data
39650 * (because the application-level data includes a length field, or is
39651 * somehow self-delimiting); in this case, the close notify is
39652 * redundant and sometimes omitted. (TLS 1.1 explicitly allows this;
39653 * in TLS 1.0 it is technically an error, but often done anyway.) You
39654 * can use g_tls_connection_set_require_close_notify() to tell @conn
39655 * to allow an "unannounced" connection close, in which case the close
39656 * will show up as a 0-length read, as in a non-TLS
39657 * #GSocketConnection, and it is up to the application to check that
39658 * the data has been fully received.
39660 * Note that this only affects the behavior when the peer closes the
39661 * connection; when the application calls g_io_stream_close() itself
39662 * on @conn, this will send a close notification regardless of the
39663 * setting of this property. If you explicitly want to do an unclean
39664 * close, you can close @conn's #GTlsConnection:base-io-stream rather
39665 * than closing @conn itself, but note that this may only be done when no other
39666 * operations are pending on @conn or the base I/O stream.
39673 * g_tls_connection_set_use_system_certdb:
39674 * @conn: a #GTlsConnection
39675 * @use_system_certdb: whether to use the system certificate database
39677 * Sets whether @conn uses the system certificate database to verify
39678 * peer certificates. This is %TRUE by default. If set to %FALSE, then
39679 * peer certificate validation will always set the
39680 * %G_TLS_CERTIFICATE_UNKNOWN_CA error (meaning
39681 * #GTlsConnection::accept-certificate will always be emitted on
39682 * client-side connections, unless that bit is not set in
39683 * #GTlsClientConnection:validation-flags).
39685 * Deprecated: 2.30: Use g_tls_connection_set_database() instead
39690 * g_tls_database_create_certificate_handle:
39691 * @self: a #GTlsDatabase
39692 * @certificate: certificate for which to create a handle.
39694 * Create a handle string for the certificate. The database will only be able
39695 * to create a handle for certificates that originate from the database. In
39696 * cases where the database cannot create a handle for a certificate, %NULL
39697 * will be returned.
39699 * This handle should be stable across various instances of the application,
39700 * and between applications. If a certificate is modified in the database,
39701 * then it is not guaranteed that this handle will continue to point to it.
39703 * Returns: (nullable): a newly allocated string containing the
39710 * g_tls_database_lookup_certificate_for_handle:
39711 * @self: a #GTlsDatabase
39712 * @handle: a certificate handle
39713 * @interaction: (allow-none): used to interact with the user if necessary
39714 * @flags: Flags which affect the lookup.
39715 * @cancellable: (allow-none): a #GCancellable, or %NULL
39716 * @error: (allow-none): a #GError, or %NULL
39718 * Lookup a certificate by its handle.
39720 * The handle should have been created by calling
39721 * g_tls_database_create_certificate_handle() on a #GTlsDatabase object of
39722 * the same TLS backend. The handle is designed to remain valid across
39723 * instantiations of the database.
39725 * If the handle is no longer valid, or does not point to a certificate in
39726 * this database, then %NULL will be returned.
39728 * This function can block, use g_tls_database_lookup_certificate_for_handle_async() to perform
39729 * the lookup operation asynchronously.
39731 * Returns: (transfer full) (allow-none): a newly allocated
39732 * #GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate.
39738 * g_tls_database_lookup_certificate_for_handle_async:
39739 * @self: a #GTlsDatabase
39740 * @handle: a certificate handle
39741 * @interaction: (allow-none): used to interact with the user if necessary
39742 * @flags: Flags which affect the lookup.
39743 * @cancellable: (allow-none): a #GCancellable, or %NULL
39744 * @callback: callback to call when the operation completes
39745 * @user_data: the data to pass to the callback function
39747 * Asynchronously lookup a certificate by its handle in the database. See
39748 * g_tls_database_lookup_certificate_for_handle() for more information.
39755 * g_tls_database_lookup_certificate_for_handle_finish:
39756 * @self: a #GTlsDatabase
39757 * @result: a #GAsyncResult.
39758 * @error: a #GError pointer, or %NULL
39760 * Finish an asynchronous lookup of a certificate by its handle. See
39761 * g_tls_database_lookup_certificate_handle() for more information.
39763 * If the handle is no longer valid, or does not point to a certificate in
39764 * this database, then %NULL will be returned.
39766 * Returns: (transfer full): a newly allocated #GTlsCertificate object.
39767 * Use g_object_unref() to release the certificate.
39773 * g_tls_database_lookup_certificate_issuer:
39774 * @self: a #GTlsDatabase
39775 * @certificate: a #GTlsCertificate
39776 * @interaction: (allow-none): used to interact with the user if necessary
39777 * @flags: flags which affect the lookup operation
39778 * @cancellable: (allow-none): a #GCancellable, or %NULL
39779 * @error: (allow-none): a #GError, or %NULL
39781 * Lookup the issuer of @certificate in the database.
39783 * The %issuer property
39784 * of @certificate is not modified, and the two certificates are not hooked
39787 * This function can block, use g_tls_database_lookup_certificate_issuer_async() to perform
39788 * the lookup operation asynchronously.
39790 * Returns: (transfer full): a newly allocated issuer #GTlsCertificate,
39791 * or %NULL. Use g_object_unref() to release the certificate.
39797 * g_tls_database_lookup_certificate_issuer_async:
39798 * @self: a #GTlsDatabase
39799 * @certificate: a #GTlsCertificate
39800 * @interaction: (allow-none): used to interact with the user if necessary
39801 * @flags: flags which affect the lookup operation
39802 * @cancellable: (allow-none): a #GCancellable, or %NULL
39803 * @callback: callback to call when the operation completes
39804 * @user_data: the data to pass to the callback function
39806 * Asynchronously lookup the issuer of @certificate in the database. See
39807 * g_tls_database_lookup_certificate_issuer() for more information.
39814 * g_tls_database_lookup_certificate_issuer_finish:
39815 * @self: a #GTlsDatabase
39816 * @result: a #GAsyncResult.
39817 * @error: a #GError pointer, or %NULL
39819 * Finish an asynchronous lookup issuer operation. See
39820 * g_tls_database_lookup_certificate_issuer() for more information.
39822 * Returns: (transfer full): a newly allocated issuer #GTlsCertificate,
39823 * or %NULL. Use g_object_unref() to release the certificate.
39829 * g_tls_database_lookup_certificates_issued_by:
39830 * @self: a #GTlsDatabase
39831 * @issuer_raw_dn: a #GByteArray which holds the DER encoded issuer DN.
39832 * @interaction: (allow-none): used to interact with the user if necessary
39833 * @flags: Flags which affect the lookup operation.
39834 * @cancellable: (allow-none): a #GCancellable, or %NULL
39835 * @error: (allow-none): a #GError, or %NULL
39837 * Lookup certificates issued by this issuer in the database.
39839 * This function can block, use g_tls_database_lookup_certificates_issued_by_async() to perform
39840 * the lookup operation asynchronously.
39842 * Returns: (transfer full) (element-type GTlsCertificate): a newly allocated list of #GTlsCertificate
39843 * objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list.
39849 * g_tls_database_lookup_certificates_issued_by_async:
39850 * @self: a #GTlsDatabase
39851 * @issuer_raw_dn: a #GByteArray which holds the DER encoded issuer DN.
39852 * @interaction: (allow-none): used to interact with the user if necessary
39853 * @flags: Flags which affect the lookup operation.
39854 * @cancellable: (allow-none): a #GCancellable, or %NULL
39855 * @callback: callback to call when the operation completes
39856 * @user_data: the data to pass to the callback function
39858 * Asynchronously lookup certificates issued by this issuer in the database. See
39859 * g_tls_database_lookup_certificates_issued_by() for more information.
39861 * The database may choose to hold a reference to the issuer byte array for the duration
39862 * of of this asynchronous operation. The byte array should not be modified during
39870 * g_tls_database_lookup_certificates_issued_by_finish:
39871 * @self: a #GTlsDatabase
39872 * @result: a #GAsyncResult.
39873 * @error: a #GError pointer, or %NULL
39875 * Finish an asynchronous lookup of certificates. See
39876 * g_tls_database_lookup_certificates_issued_by() for more information.
39878 * Returns: (transfer full) (element-type GTlsCertificate): a newly allocated list of #GTlsCertificate
39879 * objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list.
39885 * g_tls_database_verify_chain:
39886 * @self: a #GTlsDatabase
39887 * @chain: a #GTlsCertificate chain
39888 * @purpose: the purpose that this certificate chain will be used for.
39889 * @identity: (allow-none): the expected peer identity
39890 * @interaction: (allow-none): used to interact with the user if necessary
39891 * @flags: additional verify flags
39892 * @cancellable: (allow-none): a #GCancellable, or %NULL
39893 * @error: (allow-none): a #GError, or %NULL
39895 * Verify's a certificate chain after looking up and adding any missing
39896 * certificates to the chain.
39898 * @chain is a chain of #GTlsCertificate objects each pointing to the next
39899 * certificate in the chain by its %issuer property. The chain may initially
39900 * consist of one or more certificates. After the verification process is
39901 * complete, @chain may be modified by adding missing certificates, or removing
39902 * extra certificates. If a certificate anchor was found, then it is added to
39905 * @purpose describes the purpose (or usage) for which the certificate
39906 * is being used. Typically @purpose will be set to #G_TLS_DATABASE_PURPOSE_AUTHENTICATE_SERVER
39907 * which means that the certificate is being used to authenticate a server
39908 * (and we are acting as the client).
39910 * The @identity is used to check for pinned certificates (trust exceptions)
39911 * in the database. These will override the normal verification process on a
39912 * host by host basis.
39914 * Currently there are no @flags, and %G_TLS_DATABASE_VERIFY_NONE should be
39917 * This function can block, use g_tls_database_verify_chain_async() to perform
39918 * the verification operation asynchronously.
39920 * Returns: the appropriate #GTlsCertificateFlags which represents the
39921 * result of verification.
39927 * g_tls_database_verify_chain_async:
39928 * @self: a #GTlsDatabase
39929 * @chain: a #GTlsCertificate chain
39930 * @purpose: the purpose that this certificate chain will be used for.
39931 * @identity: (allow-none): the expected peer identity
39932 * @interaction: (allow-none): used to interact with the user if necessary
39933 * @flags: additional verify flags
39934 * @cancellable: (allow-none): a #GCancellable, or %NULL
39935 * @callback: callback to call when the operation completes
39936 * @user_data: the data to pass to the callback function
39938 * Asynchronously verify's a certificate chain after looking up and adding
39939 * any missing certificates to the chain. See g_tls_database_verify_chain()
39940 * for more information.
39947 * g_tls_database_verify_chain_finish:
39948 * @self: a #GTlsDatabase
39949 * @result: a #GAsyncResult.
39950 * @error: a #GError pointer, or %NULL
39952 * Finish an asynchronous verify chain operation. See
39953 * g_tls_database_verify_chain() for more information. *
39955 * Returns: the appropriate #GTlsCertificateFlags which represents the
39956 * result of verification.
39962 * g_tls_error_quark:
39964 * Gets the TLS error quark.
39966 * Returns: a #GQuark.
39972 * g_tls_file_database_new:
39973 * @anchors: (type filename): filename of anchor certificate authorities.
39974 * @error: #GError for error reporting, or %NULL to ignore.
39976 * Creates a new #GTlsFileDatabase which uses anchor certificate authorities
39977 * in @anchors to verify certificate chains.
39979 * The certificates in @anchors must be PEM encoded.
39981 * Returns: (transfer full) (type GTlsFileDatabase): the new
39982 * #GTlsFileDatabase, or %NULL on error
39988 * g_tls_interaction_ask_password:
39989 * @interaction: a #GTlsInteraction object
39990 * @password: a #GTlsPassword object
39991 * @cancellable: an optional #GCancellable cancellation object
39992 * @error: an optional location to place an error on failure
39994 * Run synchronous interaction to ask the user for a password. In general,
39995 * g_tls_interaction_invoke_ask_password() should be used instead of this
39998 * Derived subclasses usually implement a password prompt, although they may
39999 * also choose to provide a password from elsewhere. The @password value will
40000 * be filled in and then @callback will be called. Alternatively the user may
40001 * abort this password request, which will usually abort the TLS connection.
40003 * If the interaction is cancelled by the cancellation object, or by the
40004 * user then %G_TLS_INTERACTION_FAILED will be returned with an error that
40005 * contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may
40006 * not support immediate cancellation.
40008 * Returns: The status of the ask password interaction.
40014 * g_tls_interaction_ask_password_async:
40015 * @interaction: a #GTlsInteraction object
40016 * @password: a #GTlsPassword object
40017 * @cancellable: an optional #GCancellable cancellation object
40018 * @callback: (allow-none): will be called when the interaction completes
40019 * @user_data: (allow-none): data to pass to the @callback
40021 * Run asynchronous interaction to ask the user for a password. In general,
40022 * g_tls_interaction_invoke_ask_password() should be used instead of this
40025 * Derived subclasses usually implement a password prompt, although they may
40026 * also choose to provide a password from elsewhere. The @password value will
40027 * be filled in and then @callback will be called. Alternatively the user may
40028 * abort this password request, which will usually abort the TLS connection.
40030 * If the interaction is cancelled by the cancellation object, or by the
40031 * user then %G_TLS_INTERACTION_FAILED will be returned with an error that
40032 * contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may
40033 * not support immediate cancellation.
40035 * Certain implementations may not support immediate cancellation.
40042 * g_tls_interaction_ask_password_finish:
40043 * @interaction: a #GTlsInteraction object
40044 * @result: the result passed to the callback
40045 * @error: an optional location to place an error on failure
40047 * Complete an ask password user interaction request. This should be once
40048 * the g_tls_interaction_ask_password_async() completion callback is called.
40050 * If %G_TLS_INTERACTION_HANDLED is returned, then the #GTlsPassword passed
40051 * to g_tls_interaction_ask_password() will have its password filled in.
40053 * If the interaction is cancelled by the cancellation object, or by the
40054 * user then %G_TLS_INTERACTION_FAILED will be returned with an error that
40055 * contains a %G_IO_ERROR_CANCELLED error code.
40057 * Returns: The status of the ask password interaction.
40063 * g_tls_interaction_invoke_ask_password:
40064 * @interaction: a #GTlsInteraction object
40065 * @password: a #GTlsPassword object
40066 * @cancellable: an optional #GCancellable cancellation object
40067 * @error: an optional location to place an error on failure
40069 * Invoke the interaction to ask the user for a password. It invokes this
40070 * interaction in the main loop, specifically the #GMainContext returned by
40071 * g_main_context_get_thread_default() when the interaction is created. This
40072 * is called by called by #GTlsConnection or #GTlsDatabase to ask the user
40075 * Derived subclasses usually implement a password prompt, although they may
40076 * also choose to provide a password from elsewhere. The @password value will
40077 * be filled in and then @callback will be called. Alternatively the user may
40078 * abort this password request, which will usually abort the TLS connection.
40080 * The implementation can either be a synchronous (eg: modal dialog) or an
40081 * asynchronous one (eg: modeless dialog). This function will take care of
40082 * calling which ever one correctly.
40084 * If the interaction is cancelled by the cancellation object, or by the
40085 * user then %G_TLS_INTERACTION_FAILED will be returned with an error that
40086 * contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may
40087 * not support immediate cancellation.
40089 * Returns: The status of the ask password interaction.
40095 * g_tls_interaction_invoke_request_certificate:
40096 * @interaction: a #GTlsInteraction object
40097 * @connection: a #GTlsConnection object
40098 * @flags: flags providing more information about the request
40099 * @cancellable: an optional #GCancellable cancellation object
40100 * @error: an optional location to place an error on failure
40102 * Invoke the interaction to ask the user to choose a certificate to
40103 * use with the connection. It invokes this interaction in the main
40104 * loop, specifically the #GMainContext returned by
40105 * g_main_context_get_thread_default() when the interaction is
40106 * created. This is called by called by #GTlsConnection when the peer
40107 * requests a certificate during the handshake.
40109 * Derived subclasses usually implement a certificate selector,
40110 * although they may also choose to provide a certificate from
40111 * elsewhere. Alternatively the user may abort this certificate
40112 * request, which may or may not abort the TLS connection.
40114 * The implementation can either be a synchronous (eg: modal dialog) or an
40115 * asynchronous one (eg: modeless dialog). This function will take care of
40116 * calling which ever one correctly.
40118 * If the interaction is cancelled by the cancellation object, or by the
40119 * user then %G_TLS_INTERACTION_FAILED will be returned with an error that
40120 * contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may
40121 * not support immediate cancellation.
40123 * Returns: The status of the certificate request interaction.
40129 * g_tls_interaction_request_certificate:
40130 * @interaction: a #GTlsInteraction object
40131 * @connection: a #GTlsConnection object
40132 * @flags: flags providing more information about the request
40133 * @cancellable: an optional #GCancellable cancellation object
40134 * @error: an optional location to place an error on failure
40136 * Run synchronous interaction to ask the user to choose a certificate to use
40137 * with the connection. In general, g_tls_interaction_invoke_request_certificate()
40138 * should be used instead of this function.
40140 * Derived subclasses usually implement a certificate selector, although they may
40141 * also choose to provide a certificate from elsewhere. Alternatively the user may
40142 * abort this certificate request, which will usually abort the TLS connection.
40144 * If %G_TLS_INTERACTION_HANDLED is returned, then the #GTlsConnection
40145 * passed to g_tls_interaction_request_certificate() will have had its
40146 * #GTlsConnection:certificate filled in.
40148 * If the interaction is cancelled by the cancellation object, or by the
40149 * user then %G_TLS_INTERACTION_FAILED will be returned with an error that
40150 * contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may
40151 * not support immediate cancellation.
40153 * Returns: The status of the request certificate interaction.
40159 * g_tls_interaction_request_certificate_async:
40160 * @interaction: a #GTlsInteraction object
40161 * @connection: a #GTlsConnection object
40162 * @flags: flags providing more information about the request
40163 * @cancellable: an optional #GCancellable cancellation object
40164 * @callback: (allow-none): will be called when the interaction completes
40165 * @user_data: (allow-none): data to pass to the @callback
40167 * Run asynchronous interaction to ask the user for a certificate to use with
40168 * the connection. In general, g_tls_interaction_invoke_request_certificate() should
40169 * be used instead of this function.
40171 * Derived subclasses usually implement a certificate selector, although they may
40172 * also choose to provide a certificate from elsewhere. @callback will be called
40173 * when the operation completes. Alternatively the user may abort this certificate
40174 * request, which will usually abort the TLS connection.
40181 * g_tls_interaction_request_certificate_finish:
40182 * @interaction: a #GTlsInteraction object
40183 * @result: the result passed to the callback
40184 * @error: an optional location to place an error on failure
40186 * Complete an request certificate user interaction request. This should be once
40187 * the g_tls_interaction_request_certificate_async() completion callback is called.
40189 * If %G_TLS_INTERACTION_HANDLED is returned, then the #GTlsConnection
40190 * passed to g_tls_interaction_request_certificate_async() will have had its
40191 * #GTlsConnection:certificate filled in.
40193 * If the interaction is cancelled by the cancellation object, or by the
40194 * user then %G_TLS_INTERACTION_FAILED will be returned with an error that
40195 * contains a %G_IO_ERROR_CANCELLED error code.
40197 * Returns: The status of the request certificate interaction.
40203 * g_tls_password_get_description:
40204 * @password: a #GTlsPassword object
40206 * Get a description string about what the password will be used for.
40208 * Returns: The description of the password.
40214 * g_tls_password_get_flags:
40215 * @password: a #GTlsPassword object
40217 * Get flags about the password.
40219 * Returns: The flags about the password.
40225 * g_tls_password_get_value:
40226 * @password: a #GTlsPassword object
40227 * @length: (allow-none): location to place the length of the password.
40229 * Get the password value. If @length is not %NULL then it will be
40230 * filled in with the length of the password value. (Note that the
40231 * password value is not nul-terminated, so you can only pass %NULL
40232 * for @length in contexts where you know the password will have a
40233 * certain fixed length.)
40235 * Returns: The password value (owned by the password object).
40241 * g_tls_password_get_warning:
40242 * @password: a #GTlsPassword object
40244 * Get a user readable translated warning. Usually this warning is a
40245 * representation of the password flags returned from
40246 * g_tls_password_get_flags().
40248 * Returns: The warning.
40254 * g_tls_password_new:
40255 * @flags: the password flags
40256 * @description: description of what the password is for
40258 * Create a new #GTlsPassword object.
40260 * Returns: (transfer full): The newly allocated password object
40265 * g_tls_password_set_description:
40266 * @password: a #GTlsPassword object
40267 * @description: The description of the password
40269 * Set a description string about what the password will be used for.
40276 * g_tls_password_set_flags:
40277 * @password: a #GTlsPassword object
40278 * @flags: The flags about the password
40280 * Set flags about the password.
40287 * g_tls_password_set_value:
40288 * @password: a #GTlsPassword object
40289 * @value: the new password value
40290 * @length: the length of the password, or -1
40292 * Set the value for this password. The @value will be copied by the password
40295 * Specify the @length, for a non-nul-terminated password. Pass -1 as
40296 * @length if using a nul-terminated password, and @length will be
40297 * calculated automatically. (Note that the terminating nul is not
40298 * considered part of the password in this case.)
40305 * g_tls_password_set_value_full: (virtual set_value)
40306 * @password: a #GTlsPassword object
40307 * @value: the value for the password
40308 * @length: the length of the password, or -1
40309 * @destroy: (allow-none): a function to use to free the password.
40311 * Provide the value for this password.
40313 * The @value will be owned by the password object, and later freed using
40314 * the @destroy function callback.
40316 * Specify the @length, for a non-nul-terminated password. Pass -1 as
40317 * @length if using a nul-terminated password, and @length will be
40318 * calculated automatically. (Note that the terminating nul is not
40319 * considered part of the password in this case.)
40326 * g_tls_password_set_warning:
40327 * @password: a #GTlsPassword object
40328 * @warning: The user readable warning
40330 * Set a user readable translated warning. Usually this warning is a
40331 * representation of the password flags returned from
40332 * g_tls_password_get_flags().
40339 * g_tls_server_connection_new:
40340 * @base_io_stream: the #GIOStream to wrap
40341 * @certificate: (allow-none): the default server certificate, or %NULL
40342 * @error: #GError for error reporting, or %NULL to ignore.
40344 * Creates a new #GTlsServerConnection wrapping @base_io_stream (which
40345 * must have pollable input and output streams).
40347 * See the documentation for #GTlsConnection:base-io-stream for restrictions
40348 * on when application code can run operations on the @base_io_stream after
40349 * this function has returned.
40351 * Returns: (transfer full) (type GTlsServerConnection): the new
40352 * #GTlsServerConnection, or %NULL on error
40358 * g_unix_connection_receive_credentials:
40359 * @connection: A #GUnixConnection.
40360 * @cancellable: (allow-none): A #GCancellable or %NULL.
40361 * @error: Return location for error or %NULL.
40363 * Receives credentials from the sending end of the connection. The
40364 * sending end has to call g_unix_connection_send_credentials() (or
40365 * similar) for this to work.
40367 * As well as reading the credentials this also reads (and discards) a
40368 * single byte from the stream, as this is required for credentials
40369 * passing to work on some implementations.
40371 * Other ways to exchange credentials with a foreign peer includes the
40372 * #GUnixCredentialsMessage type and g_socket_get_credentials() function.
40374 * Returns: (transfer full): Received credentials on success (free with
40375 * g_object_unref()), %NULL if @error is set.
40381 * g_unix_connection_receive_credentials_async:
40382 * @connection: A #GUnixConnection.
40383 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
40384 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
40385 * @user_data: (closure): the data to pass to callback function
40387 * Asynchronously receive credentials.
40389 * For more details, see g_unix_connection_receive_credentials() which is
40390 * the synchronous version of this call.
40392 * When the operation is finished, @callback will be called. You can then call
40393 * g_unix_connection_receive_credentials_finish() to get the result of the operation.
40400 * g_unix_connection_receive_credentials_finish:
40401 * @connection: A #GUnixConnection.
40402 * @result: a #GAsyncResult.
40403 * @error: a #GError, or %NULL
40405 * Finishes an asynchronous receive credentials operation started with
40406 * g_unix_connection_receive_credentials_async().
40408 * Returns: (transfer full): a #GCredentials, or %NULL on error.
40409 * Free the returned object with g_object_unref().
40415 * g_unix_connection_receive_fd:
40416 * @connection: a #GUnixConnection
40417 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
40418 * @error: (allow-none): #GError for error reporting, or %NULL to ignore
40420 * Receives a file descriptor from the sending end of the connection.
40421 * The sending end has to call g_unix_connection_send_fd() for this
40424 * As well as reading the fd this also reads a single byte from the
40425 * stream, as this is required for fd passing to work on some
40428 * Returns: a file descriptor on success, -1 on error.
40434 * g_unix_connection_send_credentials:
40435 * @connection: A #GUnixConnection.
40436 * @cancellable: (allow-none): A #GCancellable or %NULL.
40437 * @error: Return location for error or %NULL.
40439 * Passes the credentials of the current user the receiving side
40440 * of the connection. The receiving end has to call
40441 * g_unix_connection_receive_credentials() (or similar) to accept the
40444 * As well as sending the credentials this also writes a single NUL
40445 * byte to the stream, as this is required for credentials passing to
40446 * work on some implementations.
40448 * Other ways to exchange credentials with a foreign peer includes the
40449 * #GUnixCredentialsMessage type and g_socket_get_credentials() function.
40451 * Returns: %TRUE on success, %FALSE if @error is set.
40457 * g_unix_connection_send_credentials_async:
40458 * @connection: A #GUnixConnection.
40459 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
40460 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
40461 * @user_data: (closure): the data to pass to callback function
40463 * Asynchronously send credentials.
40465 * For more details, see g_unix_connection_send_credentials() which is
40466 * the synchronous version of this call.
40468 * When the operation is finished, @callback will be called. You can then call
40469 * g_unix_connection_send_credentials_finish() to get the result of the operation.
40476 * g_unix_connection_send_credentials_finish:
40477 * @connection: A #GUnixConnection.
40478 * @result: a #GAsyncResult.
40479 * @error: a #GError, or %NULL
40481 * Finishes an asynchronous send credentials operation started with
40482 * g_unix_connection_send_credentials_async().
40484 * Returns: %TRUE if the operation was successful, otherwise %FALSE.
40490 * g_unix_connection_send_fd:
40491 * @connection: a #GUnixConnection
40492 * @fd: a file descriptor
40493 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
40494 * @error: (allow-none): #GError for error reporting, or %NULL to ignore.
40496 * Passes a file descriptor to the receiving side of the
40497 * connection. The receiving end has to call g_unix_connection_receive_fd()
40498 * to accept the file descriptor.
40500 * As well as sending the fd this also writes a single byte to the
40501 * stream, as this is required for fd passing to work on some
40504 * Returns: a %TRUE on success, %NULL on error.
40510 * g_unix_credentials_message_get_credentials:
40511 * @message: A #GUnixCredentialsMessage.
40513 * Gets the credentials stored in @message.
40515 * Returns: (transfer none): A #GCredentials instance. Do not free, it is owned by @message.
40521 * g_unix_credentials_message_is_supported:
40523 * Checks if passing #GCredentials on a #GSocket is supported on this platform.
40525 * Returns: %TRUE if supported, %FALSE otherwise
40531 * g_unix_credentials_message_new:
40533 * Creates a new #GUnixCredentialsMessage with credentials matching the current processes.
40535 * Returns: a new #GUnixCredentialsMessage
40541 * g_unix_credentials_message_new_with_credentials:
40542 * @credentials: A #GCredentials object.
40544 * Creates a new #GUnixCredentialsMessage holding @credentials.
40546 * Returns: a new #GUnixCredentialsMessage
40552 * g_unix_fd_list_append:
40553 * @list: a #GUnixFDList
40554 * @fd: a valid open file descriptor
40555 * @error: a #GError pointer
40557 * Adds a file descriptor to @list.
40559 * The file descriptor is duplicated using dup(). You keep your copy
40560 * of the descriptor and the copy contained in @list will be closed
40561 * when @list is finalized.
40563 * A possible cause of failure is exceeding the per-process or
40564 * system-wide file descriptor limit.
40566 * The index of the file descriptor in the list is returned. If you use
40567 * this index with g_unix_fd_list_get() then you will receive back a
40568 * duplicated copy of the same file descriptor.
40570 * Returns: the index of the appended fd in case of success, else -1
40571 * (and @error is set)
40577 * g_unix_fd_list_get:
40578 * @list: a #GUnixFDList
40579 * @index_: the index into the list
40580 * @error: a #GError pointer
40582 * Gets a file descriptor out of @list.
40584 * @index_ specifies the index of the file descriptor to get. It is a
40585 * programmer error for @index_ to be out of range; see
40586 * g_unix_fd_list_get_length().
40588 * The file descriptor is duplicated using dup() and set as
40589 * close-on-exec before being returned. You must call close() on it
40590 * when you are done.
40592 * A possible cause of failure is exceeding the per-process or
40593 * system-wide file descriptor limit.
40595 * Returns: the file descriptor, or -1 in case of error
40601 * g_unix_fd_list_get_length:
40602 * @list: a #GUnixFDList
40604 * Gets the length of @list (ie: the number of file descriptors
40605 * contained within).
40607 * Returns: the length of @list
40613 * g_unix_fd_list_new:
40615 * Creates a new #GUnixFDList containing no file descriptors.
40617 * Returns: a new #GUnixFDList
40623 * g_unix_fd_list_new_from_array:
40624 * @fds: (array length=n_fds): the initial list of file descriptors
40625 * @n_fds: the length of #fds, or -1
40627 * Creates a new #GUnixFDList containing the file descriptors given in
40628 * @fds. The file descriptors become the property of the new list and
40629 * may no longer be used by the caller. The array itself is owned by
40632 * Each file descriptor in the array should be set to close-on-exec.
40634 * If @n_fds is -1 then @fds must be terminated with -1.
40636 * Returns: a new #GUnixFDList
40642 * g_unix_fd_list_peek_fds:
40643 * @list: a #GUnixFDList
40644 * @length: (out) (allow-none): pointer to the length of the returned
40647 * Returns the array of file descriptors that is contained in this
40650 * After this call, the descriptors remain the property of @list. The
40651 * caller must not close them and must not free the array. The array is
40652 * valid only until @list is changed in any way.
40654 * If @length is non-%NULL then it is set to the number of file
40655 * descriptors in the returned array. The returned array is also
40656 * terminated with -1.
40658 * This function never returns %NULL. In case there are no file
40659 * descriptors contained in @list, an empty array is returned.
40661 * Returns: (array length=length) (transfer none): an array of file
40668 * g_unix_fd_list_steal_fds:
40669 * @list: a #GUnixFDList
40670 * @length: (out) (allow-none): pointer to the length of the returned
40673 * Returns the array of file descriptors that is contained in this
40676 * After this call, the descriptors are no longer contained in
40677 * @list. Further calls will return an empty list (unless more
40678 * descriptors have been added).
40680 * The return result of this function must be freed with g_free().
40681 * The caller is also responsible for closing all of the file
40682 * descriptors. The file descriptors in the array are set to
40685 * If @length is non-%NULL then it is set to the number of file
40686 * descriptors in the returned array. The returned array is also
40687 * terminated with -1.
40689 * This function never returns %NULL. In case there are no file
40690 * descriptors contained in @list, an empty array is returned.
40692 * Returns: (array length=length) (transfer full): an array of file
40699 * g_unix_fd_message_append_fd:
40700 * @message: a #GUnixFDMessage
40701 * @fd: a valid open file descriptor
40702 * @error: a #GError pointer
40704 * Adds a file descriptor to @message.
40706 * The file descriptor is duplicated using dup(). You keep your copy
40707 * of the descriptor and the copy contained in @message will be closed
40708 * when @message is finalized.
40710 * A possible cause of failure is exceeding the per-process or
40711 * system-wide file descriptor limit.
40713 * Returns: %TRUE in case of success, else %FALSE (and @error is set)
40719 * g_unix_fd_message_get_fd_list:
40720 * @message: a #GUnixFDMessage
40722 * Gets the #GUnixFDList contained in @message. This function does not
40723 * return a reference to the caller, but the returned list is valid for
40724 * the lifetime of @message.
40726 * Returns: (transfer none): the #GUnixFDList from @message
40732 * g_unix_fd_message_new:
40734 * Creates a new #GUnixFDMessage containing an empty file descriptor
40737 * Returns: a new #GUnixFDMessage
40743 * g_unix_fd_message_new_with_fd_list:
40744 * @fd_list: a #GUnixFDList
40746 * Creates a new #GUnixFDMessage containing @list.
40748 * Returns: a new #GUnixFDMessage
40754 * g_unix_fd_message_steal_fds:
40755 * @message: a #GUnixFDMessage
40756 * @length: (out) (allow-none): pointer to the length of the returned
40759 * Returns the array of file descriptors that is contained in this
40762 * After this call, the descriptors are no longer contained in
40763 * @message. Further calls will return an empty list (unless more
40764 * descriptors have been added).
40766 * The return result of this function must be freed with g_free().
40767 * The caller is also responsible for closing all of the file
40770 * If @length is non-%NULL then it is set to the number of file
40771 * descriptors in the returned array. The returned array is also
40772 * terminated with -1.
40774 * This function never returns %NULL. In case there are no file
40775 * descriptors contained in @message, an empty array is returned.
40777 * Returns: (array length=length) (transfer full): an array of file
40784 * g_unix_input_stream_get_close_fd:
40785 * @stream: a #GUnixInputStream
40787 * Returns whether the file descriptor of @stream will be
40788 * closed when the stream is closed.
40790 * Returns: %TRUE if the file descriptor is closed when done
40796 * g_unix_input_stream_get_fd:
40797 * @stream: a #GUnixInputStream
40799 * Return the UNIX file descriptor that the stream reads from.
40801 * Returns: The file descriptor of @stream
40807 * g_unix_input_stream_new:
40808 * @fd: a UNIX file descriptor
40809 * @close_fd: %TRUE to close the file descriptor when done
40811 * Creates a new #GUnixInputStream for the given @fd.
40813 * If @close_fd is %TRUE, the file descriptor will be closed
40814 * when the stream is closed.
40816 * Returns: a new #GUnixInputStream
40821 * g_unix_input_stream_set_close_fd:
40822 * @stream: a #GUnixInputStream
40823 * @close_fd: %TRUE to close the file descriptor when done
40825 * Sets whether the file descriptor of @stream shall be closed
40826 * when the stream is closed.
40833 * g_unix_is_mount_path_system_internal:
40834 * @mount_path: (type filename): a mount path, e.g. `/media/disk` or `/usr`
40836 * Determines if @mount_path is considered an implementation of the
40837 * OS. This is primarily used for hiding mountable and mounted volumes
40838 * that only are used in the OS and has little to no relevance to the
40841 * Returns: %TRUE if @mount_path is considered an implementation detail
40847 * g_unix_mount_at: (skip)
40848 * @mount_path: path for a possible unix mount.
40849 * @time_read: (out) (allow-none): guint64 to contain a timestamp.
40851 * Gets a #GUnixMountEntry for a given mount path. If @time_read
40852 * is set, it will be filled with a unix timestamp for checking
40853 * if the mounts have changed since with g_unix_mounts_changed_since().
40855 * Returns: (transfer full): a #GUnixMountEntry.
40860 * g_unix_mount_compare:
40861 * @mount1: first #GUnixMountEntry to compare.
40862 * @mount2: second #GUnixMountEntry to compare.
40864 * Compares two unix mounts.
40866 * Returns: 1, 0 or -1 if @mount1 is greater than, equal to,
40867 * or less than @mount2, respectively.
40872 * g_unix_mount_free:
40873 * @mount_entry: a #GUnixMountEntry.
40875 * Frees a unix mount.
40880 * g_unix_mount_get_device_path:
40881 * @mount_entry: a #GUnixMount.
40883 * Gets the device path for a unix mount.
40885 * Returns: (type filename): a string containing the device path.
40890 * g_unix_mount_get_fs_type:
40891 * @mount_entry: a #GUnixMount.
40893 * Gets the filesystem type for the unix mount.
40895 * Returns: a string containing the file system type.
40900 * g_unix_mount_get_mount_path:
40901 * @mount_entry: input #GUnixMountEntry to get the mount path for.
40903 * Gets the mount path for a unix mount.
40905 * Returns: (type filename): the mount path for @mount_entry.
40910 * g_unix_mount_guess_can_eject:
40911 * @mount_entry: a #GUnixMountEntry
40913 * Guesses whether a Unix mount can be ejected.
40915 * Returns: %TRUE if @mount_entry is deemed to be ejectable.
40920 * g_unix_mount_guess_icon:
40921 * @mount_entry: a #GUnixMountEntry
40923 * Guesses the icon of a Unix mount.
40925 * Returns: (transfer full): a #GIcon
40930 * g_unix_mount_guess_name:
40931 * @mount_entry: a #GUnixMountEntry
40933 * Guesses the name of a Unix mount.
40934 * The result is a translated string.
40936 * Returns: A newly allocated string that must
40937 * be freed with g_free()
40942 * g_unix_mount_guess_should_display:
40943 * @mount_entry: a #GUnixMountEntry
40945 * Guesses whether a Unix mount should be displayed in the UI.
40947 * Returns: %TRUE if @mount_entry is deemed to be displayable.
40952 * g_unix_mount_guess_symbolic_icon:
40953 * @mount_entry: a #GUnixMountEntry
40955 * Guesses the symbolic icon of a Unix mount.
40957 * Returns: (transfer full): a #GIcon
40963 * g_unix_mount_guess_type:
40964 * @mount_entry: a #GUnixMount.
40966 * Guesses the type of a unix mount. If the mount type cannot be
40967 * determined, returns %G_UNIX_MOUNT_TYPE_UNKNOWN.
40969 * Returns: a #GUnixMountType.
40974 * g_unix_mount_is_readonly:
40975 * @mount_entry: a #GUnixMount.
40977 * Checks if a unix mount is mounted read only.
40979 * Returns: %TRUE if @mount_entry is read only.
40984 * g_unix_mount_is_system_internal:
40985 * @mount_entry: a #GUnixMount.
40987 * Checks if a unix mount is a system path.
40989 * Returns: %TRUE if the unix mount is for a system path.
40994 * g_unix_mount_monitor_get:
40996 * Gets the #GUnixMountMonitor for the current thread-default main
40999 * The mount monitor can be used to monitor for changes to the list of
41000 * mounted filesystems as well as the list of mount points (ie: fstab
41003 * You must only call g_object_unref() on the return value from under
41004 * the same main context as you called this function.
41006 * Returns: (transfer full): the #GUnixMountMonitor.
41012 * g_unix_mount_monitor_new:
41014 * Deprecated alias for g_unix_mount_monitor_get().
41016 * This function was never a true constructor, which is why it was
41019 * Returns: a #GUnixMountMonitor.
41020 * Deprecated: 2.44: Use g_unix_mount_monitor_get() instead.
41025 * g_unix_mount_monitor_set_rate_limit:
41026 * @mount_monitor: a #GUnixMountMonitor
41027 * @limit_msec: a integer with the limit in milliseconds to
41028 * poll for changes.
41030 * This function does nothing.
41032 * Before 2.44, this was a partially-effective way of controlling the
41033 * rate at which events would be reported under some uncommon
41034 * circumstances. Since @mount_monitor is a singleton, it also meant
41035 * that calling this function would have side effects for other users of
41039 * Deprecated: 2.44: This function does nothing. Don't call it.
41044 * g_unix_mount_point_compare:
41045 * @mount1: a #GUnixMount.
41046 * @mount2: a #GUnixMount.
41048 * Compares two unix mount points.
41050 * Returns: 1, 0 or -1 if @mount1 is greater than, equal to,
41051 * or less than @mount2, respectively.
41056 * g_unix_mount_point_free:
41057 * @mount_point: unix mount point to free.
41059 * Frees a unix mount point.
41064 * g_unix_mount_point_get_device_path:
41065 * @mount_point: a #GUnixMountPoint.
41067 * Gets the device path for a unix mount point.
41069 * Returns: (type filename): a string containing the device path.
41074 * g_unix_mount_point_get_fs_type:
41075 * @mount_point: a #GUnixMountPoint.
41077 * Gets the file system type for the mount point.
41079 * Returns: a string containing the file system type.
41084 * g_unix_mount_point_get_mount_path:
41085 * @mount_point: a #GUnixMountPoint.
41087 * Gets the mount path for a unix mount point.
41089 * Returns: (type filename): a string containing the mount path.
41094 * g_unix_mount_point_get_options:
41095 * @mount_point: a #GUnixMountPoint.
41097 * Gets the options for the mount point.
41099 * Returns: a string containing the options.
41105 * g_unix_mount_point_guess_can_eject:
41106 * @mount_point: a #GUnixMountPoint
41108 * Guesses whether a Unix mount point can be ejected.
41110 * Returns: %TRUE if @mount_point is deemed to be ejectable.
41115 * g_unix_mount_point_guess_icon:
41116 * @mount_point: a #GUnixMountPoint
41118 * Guesses the icon of a Unix mount point.
41120 * Returns: (transfer full): a #GIcon
41125 * g_unix_mount_point_guess_name:
41126 * @mount_point: a #GUnixMountPoint
41128 * Guesses the name of a Unix mount point.
41129 * The result is a translated string.
41131 * Returns: A newly allocated string that must
41132 * be freed with g_free()
41137 * g_unix_mount_point_guess_symbolic_icon:
41138 * @mount_point: a #GUnixMountPoint
41140 * Guesses the symbolic icon of a Unix mount point.
41142 * Returns: (transfer full): a #GIcon
41148 * g_unix_mount_point_guess_type:
41149 * @mount_point: a #GUnixMountPoint.
41151 * Guesses the type of a unix mount point.
41152 * If the mount type cannot be determined,
41153 * returns %G_UNIX_MOUNT_TYPE_UNKNOWN.
41155 * Returns: a #GUnixMountType.
41160 * g_unix_mount_point_is_loopback:
41161 * @mount_point: a #GUnixMountPoint.
41163 * Checks if a unix mount point is a loopback device.
41165 * Returns: %TRUE if the mount point is a loopback. %FALSE otherwise.
41170 * g_unix_mount_point_is_readonly:
41171 * @mount_point: a #GUnixMountPoint.
41173 * Checks if a unix mount point is read only.
41175 * Returns: %TRUE if a mount point is read only.
41180 * g_unix_mount_point_is_user_mountable:
41181 * @mount_point: a #GUnixMountPoint.
41183 * Checks if a unix mount point is mountable by the user.
41185 * Returns: %TRUE if the mount point is user mountable.
41190 * g_unix_mount_points_changed_since:
41191 * @time: guint64 to contain a timestamp.
41193 * Checks if the unix mount points have changed since a given unix time.
41195 * Returns: %TRUE if the mount points have changed since @time.
41200 * g_unix_mount_points_get: (skip)
41201 * @time_read: (out) (allow-none): guint64 to contain a timestamp.
41203 * Gets a #GList of #GUnixMountPoint containing the unix mount points.
41204 * If @time_read is set, it will be filled with the mount timestamp,
41205 * allowing for checking if the mounts have changed with
41206 * g_unix_mount_points_changed_since().
41208 * Returns: (element-type GUnixMountPoint) (transfer full):
41209 * a #GList of the UNIX mountpoints.
41214 * g_unix_mounts_changed_since:
41215 * @time: guint64 to contain a timestamp.
41217 * Checks if the unix mounts have changed since a given unix time.
41219 * Returns: %TRUE if the mounts have changed since @time.
41224 * g_unix_mounts_get: (skip)
41225 * @time_read: (out) (allow-none): guint64 to contain a timestamp, or %NULL
41227 * Gets a #GList of #GUnixMountEntry containing the unix mounts.
41228 * If @time_read is set, it will be filled with the mount
41229 * timestamp, allowing for checking if the mounts have changed
41230 * with g_unix_mounts_changed_since().
41232 * Returns: (element-type GUnixMountEntry) (transfer full):
41233 * a #GList of the UNIX mounts.
41238 * g_unix_output_stream_get_close_fd:
41239 * @stream: a #GUnixOutputStream
41241 * Returns whether the file descriptor of @stream will be
41242 * closed when the stream is closed.
41244 * Returns: %TRUE if the file descriptor is closed when done
41250 * g_unix_output_stream_get_fd:
41251 * @stream: a #GUnixOutputStream
41253 * Return the UNIX file descriptor that the stream writes to.
41255 * Returns: The file descriptor of @stream
41261 * g_unix_output_stream_new:
41262 * @fd: a UNIX file descriptor
41263 * @close_fd: %TRUE to close the file descriptor when done
41265 * Creates a new #GUnixOutputStream for the given @fd.
41267 * If @close_fd, is %TRUE, the file descriptor will be closed when
41268 * the output stream is destroyed.
41270 * Returns: a new #GOutputStream
41275 * g_unix_output_stream_set_close_fd:
41276 * @stream: a #GUnixOutputStream
41277 * @close_fd: %TRUE to close the file descriptor when done
41279 * Sets whether the file descriptor of @stream shall be closed
41280 * when the stream is closed.
41287 * g_unix_socket_address_abstract_names_supported:
41289 * Checks if abstract UNIX domain socket names are supported.
41291 * Returns: %TRUE if supported, %FALSE otherwise
41297 * g_unix_socket_address_get_address_type:
41298 * @address: a #GInetSocketAddress
41300 * Gets @address's type.
41302 * Returns: a #GUnixSocketAddressType
41308 * g_unix_socket_address_get_is_abstract:
41309 * @address: a #GInetSocketAddress
41311 * Tests if @address is abstract.
41313 * Returns: %TRUE if the address is abstract, %FALSE otherwise
41315 * Deprecated: Use g_unix_socket_address_get_address_type()
41320 * g_unix_socket_address_get_path:
41321 * @address: a #GInetSocketAddress
41323 * Gets @address's path, or for abstract sockets the "name".
41325 * Guaranteed to be zero-terminated, but an abstract socket
41326 * may contain embedded zeros, and thus you should use
41327 * g_unix_socket_address_get_path_len() to get the true length
41330 * Returns: the path for @address
41336 * g_unix_socket_address_get_path_len:
41337 * @address: a #GInetSocketAddress
41339 * Gets the length of @address's path.
41341 * For details, see g_unix_socket_address_get_path().
41343 * Returns: the length of the path
41349 * g_unix_socket_address_new:
41350 * @path: the socket path
41352 * Creates a new #GUnixSocketAddress for @path.
41354 * To create abstract socket addresses, on systems that support that,
41355 * use g_unix_socket_address_new_abstract().
41357 * Returns: a new #GUnixSocketAddress
41363 * g_unix_socket_address_new_abstract:
41364 * @path: (array length=path_len) (element-type gchar): the abstract name
41365 * @path_len: the length of @path, or -1
41367 * Creates a new %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED
41368 * #GUnixSocketAddress for @path.
41370 * Returns: a new #GUnixSocketAddress
41371 * Deprecated: Use g_unix_socket_address_new_with_type().
41376 * g_unix_socket_address_new_with_type:
41377 * @path: (array length=path_len) (element-type gchar): the name
41378 * @path_len: the length of @path, or -1
41379 * @type: a #GUnixSocketAddressType
41381 * Creates a new #GUnixSocketAddress of type @type with name @path.
41383 * If @type is %G_UNIX_SOCKET_ADDRESS_PATH, this is equivalent to
41384 * calling g_unix_socket_address_new().
41386 * If @type is %G_UNIX_SOCKET_ADDRESS_ANONYMOUS, @path and @path_len will be
41389 * If @path_type is %G_UNIX_SOCKET_ADDRESS_ABSTRACT, then @path_len
41390 * bytes of @path will be copied to the socket's path, and only those
41391 * bytes will be considered part of the name. (If @path_len is -1,
41392 * then @path is assumed to be NUL-terminated.) For example, if @path
41393 * was "test", then calling g_socket_address_get_native_size() on the
41394 * returned socket would return 7 (2 bytes of overhead, 1 byte for the
41395 * abstract-socket indicator byte, and 4 bytes for the name "test").
41397 * If @path_type is %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED, then
41398 * @path_len bytes of @path will be copied to the socket's path, the
41399 * rest of the path will be padded with 0 bytes, and the entire
41400 * zero-padded buffer will be considered the name. (As above, if
41401 * @path_len is -1, then @path is assumed to be NUL-terminated.) In
41402 * this case, g_socket_address_get_native_size() will always return
41403 * the full size of a `struct sockaddr_un`, although
41404 * g_unix_socket_address_get_path_len() will still return just the
41407 * %G_UNIX_SOCKET_ADDRESS_ABSTRACT is preferred over
41408 * %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED for new programs. Of course,
41409 * when connecting to a server created by another process, you must
41410 * use the appropriate type corresponding to how that process created
41411 * its listening socket.
41413 * Returns: a new #GUnixSocketAddress
41419 * g_vfs_get_default:
41421 * Gets the default #GVfs for the system.
41423 * Returns: (transfer none): a #GVfs.
41428 * g_vfs_get_file_for_path:
41430 * @path: a string containing a VFS path.
41432 * Gets a #GFile for @path.
41434 * Returns: (transfer full): a #GFile.
41435 * Free the returned object with g_object_unref().
41440 * g_vfs_get_file_for_uri:
41442 * @uri: a string containing a URI
41444 * Gets a #GFile for @uri.
41446 * This operation never fails, but the returned object
41447 * might not support any I/O operation if the URI
41448 * is malformed or if the URI scheme is not supported.
41450 * Returns: (transfer full): a #GFile.
41451 * Free the returned object with g_object_unref().
41458 * Gets the local #GVfs for the system.
41460 * Returns: (transfer none): a #GVfs.
41465 * g_vfs_get_supported_uri_schemes:
41468 * Gets a list of URI schemes supported by @vfs.
41470 * Returns: (transfer none): a %NULL-terminated array of strings.
41471 * The returned array belongs to GIO and must
41472 * not be freed or modified.
41480 * Checks if the VFS is active.
41482 * Returns: %TRUE if construction of the @vfs was successful
41483 * and it is now active.
41488 * g_vfs_parse_name:
41490 * @parse_name: a string to be parsed by the VFS module.
41492 * This operation never fails, but the returned object might
41493 * not support any I/O operations if the @parse_name cannot
41494 * be parsed by the #GVfs module.
41496 * Returns: (transfer full): a #GFile for the given @parse_name.
41497 * Free the returned object with g_object_unref().
41502 * g_vfs_register_uri_scheme:
41504 * @scheme: an URI scheme, e.g. "http"
41505 * @uri_func: (scope notified) (nullable): a #GVfsFileLookupFunc
41506 * @uri_data: (nullable): custom data passed to be passed to @uri_func, or %NULL
41507 * @uri_destroy: (nullable): function to be called when unregistering the
41508 * URI scheme, or when @vfs is disposed, to free the resources used
41509 * by the URI lookup function
41510 * @parse_name_func: (scope notified) (nullable): a #GVfsFileLookupFunc
41511 * @parse_name_data: (nullable): custom data passed to be passed to
41512 * @parse_name_func, or %NULL
41513 * @parse_name_destroy: (nullable): function to be called when unregistering the
41514 * URI scheme, or when @vfs is disposed, to free the resources used
41515 * by the parse name lookup function
41517 * Registers @uri_func and @parse_name_func as the #GFile URI and parse name
41518 * lookup functions for URIs with a scheme matching @scheme.
41519 * Note that @scheme is registered only within the running application, as
41520 * opposed to desktop-wide as it happens with GVfs backends.
41522 * When a #GFile is requested with an URI containing @scheme (e.g. through
41523 * g_file_new_for_uri()), @uri_func will be called to allow a custom
41524 * constructor. The implementation of @uri_func should not be blocking, and
41525 * must not call g_vfs_register_uri_scheme() or g_vfs_unregister_uri_scheme().
41527 * When g_file_parse_name() is called with a parse name obtained from such file,
41528 * @parse_name_func will be called to allow the #GFile to be created again. In
41529 * that case, it's responsibility of @parse_name_func to make sure the parse
41530 * name matches what the custom #GFile implementation returned when
41531 * g_file_get_parse_name() was previously called. The implementation of
41532 * @parse_name_func should not be blocking, and must not call
41533 * g_vfs_register_uri_scheme() or g_vfs_unregister_uri_scheme().
41535 * It's an error to call this function twice with the same scheme. To unregister
41536 * a custom URI scheme, use g_vfs_unregister_uri_scheme().
41538 * Returns: %TRUE if @scheme was successfully registered, or %FALSE if a handler
41539 * for @scheme already exists.
41545 * g_vfs_unregister_uri_scheme:
41547 * @scheme: an URI scheme, e.g. "http"
41549 * Unregisters the URI handler for @scheme previously registered with
41550 * g_vfs_register_uri_scheme().
41552 * Returns: %TRUE if @scheme was successfully unregistered, or %FALSE if a
41553 * handler for @scheme does not exist.
41559 * g_volume_can_eject:
41560 * @volume: a #GVolume
41562 * Checks if a volume can be ejected.
41564 * Returns: %TRUE if the @volume can be ejected. %FALSE otherwise
41569 * g_volume_can_mount:
41570 * @volume: a #GVolume
41572 * Checks if a volume can be mounted.
41574 * Returns: %TRUE if the @volume can be mounted. %FALSE otherwise
41580 * @volume: a #GVolume
41581 * @flags: flags affecting the unmount if required for eject
41582 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
41583 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL
41584 * @user_data: user data that gets passed to @callback
41586 * Ejects a volume. This is an asynchronous operation, and is
41587 * finished by calling g_volume_eject_finish() with the @volume
41588 * and #GAsyncResult returned in the @callback.
41590 * Deprecated: 2.22: Use g_volume_eject_with_operation() instead.
41595 * g_volume_eject_finish:
41596 * @volume: pointer to a #GVolume
41597 * @result: a #GAsyncResult
41598 * @error: a #GError location to store an error, or %NULL to ignore
41600 * Finishes ejecting a volume. If any errors occurred during the operation,
41601 * @error will be set to contain the errors and %FALSE will be returned.
41603 * Returns: %TRUE, %FALSE if operation failed
41604 * Deprecated: 2.22: Use g_volume_eject_with_operation_finish() instead.
41609 * g_volume_eject_with_operation:
41610 * @volume: a #GVolume
41611 * @flags: flags affecting the unmount if required for eject
41612 * @mount_operation: (allow-none): a #GMountOperation or %NULL to
41613 * avoid user interaction
41614 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
41615 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL
41616 * @user_data: user data passed to @callback
41618 * Ejects a volume. This is an asynchronous operation, and is
41619 * finished by calling g_volume_eject_with_operation_finish() with the @volume
41620 * and #GAsyncResult data returned in the @callback.
41627 * g_volume_eject_with_operation_finish:
41628 * @volume: a #GVolume
41629 * @result: a #GAsyncResult
41630 * @error: a #GError location to store the error occurring, or %NULL
41632 * Finishes ejecting a volume. If any errors occurred during the operation,
41633 * @error will be set to contain the errors and %FALSE will be returned.
41635 * Returns: %TRUE if the volume was successfully ejected. %FALSE otherwise
41641 * g_volume_enumerate_identifiers:
41642 * @volume: a #GVolume
41644 * Gets the kinds of [identifiers][volume-identifier] that @volume has.
41645 * Use g_volume_get_identifier() to obtain the identifiers themselves.
41647 * Returns: (array zero-terminated=1) (transfer full): a %NULL-terminated array
41648 * of strings containing kinds of identifiers. Use g_strfreev() to free.
41653 * g_volume_get_activation_root:
41654 * @volume: a #GVolume
41656 * Gets the activation root for a #GVolume if it is known ahead of
41657 * mount time. Returns %NULL otherwise. If not %NULL and if @volume
41658 * is mounted, then the result of g_mount_get_root() on the
41659 * #GMount object obtained from g_volume_get_mount() will always
41660 * either be equal or a prefix of what this function returns. In
41661 * other words, in code
41663 * |[<!-- language="C" -->
41665 * GFile *mount_root
41666 * GFile *volume_activation_root;
41668 * mount = g_volume_get_mount (volume); // mounted, so never NULL
41669 * mount_root = g_mount_get_root (mount);
41670 * volume_activation_root = g_volume_get_activation_root (volume); // assume not NULL
41672 * then the expression
41673 * |[<!-- language="C" -->
41674 * (g_file_has_prefix (volume_activation_root, mount_root) ||
41675 * g_file_equal (volume_activation_root, mount_root))
41677 * will always be %TRUE.
41679 * Activation roots are typically used in #GVolumeMonitor
41680 * implementations to find the underlying mount to shadow, see
41681 * g_mount_is_shadowed() for more details.
41683 * Returns: (nullable) (transfer full): the activation root of @volume
41684 * or %NULL. Use g_object_unref() to free.
41690 * g_volume_get_drive:
41691 * @volume: a #GVolume
41693 * Gets the drive for the @volume.
41695 * Returns: (transfer full): a #GDrive or %NULL if @volume is not
41696 * associated with a drive. The returned object should be unreffed
41697 * with g_object_unref() when no longer needed.
41702 * g_volume_get_icon:
41703 * @volume: a #GVolume
41705 * Gets the icon for @volume.
41707 * Returns: (transfer full): a #GIcon.
41708 * The returned object should be unreffed with g_object_unref()
41709 * when no longer needed.
41714 * g_volume_get_identifier:
41715 * @volume: a #GVolume
41716 * @kind: the kind of identifier to return
41718 * Gets the identifier of the given kind for @volume.
41719 * See the [introduction][volume-identifier] for more
41720 * information about volume identifiers.
41722 * Returns: a newly allocated string containing the
41723 * requested identfier, or %NULL if the #GVolume
41724 * doesn't have this kind of identifier
41729 * g_volume_get_mount:
41730 * @volume: a #GVolume
41732 * Gets the mount for the @volume.
41734 * Returns: (transfer full): a #GMount or %NULL if @volume isn't mounted.
41735 * The returned object should be unreffed with g_object_unref()
41736 * when no longer needed.
41741 * g_volume_get_name:
41742 * @volume: a #GVolume
41744 * Gets the name of @volume.
41746 * Returns: the name for the given @volume. The returned string should
41747 * be freed with g_free() when no longer needed.
41752 * g_volume_get_sort_key:
41753 * @volume: a #GVolume
41755 * Gets the sort key for @volume, if any.
41757 * Returns: Sorting key for @volume or %NULL if no such key is available
41763 * g_volume_get_symbolic_icon:
41764 * @volume: a #GVolume
41766 * Gets the symbolic icon for @volume.
41768 * Returns: (transfer full): a #GIcon.
41769 * The returned object should be unreffed with g_object_unref()
41770 * when no longer needed.
41776 * g_volume_get_uuid:
41777 * @volume: a #GVolume
41779 * Gets the UUID for the @volume. The reference is typically based on
41780 * the file system UUID for the volume in question and should be
41781 * considered an opaque string. Returns %NULL if there is no UUID
41784 * Returns: the UUID for @volume or %NULL if no UUID can be computed.
41785 * The returned string should be freed with g_free()
41786 * when no longer needed.
41791 * g_volume_monitor_adopt_orphan_mount:
41792 * @mount: a #GMount object to find a parent for
41794 * This function should be called by any #GVolumeMonitor
41795 * implementation when a new #GMount object is created that is not
41796 * associated with a #GVolume object. It must be called just before
41797 * emitting the @mount_added signal.
41799 * If the return value is not %NULL, the caller must associate the
41800 * returned #GVolume object with the #GMount. This involves returning
41801 * it in its g_mount_get_volume() implementation. The caller must
41802 * also listen for the "removed" signal on the returned object
41803 * and give up its reference when handling that signal
41805 * Similary, if implementing g_volume_monitor_adopt_orphan_mount(),
41806 * the implementor must take a reference to @mount and return it in
41807 * its g_volume_get_mount() implemented. Also, the implementor must
41808 * listen for the "unmounted" signal on @mount and give up its
41809 * reference upon handling that signal.
41811 * There are two main use cases for this function.
41813 * One is when implementing a user space file system driver that reads
41814 * blocks of a block device that is already represented by the native
41815 * volume monitor (for example a CD Audio file system driver). Such
41816 * a driver will generate its own #GMount object that needs to be
41817 * associated with the #GVolume object that represents the volume.
41819 * The other is for implementing a #GVolumeMonitor whose sole purpose
41820 * is to return #GVolume objects representing entries in the users
41821 * "favorite servers" list or similar.
41823 * Returns: (transfer full): the #GVolume object that is the parent for @mount or %NULL
41824 * if no wants to adopt the #GMount.
41825 * Deprecated: 2.20: Instead of using this function, #GVolumeMonitor
41826 * implementations should instead create shadow mounts with the URI of
41827 * the mount they intend to adopt. See the proxy volume monitor in
41828 * gvfs for an example of this. Also see g_mount_is_shadowed(),
41829 * g_mount_shadow() and g_mount_unshadow() functions.
41834 * g_volume_monitor_get:
41836 * Gets the volume monitor used by gio.
41838 * Returns: (transfer full): a reference to the #GVolumeMonitor used by gio. Call
41839 * g_object_unref() when done with it.
41844 * g_volume_monitor_get_connected_drives:
41845 * @volume_monitor: a #GVolumeMonitor.
41847 * Gets a list of drives connected to the system.
41849 * The returned list should be freed with g_list_free(), after
41850 * its elements have been unreffed with g_object_unref().
41852 * Returns: (element-type GDrive) (transfer full): a #GList of connected #GDrive objects.
41857 * g_volume_monitor_get_mount_for_uuid:
41858 * @volume_monitor: a #GVolumeMonitor.
41859 * @uuid: the UUID to look for
41861 * Finds a #GMount object by its UUID (see g_mount_get_uuid())
41863 * Returns: (transfer full): a #GMount or %NULL if no such mount is available.
41864 * Free the returned object with g_object_unref().
41869 * g_volume_monitor_get_mounts:
41870 * @volume_monitor: a #GVolumeMonitor.
41872 * Gets a list of the mounts on the system.
41874 * The returned list should be freed with g_list_free(), after
41875 * its elements have been unreffed with g_object_unref().
41877 * Returns: (element-type GMount) (transfer full): a #GList of #GMount objects.
41882 * g_volume_monitor_get_volume_for_uuid:
41883 * @volume_monitor: a #GVolumeMonitor.
41884 * @uuid: the UUID to look for
41886 * Finds a #GVolume object by its UUID (see g_volume_get_uuid())
41888 * Returns: (transfer full): a #GVolume or %NULL if no such volume is available.
41889 * Free the returned object with g_object_unref().
41894 * g_volume_monitor_get_volumes:
41895 * @volume_monitor: a #GVolumeMonitor.
41897 * Gets a list of the volumes on the system.
41899 * The returned list should be freed with g_list_free(), after
41900 * its elements have been unreffed with g_object_unref().
41902 * Returns: (element-type GVolume) (transfer full): a #GList of #GVolume objects.
41907 * g_volume_mount: (virtual mount_fn)
41908 * @volume: a #GVolume
41909 * @flags: flags affecting the operation
41910 * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction
41911 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
41912 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL
41913 * @user_data: user data that gets passed to @callback
41915 * Mounts a volume. This is an asynchronous operation, and is
41916 * finished by calling g_volume_mount_finish() with the @volume
41917 * and #GAsyncResult returned in the @callback.
41922 * g_volume_mount_finish:
41923 * @volume: a #GVolume
41924 * @result: a #GAsyncResult
41925 * @error: a #GError location to store an error, or %NULL to ignore
41927 * Finishes mounting a volume. If any errors occurred during the operation,
41928 * @error will be set to contain the errors and %FALSE will be returned.
41930 * If the mount operation succeeded, g_volume_get_mount() on @volume
41931 * is guaranteed to return the mount right after calling this
41932 * function; there's no need to listen for the 'mount-added' signal on
41935 * Returns: %TRUE, %FALSE if operation failed
41940 * g_volume_should_automount:
41941 * @volume: a #GVolume
41943 * Returns whether the volume should be automatically mounted.
41945 * Returns: %TRUE if the volume should be automatically mounted
41950 * g_win32_input_stream_get_close_handle:
41951 * @stream: a #GWin32InputStream
41953 * Returns whether the handle of @stream will be
41954 * closed when the stream is closed.
41956 * Returns: %TRUE if the handle is closed when done
41962 * g_win32_input_stream_get_handle:
41963 * @stream: a #GWin32InputStream
41965 * Return the Windows file handle that the stream reads from.
41967 * Returns: The file handle of @stream
41973 * g_win32_input_stream_new:
41974 * @handle: a Win32 file handle
41975 * @close_handle: %TRUE to close the handle when done
41977 * Creates a new #GWin32InputStream for the given @handle.
41979 * If @close_handle is %TRUE, the handle will be closed
41980 * when the stream is closed.
41982 * Note that "handle" here means a Win32 HANDLE, not a "file descriptor"
41983 * as used in the Windows C libraries.
41985 * Returns: a new #GWin32InputStream
41990 * g_win32_input_stream_set_close_handle:
41991 * @stream: a #GWin32InputStream
41992 * @close_handle: %TRUE to close the handle when done
41994 * Sets whether the handle of @stream shall be closed
41995 * when the stream is closed.
42002 * g_win32_output_stream_get_close_handle:
42003 * @stream: a #GWin32OutputStream
42005 * Returns whether the handle of @stream will be closed when the
42006 * stream is closed.
42008 * Returns: %TRUE if the handle is closed when done
42014 * g_win32_output_stream_get_handle:
42015 * @stream: a #GWin32OutputStream
42017 * Return the Windows handle that the stream writes to.
42019 * Returns: The handle descriptor of @stream
42025 * g_win32_output_stream_new:
42026 * @handle: a Win32 file handle
42027 * @close_handle: %TRUE to close the handle when done
42029 * Creates a new #GWin32OutputStream for the given @handle.
42031 * If @close_handle, is %TRUE, the handle will be closed when the
42032 * output stream is destroyed.
42034 * Returns: a new #GOutputStream
42040 * g_win32_output_stream_set_close_handle:
42041 * @stream: a #GWin32OutputStream
42042 * @close_handle: %TRUE to close the handle when done
42044 * Sets whether the handle of @stream shall be closed when the stream
42052 * g_win32_registry_key_erase_change_indicator:
42053 * @key: (in) (transfer none): a #GWin32RegistryKey
42055 * Erases change indicator of the @key.
42057 * Subsequent calls to g_win32_registry_key_has_changed() will return %FALSE
42058 * until the key is put on watch again by calling
42059 * g_win32_registry_key_watch() again.
42066 * g_win32_registry_key_get_child:
42067 * @key: (in) (transfer none): a parent #GWin32RegistryKey
42068 * @subkey: (in) (transfer none): name of a child key to open (in UTF-8), relative to @key
42069 * @error: (inout) (nullable): a pointer to a %NULL #GError, or %NULL
42071 * Opens a @subkey of the @key.
42073 * Returns: (nullable): a #GWin32RegistryKey or %NULL if can't be opened. Free
42074 * with g_object_unref().
42079 * g_win32_registry_key_get_child_w:
42080 * @key: (in) (transfer none): a parent #GWin32RegistryKey
42081 * @subkey: (in) (transfer none): name of a child key to open (in UTF-8), relative to @key
42082 * @error: (inout) (nullable): a pointer to a %NULL #GError, or %NULL
42084 * Opens a @subkey of the @key.
42086 * Returns: (nullable): a #GWin32RegistryKey or %NULL if can't be opened. Free
42087 * with g_object_unref().
42092 * g_win32_registry_key_get_path:
42093 * @key: (in) (transfer none): a #GWin32RegistryKey
42095 * Get full path to the key
42097 * Returns: (transfer none): a full path to the key (in UTF-8),
42098 * or %NULL if it can't be converted to UTF-8.
42104 * g_win32_registry_key_get_path_w:
42105 * @key: (in) (transfer none): a #GWin32RegistryKey
42107 * Get full path to the key
42109 * Returns: (transfer none): a full path to the key (in UTF-16)
42115 * g_win32_registry_key_get_value:
42116 * @key: (in) (transfer none): a #GWin32RegistryKey
42117 * @auto_expand: (in): %TRUE to automatically expand G_WIN32_REGISTRY_VALUE_EXPAND_STR
42118 * to G_WIN32_REGISTRY_VALUE_STR.
42119 * @value_name: (in) (transfer none): name of the value to get (in UTF-8).
42120 * Empty string means the '(Default)' value.
42121 * @value_type: (out) (optional): type of the value retrieved.
42122 * @value_data: (out callee-allocates) (optional): contents of the value.
42123 * @value_data_size: (out) (optional): size of the buffer pointed
42125 * @error: (nullable): a pointer to %NULL #GError, or %NULL
42127 * Get data from a value of a key. String data is guaranteed to be
42128 * appropriately terminated and will be in UTF-8.
42130 * Returns: %TRUE on success, %FALSE on failure.
42136 * g_win32_registry_key_get_value_w:
42137 * @key: (in) (transfer none): a #GWin32RegistryKey
42138 * @auto_expand: (in): %TRUE to automatically expand G_WIN32_REGISTRY_VALUE_EXPAND_STR
42139 * to G_WIN32_REGISTRY_VALUE_STR.
42140 * @value_name: (in) (transfer none): name of the value to get (in UTF-16).
42141 * Empty string means the '(Default)' value.
42142 * @value_type: (out) (optional): type of the value retrieved.
42143 * @value_data: (out callee-allocates) (optional): contents of the value.
42144 * @value_data_size: (out) (optional): size of the buffer pointed
42146 * @error: (nullable): a pointer to %NULL #GError, or %NULL
42148 * Get data from a value of a key.
42150 * Get data from a value of a key. String data is guaranteed to be
42151 * appropriately terminated and will be in UTF-16.
42153 * When calling with value_data == NULL (to get data size without getting
42154 * the data itself) remember that returned size corresponds to possibly
42155 * unterminated string data (if value is some kind of string), because
42156 * termination cannot be checked and fixed unless the data is retreived
42159 * Returns: %TRUE on success, %FALSE on failure.
42165 * g_win32_registry_key_has_changed:
42166 * @key: (in) (transfer none): a #GWin32RegistryKey
42168 * Check the @key's status indicator.
42170 * Returns: %TRUE if the @key was put under watch at some point and has changed
42171 * since then, %FALSE if it either wasn't changed or wasn't watched at all.
42177 * g_win32_registry_key_new:
42178 * @path: absolute full name of a key to open (in UTF-8)
42179 * @error: (nullable): a pointer to a %NULL #GError, or %NULL
42181 * Creates an object that represents a registry key specified by @path.
42182 * @path must start with one of the following pre-defined names:
42183 * - HKEY_CLASSES_ROOT
42184 * - HKEY_CURRENT_CONFIG
42185 * - HKEY_CURRENT_USER
42186 * - HKEY_CURRENT_USER_LOCAL_SETTINGS
42187 * - HKEY_LOCAL_MACHINE
42188 * - HKEY_PERFORMANCE_DATA
42189 * - HKEY_PERFORMANCE_NLSTEXT
42190 * - HKEY_PERFORMANCE_TEXT
42192 * @path must not end with '\\'.
42194 * Returns: (nullable) (transfer full): a #GWin32RegistryKey or %NULL if can't
42195 * be opened. Free with g_object_unref().
42200 * g_win32_registry_key_new_w:
42201 * @path: (in) (transfer none): absolute full name of a key to open (in UTF-16)
42202 * @error: (inout) (nullable): a pointer to a %NULL #GError, or %NULL
42204 * Creates an object that represents a registry key specified by @path.
42205 * @path must start with one of the following pre-defined names:
42206 * - HKEY_CLASSES_ROOT
42207 * - HKEY_CURRENT_CONFIG
42208 * - HKEY_CURRENT_USER
42209 * - HKEY_CURRENT_USER_LOCAL_SETTINGS
42210 * - HKEY_LOCAL_MACHINE
42211 * - HKEY_PERFORMANCE_DATA
42212 * - HKEY_PERFORMANCE_NLSTEXT
42213 * - HKEY_PERFORMANCE_TEXT
42215 * @path must not end with L'\\'.
42217 * Returns: (nullable) (transfer full): a #GWin32RegistryKey or %NULL if can't
42218 * be opened. Free with g_object_unref().
42223 * g_win32_registry_key_watch:
42224 * @key: (in) (transfer none): a #GWin32RegistryKey
42225 * @watch_children: (in): %TRUE also watch the children of the @key, %FALSE
42226 * to watch the key only.
42227 * @watch_flags: (in): specifies the types of changes to watch for.
42228 * @callback: (in) (nullable): a function to invoke when a change occurs.
42229 * @user_data: (in) (nullable): a pointer to pass to @callback on invocation.
42230 * @error: (nullable): a pointer to %NULL #GError, or %NULL
42232 * Puts @key under a watch.
42234 * When the key changes, an APC will be queued in the current thread. The APC
42235 * will run when the current thread enters alertable state (GLib main loop
42236 * should do that; if you are not using it, see MSDN documentation for W32API
42237 * calls that put thread into alertable state). When it runs, it will
42238 * atomically switch an indicator in the @key. If a callback was specified,
42239 * it is invoked at that point. Subsequent calls to
42240 * g_win32_registry_key_has_changed() will return %TRUE, and the callback (if
42241 * it was specified) will not be invoked anymore.
42242 * Calling g_win32_registry_key_erase_change_indicator() will reset the indicator,
42243 * and g_win32_registry_key_has_changed() will start returning %FALSE.
42244 * To resume the watch, call g_win32_registry_key_watch_for_changes() again.
42246 * Calling g_win32_registry_key_watch_for_changes() for a key that is already
42247 * being watched is allowed and affects nothing.
42249 * The fact that the key is being watched will be used internally to update
42250 * key path (if it changes).
42252 * Returns: %TRUE on success, %FALSE on failure.
42258 * g_win32_registry_subkey_iter_assign:
42259 * @iter: a #GWin32RegistrySubkeyIter
42260 * @other: another #GWin32RegistrySubkeyIter
42262 * Assigns the value of @other to @iter. This function
42263 * is not useful in applications, because iterators can be assigned
42264 * with `GWin32RegistrySubkeyIter i = j;`. The
42265 * function is used by language bindings.
42272 * g_win32_registry_subkey_iter_clear:
42273 * @iter: (in) (transfer none): a #GWin32RegistrySubkeyIter
42275 * Frees internal buffers of a #GWin32RegistrySubkeyIter.
42282 * g_win32_registry_subkey_iter_copy:
42283 * @iter: an iterator
42285 * Creates a dynamically-allocated copy of an iterator. Dynamically-allocated
42286 * state of the iterator is duplicated too.
42288 * Returns: (transfer full): a copy of the @iter,
42289 * free with g_win32_registry_subkey_iter_free ()
42295 * g_win32_registry_subkey_iter_free:
42296 * @iter: a dynamically-allocated iterator
42298 * Free an iterator allocated on the heap. For iterators that are allocated
42299 * on the stack use g_win32_registry_subkey_iter_clear () instead.
42306 * g_win32_registry_subkey_iter_get_name:
42307 * @iter: (in) (transfer none): a #GWin32RegistrySubkeyIter
42308 * @subkey_name: (out callee-allocates) (transfer none): Pointer to a location
42309 * to store the name of a subkey (in UTF-8). Free with g_free().
42310 * @subkey_name_len: (out) (optional): Pointer to a location to store the
42311 * length of @subkey_name, in gchars, excluding NUL-terminator.
42312 * %NULL if length is not needed.
42313 * @error: (nullable): a pointer to %NULL #GError, or %NULL
42315 * Gets the name of the subkey at the @iter potision.
42317 * Returns: %TRUE if the name was retrieved, %FALSE otherwise.
42323 * g_win32_registry_subkey_iter_get_name_w:
42324 * @iter: (in) (transfer none): a #GWin32RegistrySubkeyIter
42325 * @subkey_name: (out callee-allocates) (transfer none): Pointer to a location
42326 * to store the name of a subkey (in UTF-16).
42327 * @subkey_name_len: (out) (optional) (transfer none): Pointer to a location
42328 * to store the length of @subkey_name, in gunichar2s, excluding
42330 * %NULL if length is not needed.
42331 * @error: (nullable): a pointer to %NULL #GError, or %NULL
42333 * Same as g_win32_registry_subkey_iter_get_next(), but outputs UTF-16-encoded
42334 * data, without converting it to UTF-8 first.
42336 * Returns: %TRUE if the name was retrieved, %FALSE otherwise.
42342 * g_win32_registry_subkey_iter_init:
42343 * @iter: (in) (transfer none): a pointer to a #GWin32RegistrySubkeyIter
42344 * @key: (in) (transfer none): a #GWin32RegistryKey to iterate over
42345 * @error: (inout) (nullable): a pointer to %NULL #GError, or %NULL
42347 * Initialises (without allocating) a #GWin32RegistrySubkeyIter. @iter may be
42348 * completely uninitialised prior to this call; its old value is
42351 * The iterator remains valid for as long as @key exists.
42352 * Clean up its internal buffers with a call to
42353 * g_win32_registry_subkey_iter_clear() when done.
42355 * Returns: %TRUE if iterator was initialized successfully, %FALSE on error.
42361 * g_win32_registry_subkey_iter_n_subkeys:
42362 * @iter: (in) (transfer none): a #GWin32RegistrySubkeyIter
42364 * Queries the number of subkeys items in the key that we are
42365 * iterating over. This is the total number of subkeys -- not the number
42366 * of items remaining.
42368 * This information is accurate at the point of iterator initialization,
42369 * and may go out of sync with reality even while subkeys are enumerated.
42371 * Returns: the number of subkeys in the key
42377 * g_win32_registry_subkey_iter_next:
42378 * @iter: (in) (transfer none): a #GWin32RegistrySubkeyIter
42379 * @skip_errors: (in): %TRUE if iterator should silently ignore errors (such as
42380 * the actual number of subkeys being less than expected) and
42382 * @error: (nullable): a pointer to %NULL #GError, or %NULL
42384 * Moves iterator to the next subkey.
42385 * Enumeration errors can be ignored if @skip_errors is %TRUE
42387 * Here is an example for iterating with g_win32_registry_subkey_iter_next():
42388 * |[<!-- language="C" -->
42389 * // recursively iterate a key
42391 * iterate_key_recursive (GWin32RegistryKey *key)
42393 * GWin32RegistrySubkeyIter iter;
42395 * GWin32RegistryKey *child;
42397 * if (!g_win32_registry_subkey_iter_init (&iter, key, NULL))
42400 * while (g_win32_registry_subkey_iter_next (&iter, TRUE, NULL))
42402 * if (!g_win32_registry_subkey_iter_get_name (&iter, &name, NULL, NULL))
42405 * g_print ("subkey '%s'\n", name);
42406 * child = g_win32_registry_key_get_child (key, name, NULL);
42409 * iterate_key_recursive (child);
42412 * g_win32_registry_subkey_iter_clear (&iter);
42416 * Returns: %TRUE if next subkey info was retrieved, %FALSE otherwise.
42422 * g_win32_registry_value_iter_assign:
42423 * @iter: a #GWin32RegistryValueIter
42424 * @other: another #GWin32RegistryValueIter
42426 * Assigns the value of @other to @iter. This function
42427 * is not useful in applications, because iterators can be assigned
42428 * with `GWin32RegistryValueIter i = j;`. The
42429 * function is used by language bindings.
42436 * g_win32_registry_value_iter_clear:
42437 * @iter: (in) (transfer none): a #GWin32RegistryValueIter
42439 * Frees internal buffers of a #GWin32RegistryValueIter.
42446 * g_win32_registry_value_iter_copy:
42447 * @iter: an iterator
42449 * Creates a dynamically-allocated copy of an iterator. Dynamically-allocated
42450 * state of the iterator is duplicated too.
42452 * Returns: (transfer full): a copy of the @iter,
42453 * free with g_win32_registry_value_iter_free ().
42459 * g_win32_registry_value_iter_free:
42460 * @iter: a dynamically-allocated iterator
42462 * Free an iterator allocated on the heap. For iterators that are allocated
42463 * on the stack use g_win32_registry_value_iter_clear () instead.
42470 * g_win32_registry_value_iter_get_data:
42471 * @iter: (in) (transfer none): a #GWin32RegistryValueIter
42472 * @auto_expand: (in): %TRUE to automatically expand G_WIN32_REGISTRY_VALUE_EXPAND_STR to
42473 * G_WIN32_REGISTRY_VALUE_STR
42474 * @value_data: (out callee-allocates) (optional) (transfer none): Pointer to a
42475 * location to store the data of the value (in UTF-8, if it's a string)
42476 * @value_data_size: (out) (optional): Pointer to a location to store the length
42477 * of @value_data, in bytes (including any NUL-terminators, if it's a string).
42478 * %NULL if length is not needed
42479 * @error: (nullable): a pointer to %NULL #GError, or %NULL
42481 * Stores the data of the value currently being iterated over in @value_data,
42482 * and its length - in @value_data_len (if not %NULL).
42484 * Returns: %TRUE if value data was retrieved, %FALSE otherwise.
42490 * g_win32_registry_value_iter_get_data_w:
42491 * @iter: (in) (transfer none): a #GWin32RegistryValueIter
42492 * @auto_expand: (in): %TRUE to automatically expand G_WIN32_REGISTRY_VALUE_EXPAND_STR to
42493 * G_WIN32_REGISTRY_VALUE_STR
42494 * @value_data: (out callee-allocates) (optional) (transfer none): Pointer to a
42495 * location to store the data of the value (in UTF-16, if it's a string)
42496 * @value_data_size: (out) (optional): Pointer to a location to store the size
42497 * of @value_data, in bytes (including any NUL-terminators, if it's a string).
42498 * %NULL if length is not needed.
42499 * @error: (nullable): a pointer to %NULL #GError, or %NULL
42501 * Stores the data of the value currently being iterated over in @value_data,
42502 * and its length - in @value_data_len (if not %NULL).
42504 * Returns: %TRUE if value data was retrieved, %FALSE otherwise.
42510 * g_win32_registry_value_iter_get_name:
42511 * @iter: (in) (transfer none): a #GWin32RegistryValueIter
42512 * @value_name: (out callee-allocates) (transfer none): Pointer to a location
42513 * to store the name of a value (in UTF-8).
42514 * @value_name_len: (out) (optional): Pointer to a location to store the length
42515 * of @value_name, in gchars, excluding NUL-terminator.
42516 * %NULL if length is not needed.
42517 * @error: (nullable): a pointer to %NULL #GError, or %NULL
42519 * Stores the name of the value currently being iterated over in @value_name,
42520 * and its length - in @value_name_len (if not %NULL).
42522 * Returns: %TRUE if value name was retrieved, %FALSE otherwise.
42528 * g_win32_registry_value_iter_get_name_w:
42529 * @iter: (in) (transfer none): a #GWin32RegistryValueIter
42530 * @value_name: (out callee-allocates) (transfer none): Pointer to a location
42531 * to store the name of a value (in UTF-16).
42532 * @value_name_len: (out) (optional): Pointer to a location to store the length
42533 * of @value_name, in gunichar2s, excluding NUL-terminator.
42534 * %NULL if length is not needed.
42535 * @error: (nullable): a pointer to %NULL #GError, or %NULL
42537 * Stores the name of the value currently being iterated over in @value_name,
42538 * and its length - in @value_name (if not %NULL).
42540 * Returns: %TRUE if value name was retrieved, %FALSE otherwise.
42546 * g_win32_registry_value_iter_get_value_type:
42547 * @iter: (in) (transfer none): a #GWin32RegistryValueIter
42548 * @value_type: (out): Pointer to a location to store the type of
42550 * @error: (nullable): a pointer to %NULL #GError, or %NULL
42552 * Stores the type of the value currently being iterated over in @value_type.
42554 * Returns: %TRUE if value type was retrieved, %FALSE otherwise.
42560 * g_win32_registry_value_iter_init:
42561 * @iter: (in) (transfer none): a pointer to a #GWin32RegistryValueIter
42562 * @key: (in) (transfer none): a #GWin32RegistryKey to iterate over
42563 * @error: (nullable): a pointer to %NULL #GError, or %NULL
42565 * Initialises (without allocating) a #GWin32RegistryValueIter. @iter may be
42566 * completely uninitialised prior to this call; its old value is
42569 * The iterator remains valid for as long as @key exists.
42570 * Clean up its internal buffers with a call to
42571 * g_win32_registry_value_iter_clear() when done.
42573 * Returns: %TRUE if iterator was initialized successfully, %FALSE on error.
42579 * g_win32_registry_value_iter_n_values:
42580 * @iter: (in) (transfer none): a #GWin32RegistryValueIter
42582 * Queries the number of values items in the key that we are
42583 * iterating over. This is the total number of values -- not the number
42584 * of items remaining.
42586 * This information is accurate at the point of iterator initialization,
42587 * and may go out of sync with reality even while values are enumerated.
42589 * Returns: the number of values in the key
42595 * g_win32_registry_value_iter_next:
42596 * @iter: (in) (transfer none): a #GWin32RegistryValueIter
42597 * @skip_errors: (in): %TRUE if iterator should silently ignore errors (such as
42598 * the actual number of values being less than expected) and
42600 * @error: (nullable): a pointer to %NULL #GError, or %NULL
42602 * Advances iterator to the next value in the key. If no more values remain then
42603 * FALSE is returned.
42604 * Enumeration errors can be ignored if @skip_errors is %TRUE
42606 * Here is an example for iterating with g_win32_registry_value_iter_next():
42607 * |[<!-- language="C" -->
42608 * // iterate values of a key
42610 * iterate_values_recursive (GWin32RegistryKey *key)
42612 * GWin32RegistryValueIter iter;
42614 * GWin32RegistryValueType val_type;
42617 * if (!g_win32_registry_value_iter_init (&iter, key, NULL))
42620 * while (g_win32_registry_value_iter_next (&iter, TRUE, NULL))
42622 * if ((!g_win32_registry_value_iter_get_value_type (&iter, &value)) ||
42623 * ((val_type != G_WIN32_REGISTRY_VALUE_STR) &&
42624 * (val_type != G_WIN32_REGISTRY_VALUE_EXPAND_STR)))
42627 * if (g_win32_registry_value_iter_get_value (&iter, TRUE, &name, NULL,
42628 * &val_data, NULL, NULL))
42629 * g_print ("value '%s' = '%s'\n", name, val_data);
42632 * g_win32_registry_value_iter_clear (&iter);
42636 * Returns: %TRUE if next value info was retrieved, %FALSE otherwise.
42642 * g_zlib_compressor_get_file_info:
42643 * @compressor: a #GZlibCompressor
42645 * Returns the #GZlibCompressor:file-info property.
42647 * Returns: (transfer none): a #GFileInfo, or %NULL
42653 * g_zlib_compressor_new:
42654 * @format: The format to use for the compressed data
42655 * @level: compression level (0-9), -1 for default
42657 * Creates a new #GZlibCompressor.
42659 * Returns: a new #GZlibCompressor
42665 * g_zlib_compressor_set_file_info:
42666 * @compressor: a #GZlibCompressor
42667 * @file_info: (allow-none): a #GFileInfo
42669 * Sets @file_info in @compressor. If non-%NULL, and @compressor's
42670 * #GZlibCompressor:format property is %G_ZLIB_COMPRESSOR_FORMAT_GZIP,
42671 * it will be used to set the file name and modification time in
42672 * the GZIP header of the compressed data.
42674 * Note: it is an error to call this function while a compression is in
42675 * progress; it may only be called immediately after creation of @compressor,
42676 * or after resetting it with g_converter_reset().
42683 * g_zlib_decompressor_get_file_info:
42684 * @decompressor: a #GZlibDecompressor
42686 * Retrieves the #GFileInfo constructed from the GZIP header data
42687 * of compressed data processed by @compressor, or %NULL if @decompressor's
42688 * #GZlibDecompressor:format property is not %G_ZLIB_COMPRESSOR_FORMAT_GZIP,
42689 * or the header data was not fully processed yet, or it not present in the
42690 * data stream at all.
42692 * Returns: (transfer none): a #GFileInfo, or %NULL
42698 * g_zlib_decompressor_new:
42699 * @format: The format to use for the compressed data
42701 * Creates a new #GZlibDecompressor.
42703 * Returns: a new #GZlibDecompressor
42709 * get_viewable_logical_drives:
42711 * Returns the list of logical and viewable drives as defined by
42712 * GetLogicalDrives() and the registry keys
42713 * Software\Microsoft\Windows\CurrentVersion\Policies\Explorer under
42714 * HKLM or HKCU. If neither key exists the result of
42715 * GetLogicalDrives() is returned.
42717 * Returns: bitmask with same meaning as returned by GetLogicalDrives()
42722 * gxdp_documents_call_add:
42723 * @proxy: A #GXdpDocumentsProxy.
42724 * @arg_o_path_fd: Argument to pass with the method invocation.
42725 * @arg_reuse_existing: Argument to pass with the method invocation.
42726 * @arg_persistent: Argument to pass with the method invocation.
42727 * @fd_list: (allow-none): A #GUnixFDList or %NULL.
42728 * @cancellable: (allow-none): A #GCancellable or %NULL.
42729 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
42730 * @user_data: User data to pass to @callback.
42732 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-portal-Documents.Add">Add()</link> D-Bus method on @proxy.
42733 * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from.
42734 * You can then call gxdp_documents_call_add_finish() to get the result of the operation.
42736 * See gxdp_documents_call_add_sync() for the synchronous, blocking version of this method.
42741 * gxdp_documents_call_add_finish:
42742 * @proxy: A #GXdpDocumentsProxy.
42743 * @out_doc_id: (out): Return location for return parameter or %NULL to ignore.
42744 * @out_fd_list: (out): Return location for a #GUnixFDList or %NULL.
42745 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to gxdp_documents_call_add().
42746 * @error: Return location for error or %NULL.
42748 * Finishes an operation started with gxdp_documents_call_add().
42750 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
42755 * gxdp_documents_call_add_named:
42756 * @proxy: A #GXdpDocumentsProxy.
42757 * @arg_o_path_parent_fd: Argument to pass with the method invocation.
42758 * @arg_filename: Argument to pass with the method invocation.
42759 * @arg_reuse_existing: Argument to pass with the method invocation.
42760 * @arg_persistent: Argument to pass with the method invocation.
42761 * @fd_list: (allow-none): A #GUnixFDList or %NULL.
42762 * @cancellable: (allow-none): A #GCancellable or %NULL.
42763 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
42764 * @user_data: User data to pass to @callback.
42766 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-portal-Documents.AddNamed">AddNamed()</link> D-Bus method on @proxy.
42767 * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from.
42768 * You can then call gxdp_documents_call_add_named_finish() to get the result of the operation.
42770 * See gxdp_documents_call_add_named_sync() for the synchronous, blocking version of this method.
42775 * gxdp_documents_call_add_named_finish:
42776 * @proxy: A #GXdpDocumentsProxy.
42777 * @out_doc_id: (out): Return location for return parameter or %NULL to ignore.
42778 * @out_fd_list: (out): Return location for a #GUnixFDList or %NULL.
42779 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to gxdp_documents_call_add_named().
42780 * @error: Return location for error or %NULL.
42782 * Finishes an operation started with gxdp_documents_call_add_named().
42784 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
42789 * gxdp_documents_call_add_named_sync:
42790 * @proxy: A #GXdpDocumentsProxy.
42791 * @arg_o_path_parent_fd: Argument to pass with the method invocation.
42792 * @arg_filename: Argument to pass with the method invocation.
42793 * @arg_reuse_existing: Argument to pass with the method invocation.
42794 * @arg_persistent: Argument to pass with the method invocation.
42795 * @fd_list: (allow-none): A #GUnixFDList or %NULL.
42796 * @out_doc_id: (out): Return location for return parameter or %NULL to ignore.
42797 * @out_fd_list: (out): Return location for a #GUnixFDList or %NULL.
42798 * @cancellable: (allow-none): A #GCancellable or %NULL.
42799 * @error: Return location for error or %NULL.
42801 * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-portal-Documents.AddNamed">AddNamed()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
42803 * See gxdp_documents_call_add_named() for the asynchronous version of this method.
42805 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
42810 * gxdp_documents_call_add_sync:
42811 * @proxy: A #GXdpDocumentsProxy.
42812 * @arg_o_path_fd: Argument to pass with the method invocation.
42813 * @arg_reuse_existing: Argument to pass with the method invocation.
42814 * @arg_persistent: Argument to pass with the method invocation.
42815 * @fd_list: (allow-none): A #GUnixFDList or %NULL.
42816 * @out_doc_id: (out): Return location for return parameter or %NULL to ignore.
42817 * @out_fd_list: (out): Return location for a #GUnixFDList or %NULL.
42818 * @cancellable: (allow-none): A #GCancellable or %NULL.
42819 * @error: Return location for error or %NULL.
42821 * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-portal-Documents.Add">Add()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
42823 * See gxdp_documents_call_add() for the asynchronous version of this method.
42825 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
42830 * gxdp_documents_call_delete:
42831 * @proxy: A #GXdpDocumentsProxy.
42832 * @arg_doc_id: Argument to pass with the method invocation.
42833 * @cancellable: (allow-none): A #GCancellable or %NULL.
42834 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
42835 * @user_data: User data to pass to @callback.
42837 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-portal-Documents.Delete">Delete()</link> D-Bus method on @proxy.
42838 * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from.
42839 * You can then call gxdp_documents_call_delete_finish() to get the result of the operation.
42841 * See gxdp_documents_call_delete_sync() for the synchronous, blocking version of this method.
42846 * gxdp_documents_call_delete_finish:
42847 * @proxy: A #GXdpDocumentsProxy.
42848 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to gxdp_documents_call_delete().
42849 * @error: Return location for error or %NULL.
42851 * Finishes an operation started with gxdp_documents_call_delete().
42853 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
42858 * gxdp_documents_call_delete_sync:
42859 * @proxy: A #GXdpDocumentsProxy.
42860 * @arg_doc_id: Argument to pass with the method invocation.
42861 * @cancellable: (allow-none): A #GCancellable or %NULL.
42862 * @error: Return location for error or %NULL.
42864 * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-portal-Documents.Delete">Delete()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
42866 * See gxdp_documents_call_delete() for the asynchronous version of this method.
42868 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
42873 * gxdp_documents_call_get_mount_point:
42874 * @proxy: A #GXdpDocumentsProxy.
42875 * @cancellable: (allow-none): A #GCancellable or %NULL.
42876 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
42877 * @user_data: User data to pass to @callback.
42879 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-portal-Documents.GetMountPoint">GetMountPoint()</link> D-Bus method on @proxy.
42880 * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from.
42881 * You can then call gxdp_documents_call_get_mount_point_finish() to get the result of the operation.
42883 * See gxdp_documents_call_get_mount_point_sync() for the synchronous, blocking version of this method.
42888 * gxdp_documents_call_get_mount_point_finish:
42889 * @proxy: A #GXdpDocumentsProxy.
42890 * @out_path: (out): Return location for return parameter or %NULL to ignore.
42891 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to gxdp_documents_call_get_mount_point().
42892 * @error: Return location for error or %NULL.
42894 * Finishes an operation started with gxdp_documents_call_get_mount_point().
42896 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
42901 * gxdp_documents_call_get_mount_point_sync:
42902 * @proxy: A #GXdpDocumentsProxy.
42903 * @out_path: (out): Return location for return parameter or %NULL to ignore.
42904 * @cancellable: (allow-none): A #GCancellable or %NULL.
42905 * @error: Return location for error or %NULL.
42907 * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-portal-Documents.GetMountPoint">GetMountPoint()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
42909 * See gxdp_documents_call_get_mount_point() for the asynchronous version of this method.
42911 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
42916 * gxdp_documents_call_grant_permissions:
42917 * @proxy: A #GXdpDocumentsProxy.
42918 * @arg_doc_id: Argument to pass with the method invocation.
42919 * @arg_app_id: Argument to pass with the method invocation.
42920 * @arg_permissions: Argument to pass with the method invocation.
42921 * @cancellable: (allow-none): A #GCancellable or %NULL.
42922 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
42923 * @user_data: User data to pass to @callback.
42925 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-portal-Documents.GrantPermissions">GrantPermissions()</link> D-Bus method on @proxy.
42926 * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from.
42927 * You can then call gxdp_documents_call_grant_permissions_finish() to get the result of the operation.
42929 * See gxdp_documents_call_grant_permissions_sync() for the synchronous, blocking version of this method.
42934 * gxdp_documents_call_grant_permissions_finish:
42935 * @proxy: A #GXdpDocumentsProxy.
42936 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to gxdp_documents_call_grant_permissions().
42937 * @error: Return location for error or %NULL.
42939 * Finishes an operation started with gxdp_documents_call_grant_permissions().
42941 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
42946 * gxdp_documents_call_grant_permissions_sync:
42947 * @proxy: A #GXdpDocumentsProxy.
42948 * @arg_doc_id: Argument to pass with the method invocation.
42949 * @arg_app_id: Argument to pass with the method invocation.
42950 * @arg_permissions: Argument to pass with the method invocation.
42951 * @cancellable: (allow-none): A #GCancellable or %NULL.
42952 * @error: Return location for error or %NULL.
42954 * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-portal-Documents.GrantPermissions">GrantPermissions()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
42956 * See gxdp_documents_call_grant_permissions() for the asynchronous version of this method.
42958 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
42963 * gxdp_documents_call_info:
42964 * @proxy: A #GXdpDocumentsProxy.
42965 * @arg_doc_id: Argument to pass with the method invocation.
42966 * @cancellable: (allow-none): A #GCancellable or %NULL.
42967 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
42968 * @user_data: User data to pass to @callback.
42970 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-portal-Documents.Info">Info()</link> D-Bus method on @proxy.
42971 * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from.
42972 * You can then call gxdp_documents_call_info_finish() to get the result of the operation.
42974 * See gxdp_documents_call_info_sync() for the synchronous, blocking version of this method.
42979 * gxdp_documents_call_info_finish:
42980 * @proxy: A #GXdpDocumentsProxy.
42981 * @out_path: (out): Return location for return parameter or %NULL to ignore.
42982 * @out_apps: (out): Return location for return parameter or %NULL to ignore.
42983 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to gxdp_documents_call_info().
42984 * @error: Return location for error or %NULL.
42986 * Finishes an operation started with gxdp_documents_call_info().
42988 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
42993 * gxdp_documents_call_info_sync:
42994 * @proxy: A #GXdpDocumentsProxy.
42995 * @arg_doc_id: Argument to pass with the method invocation.
42996 * @out_path: (out): Return location for return parameter or %NULL to ignore.
42997 * @out_apps: (out): Return location for return parameter or %NULL to ignore.
42998 * @cancellable: (allow-none): A #GCancellable or %NULL.
42999 * @error: Return location for error or %NULL.
43001 * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-portal-Documents.Info">Info()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
43003 * See gxdp_documents_call_info() for the asynchronous version of this method.
43005 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
43010 * gxdp_documents_call_list:
43011 * @proxy: A #GXdpDocumentsProxy.
43012 * @arg_app_id: Argument to pass with the method invocation.
43013 * @cancellable: (allow-none): A #GCancellable or %NULL.
43014 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
43015 * @user_data: User data to pass to @callback.
43017 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-portal-Documents.List">List()</link> D-Bus method on @proxy.
43018 * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from.
43019 * You can then call gxdp_documents_call_list_finish() to get the result of the operation.
43021 * See gxdp_documents_call_list_sync() for the synchronous, blocking version of this method.
43026 * gxdp_documents_call_list_finish:
43027 * @proxy: A #GXdpDocumentsProxy.
43028 * @out_docs: (out): Return location for return parameter or %NULL to ignore.
43029 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to gxdp_documents_call_list().
43030 * @error: Return location for error or %NULL.
43032 * Finishes an operation started with gxdp_documents_call_list().
43034 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
43039 * gxdp_documents_call_list_sync:
43040 * @proxy: A #GXdpDocumentsProxy.
43041 * @arg_app_id: Argument to pass with the method invocation.
43042 * @out_docs: (out): Return location for return parameter or %NULL to ignore.
43043 * @cancellable: (allow-none): A #GCancellable or %NULL.
43044 * @error: Return location for error or %NULL.
43046 * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-portal-Documents.List">List()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
43048 * See gxdp_documents_call_list() for the asynchronous version of this method.
43050 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
43055 * gxdp_documents_call_lookup:
43056 * @proxy: A #GXdpDocumentsProxy.
43057 * @arg_filename: Argument to pass with the method invocation.
43058 * @cancellable: (allow-none): A #GCancellable or %NULL.
43059 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
43060 * @user_data: User data to pass to @callback.
43062 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-portal-Documents.Lookup">Lookup()</link> D-Bus method on @proxy.
43063 * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from.
43064 * You can then call gxdp_documents_call_lookup_finish() to get the result of the operation.
43066 * See gxdp_documents_call_lookup_sync() for the synchronous, blocking version of this method.
43071 * gxdp_documents_call_lookup_finish:
43072 * @proxy: A #GXdpDocumentsProxy.
43073 * @out_doc_id: (out): Return location for return parameter or %NULL to ignore.
43074 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to gxdp_documents_call_lookup().
43075 * @error: Return location for error or %NULL.
43077 * Finishes an operation started with gxdp_documents_call_lookup().
43079 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
43084 * gxdp_documents_call_lookup_sync:
43085 * @proxy: A #GXdpDocumentsProxy.
43086 * @arg_filename: Argument to pass with the method invocation.
43087 * @out_doc_id: (out): Return location for return parameter or %NULL to ignore.
43088 * @cancellable: (allow-none): A #GCancellable or %NULL.
43089 * @error: Return location for error or %NULL.
43091 * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-portal-Documents.Lookup">Lookup()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
43093 * See gxdp_documents_call_lookup() for the asynchronous version of this method.
43095 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
43100 * gxdp_documents_call_revoke_permissions:
43101 * @proxy: A #GXdpDocumentsProxy.
43102 * @arg_doc_id: Argument to pass with the method invocation.
43103 * @arg_app_id: Argument to pass with the method invocation.
43104 * @arg_permissions: Argument to pass with the method invocation.
43105 * @cancellable: (allow-none): A #GCancellable or %NULL.
43106 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
43107 * @user_data: User data to pass to @callback.
43109 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-portal-Documents.RevokePermissions">RevokePermissions()</link> D-Bus method on @proxy.
43110 * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from.
43111 * You can then call gxdp_documents_call_revoke_permissions_finish() to get the result of the operation.
43113 * See gxdp_documents_call_revoke_permissions_sync() for the synchronous, blocking version of this method.
43118 * gxdp_documents_call_revoke_permissions_finish:
43119 * @proxy: A #GXdpDocumentsProxy.
43120 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to gxdp_documents_call_revoke_permissions().
43121 * @error: Return location for error or %NULL.
43123 * Finishes an operation started with gxdp_documents_call_revoke_permissions().
43125 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
43130 * gxdp_documents_call_revoke_permissions_sync:
43131 * @proxy: A #GXdpDocumentsProxy.
43132 * @arg_doc_id: Argument to pass with the method invocation.
43133 * @arg_app_id: Argument to pass with the method invocation.
43134 * @arg_permissions: Argument to pass with the method invocation.
43135 * @cancellable: (allow-none): A #GCancellable or %NULL.
43136 * @error: Return location for error or %NULL.
43138 * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-portal-Documents.RevokePermissions">RevokePermissions()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
43140 * See gxdp_documents_call_revoke_permissions() for the asynchronous version of this method.
43142 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
43147 * gxdp_documents_complete_add:
43148 * @object: A #GXdpDocuments.
43149 * @invocation: (transfer full): A #GDBusMethodInvocation.
43150 * @fd_list: (allow-none): A #GUnixFDList or %NULL.
43151 * @doc_id: Parameter to return.
43153 * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-portal-Documents.Add">Add()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
43155 * This method will free @invocation, you cannot use it afterwards.
43160 * gxdp_documents_complete_add_named:
43161 * @object: A #GXdpDocuments.
43162 * @invocation: (transfer full): A #GDBusMethodInvocation.
43163 * @fd_list: (allow-none): A #GUnixFDList or %NULL.
43164 * @doc_id: Parameter to return.
43166 * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-portal-Documents.AddNamed">AddNamed()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
43168 * This method will free @invocation, you cannot use it afterwards.
43173 * gxdp_documents_complete_delete:
43174 * @object: A #GXdpDocuments.
43175 * @invocation: (transfer full): A #GDBusMethodInvocation.
43177 * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-portal-Documents.Delete">Delete()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
43179 * This method will free @invocation, you cannot use it afterwards.
43184 * gxdp_documents_complete_get_mount_point:
43185 * @object: A #GXdpDocuments.
43186 * @invocation: (transfer full): A #GDBusMethodInvocation.
43187 * @path: Parameter to return.
43189 * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-portal-Documents.GetMountPoint">GetMountPoint()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
43191 * This method will free @invocation, you cannot use it afterwards.
43196 * gxdp_documents_complete_grant_permissions:
43197 * @object: A #GXdpDocuments.
43198 * @invocation: (transfer full): A #GDBusMethodInvocation.
43200 * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-portal-Documents.GrantPermissions">GrantPermissions()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
43202 * This method will free @invocation, you cannot use it afterwards.
43207 * gxdp_documents_complete_info:
43208 * @object: A #GXdpDocuments.
43209 * @invocation: (transfer full): A #GDBusMethodInvocation.
43210 * @path: Parameter to return.
43211 * @apps: Parameter to return.
43213 * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-portal-Documents.Info">Info()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
43215 * This method will free @invocation, you cannot use it afterwards.
43220 * gxdp_documents_complete_list:
43221 * @object: A #GXdpDocuments.
43222 * @invocation: (transfer full): A #GDBusMethodInvocation.
43223 * @docs: Parameter to return.
43225 * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-portal-Documents.List">List()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
43227 * This method will free @invocation, you cannot use it afterwards.
43232 * gxdp_documents_complete_lookup:
43233 * @object: A #GXdpDocuments.
43234 * @invocation: (transfer full): A #GDBusMethodInvocation.
43235 * @doc_id: Parameter to return.
43237 * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-portal-Documents.Lookup">Lookup()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
43239 * This method will free @invocation, you cannot use it afterwards.
43244 * gxdp_documents_complete_revoke_permissions:
43245 * @object: A #GXdpDocuments.
43246 * @invocation: (transfer full): A #GDBusMethodInvocation.
43248 * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-portal-Documents.RevokePermissions">RevokePermissions()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
43250 * This method will free @invocation, you cannot use it afterwards.
43255 * gxdp_documents_interface_info:
43257 * Gets a machine-readable description of the <link linkend="gdbus-interface-org-freedesktop-portal-Documents.top_of_page">org.freedesktop.portal.Documents</link> D-Bus interface.
43259 * Returns: (transfer none): A #GDBusInterfaceInfo. Do not free.
43264 * gxdp_documents_override_properties:
43265 * @klass: The class structure for a #GObject<!-- -->-derived class.
43266 * @property_id_begin: The property id to assign to the first overridden property.
43268 * Overrides all #GObject properties in the #GXdpDocuments interface for a concrete class.
43269 * The properties are overridden in the order they are defined.
43271 * Returns: The last property id.
43276 * gxdp_documents_proxy_new:
43277 * @connection: A #GDBusConnection.
43278 * @flags: Flags from the #GDBusProxyFlags enumeration.
43279 * @name: (allow-none): A bus name (well-known or unique) or %NULL if @connection is not a message bus connection.
43280 * @object_path: An object path.
43281 * @cancellable: (allow-none): A #GCancellable or %NULL.
43282 * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
43283 * @user_data: User data to pass to @callback.
43285 * Asynchronously creates a proxy for the D-Bus interface <link linkend="gdbus-interface-org-freedesktop-portal-Documents.top_of_page">org.freedesktop.portal.Documents</link>. See g_dbus_proxy_new() for more details.
43287 * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from.
43288 * You can then call gxdp_documents_proxy_new_finish() to get the result of the operation.
43290 * See gxdp_documents_proxy_new_sync() for the synchronous, blocking version of this constructor.
43295 * gxdp_documents_proxy_new_finish:
43296 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to gxdp_documents_proxy_new().
43297 * @error: Return location for error or %NULL
43299 * Finishes an operation started with gxdp_documents_proxy_new().
43301 * Returns: (transfer full) (type GXdpDocumentsProxy): The constructed proxy object or %NULL if @error is set.
43306 * gxdp_documents_proxy_new_for_bus:
43307 * @bus_type: A #GBusType.
43308 * @flags: Flags from the #GDBusProxyFlags enumeration.
43309 * @name: A bus name (well-known or unique).
43310 * @object_path: An object path.
43311 * @cancellable: (allow-none): A #GCancellable or %NULL.
43312 * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
43313 * @user_data: User data to pass to @callback.
43315 * Like gxdp_documents_proxy_new() but takes a #GBusType instead of a #GDBusConnection.
43317 * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from.
43318 * You can then call gxdp_documents_proxy_new_for_bus_finish() to get the result of the operation.
43320 * See gxdp_documents_proxy_new_for_bus_sync() for the synchronous, blocking version of this constructor.
43325 * gxdp_documents_proxy_new_for_bus_finish:
43326 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to gxdp_documents_proxy_new_for_bus().
43327 * @error: Return location for error or %NULL
43329 * Finishes an operation started with gxdp_documents_proxy_new_for_bus().
43331 * Returns: (transfer full) (type GXdpDocumentsProxy): The constructed proxy object or %NULL if @error is set.
43336 * gxdp_documents_proxy_new_for_bus_sync:
43337 * @bus_type: A #GBusType.
43338 * @flags: Flags from the #GDBusProxyFlags enumeration.
43339 * @name: A bus name (well-known or unique).
43340 * @object_path: An object path.
43341 * @cancellable: (allow-none): A #GCancellable or %NULL.
43342 * @error: Return location for error or %NULL
43344 * Like gxdp_documents_proxy_new_sync() but takes a #GBusType instead of a #GDBusConnection.
43346 * The calling thread is blocked until a reply is received.
43348 * See gxdp_documents_proxy_new_for_bus() for the asynchronous version of this constructor.
43350 * Returns: (transfer full) (type GXdpDocumentsProxy): The constructed proxy object or %NULL if @error is set.
43355 * gxdp_documents_proxy_new_sync:
43356 * @connection: A #GDBusConnection.
43357 * @flags: Flags from the #GDBusProxyFlags enumeration.
43358 * @name: (allow-none): A bus name (well-known or unique) or %NULL if @connection is not a message bus connection.
43359 * @object_path: An object path.
43360 * @cancellable: (allow-none): A #GCancellable or %NULL.
43361 * @error: Return location for error or %NULL
43363 * Synchronously creates a proxy for the D-Bus interface <link linkend="gdbus-interface-org-freedesktop-portal-Documents.top_of_page">org.freedesktop.portal.Documents</link>. See g_dbus_proxy_new_sync() for more details.
43365 * The calling thread is blocked until a reply is received.
43367 * See gxdp_documents_proxy_new() for the asynchronous version of this constructor.
43369 * Returns: (transfer full) (type GXdpDocumentsProxy): The constructed proxy object or %NULL if @error is set.
43374 * gxdp_documents_skeleton_new:
43376 * Creates a skeleton object for the D-Bus interface <link linkend="gdbus-interface-org-freedesktop-portal-Documents.top_of_page">org.freedesktop.portal.Documents</link>.
43378 * Returns: (transfer full) (type GXdpDocumentsSkeleton): The skeleton object.
43383 * gxdp_network_monitor_emit_changed:
43384 * @object: A #GXdpNetworkMonitor.
43385 * @arg_available: Argument to pass with the signal.
43387 * Emits the <link linkend="gdbus-signal-org-freedesktop-portal-NetworkMonitor.changed">"changed"</link> D-Bus signal.
43392 * gxdp_network_monitor_get_available: (skip)
43393 * @object: A #GXdpNetworkMonitor.
43395 * Gets the value of the <link linkend="gdbus-property-org-freedesktop-portal-NetworkMonitor.available">"available"</link> D-Bus property.
43397 * Since this D-Bus property is readable, it is meaningful to use this function on both the client- and service-side.
43399 * Returns: The property value.
43404 * gxdp_network_monitor_get_connectivity: (skip)
43405 * @object: A #GXdpNetworkMonitor.
43407 * Gets the value of the <link linkend="gdbus-property-org-freedesktop-portal-NetworkMonitor.connectivity">"connectivity"</link> D-Bus property.
43409 * Since this D-Bus property is readable, it is meaningful to use this function on both the client- and service-side.
43411 * Returns: The property value.
43416 * gxdp_network_monitor_get_metered: (skip)
43417 * @object: A #GXdpNetworkMonitor.
43419 * Gets the value of the <link linkend="gdbus-property-org-freedesktop-portal-NetworkMonitor.metered">"metered"</link> D-Bus property.
43421 * Since this D-Bus property is readable, it is meaningful to use this function on both the client- and service-side.
43423 * Returns: The property value.
43428 * gxdp_network_monitor_interface_info:
43430 * Gets a machine-readable description of the <link linkend="gdbus-interface-org-freedesktop-portal-NetworkMonitor.top_of_page">org.freedesktop.portal.NetworkMonitor</link> D-Bus interface.
43432 * Returns: (transfer none): A #GDBusInterfaceInfo. Do not free.
43437 * gxdp_network_monitor_override_properties:
43438 * @klass: The class structure for a #GObject<!-- -->-derived class.
43439 * @property_id_begin: The property id to assign to the first overridden property.
43441 * Overrides all #GObject properties in the #GXdpNetworkMonitor interface for a concrete class.
43442 * The properties are overridden in the order they are defined.
43444 * Returns: The last property id.
43449 * gxdp_network_monitor_proxy_new:
43450 * @connection: A #GDBusConnection.
43451 * @flags: Flags from the #GDBusProxyFlags enumeration.
43452 * @name: (allow-none): A bus name (well-known or unique) or %NULL if @connection is not a message bus connection.
43453 * @object_path: An object path.
43454 * @cancellable: (allow-none): A #GCancellable or %NULL.
43455 * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
43456 * @user_data: User data to pass to @callback.
43458 * Asynchronously creates a proxy for the D-Bus interface <link linkend="gdbus-interface-org-freedesktop-portal-NetworkMonitor.top_of_page">org.freedesktop.portal.NetworkMonitor</link>. See g_dbus_proxy_new() for more details.
43460 * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from.
43461 * You can then call gxdp_network_monitor_proxy_new_finish() to get the result of the operation.
43463 * See gxdp_network_monitor_proxy_new_sync() for the synchronous, blocking version of this constructor.
43468 * gxdp_network_monitor_proxy_new_finish:
43469 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to gxdp_network_monitor_proxy_new().
43470 * @error: Return location for error or %NULL
43472 * Finishes an operation started with gxdp_network_monitor_proxy_new().
43474 * Returns: (transfer full) (type GXdpNetworkMonitorProxy): The constructed proxy object or %NULL if @error is set.
43479 * gxdp_network_monitor_proxy_new_for_bus:
43480 * @bus_type: A #GBusType.
43481 * @flags: Flags from the #GDBusProxyFlags enumeration.
43482 * @name: A bus name (well-known or unique).
43483 * @object_path: An object path.
43484 * @cancellable: (allow-none): A #GCancellable or %NULL.
43485 * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
43486 * @user_data: User data to pass to @callback.
43488 * Like gxdp_network_monitor_proxy_new() but takes a #GBusType instead of a #GDBusConnection.
43490 * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from.
43491 * You can then call gxdp_network_monitor_proxy_new_for_bus_finish() to get the result of the operation.
43493 * See gxdp_network_monitor_proxy_new_for_bus_sync() for the synchronous, blocking version of this constructor.
43498 * gxdp_network_monitor_proxy_new_for_bus_finish:
43499 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to gxdp_network_monitor_proxy_new_for_bus().
43500 * @error: Return location for error or %NULL
43502 * Finishes an operation started with gxdp_network_monitor_proxy_new_for_bus().
43504 * Returns: (transfer full) (type GXdpNetworkMonitorProxy): The constructed proxy object or %NULL if @error is set.
43509 * gxdp_network_monitor_proxy_new_for_bus_sync:
43510 * @bus_type: A #GBusType.
43511 * @flags: Flags from the #GDBusProxyFlags enumeration.
43512 * @name: A bus name (well-known or unique).
43513 * @object_path: An object path.
43514 * @cancellable: (allow-none): A #GCancellable or %NULL.
43515 * @error: Return location for error or %NULL
43517 * Like gxdp_network_monitor_proxy_new_sync() but takes a #GBusType instead of a #GDBusConnection.
43519 * The calling thread is blocked until a reply is received.
43521 * See gxdp_network_monitor_proxy_new_for_bus() for the asynchronous version of this constructor.
43523 * Returns: (transfer full) (type GXdpNetworkMonitorProxy): The constructed proxy object or %NULL if @error is set.
43528 * gxdp_network_monitor_proxy_new_sync:
43529 * @connection: A #GDBusConnection.
43530 * @flags: Flags from the #GDBusProxyFlags enumeration.
43531 * @name: (allow-none): A bus name (well-known or unique) or %NULL if @connection is not a message bus connection.
43532 * @object_path: An object path.
43533 * @cancellable: (allow-none): A #GCancellable or %NULL.
43534 * @error: Return location for error or %NULL
43536 * Synchronously creates a proxy for the D-Bus interface <link linkend="gdbus-interface-org-freedesktop-portal-NetworkMonitor.top_of_page">org.freedesktop.portal.NetworkMonitor</link>. See g_dbus_proxy_new_sync() for more details.
43538 * The calling thread is blocked until a reply is received.
43540 * See gxdp_network_monitor_proxy_new() for the asynchronous version of this constructor.
43542 * Returns: (transfer full) (type GXdpNetworkMonitorProxy): The constructed proxy object or %NULL if @error is set.
43547 * gxdp_network_monitor_set_available: (skip)
43548 * @object: A #GXdpNetworkMonitor.
43549 * @value: The value to set.
43551 * Sets the <link linkend="gdbus-property-org-freedesktop-portal-NetworkMonitor.available">"available"</link> D-Bus property to @value.
43553 * Since this D-Bus property is not writable, it is only meaningful to use this function on the service-side.
43558 * gxdp_network_monitor_set_connectivity: (skip)
43559 * @object: A #GXdpNetworkMonitor.
43560 * @value: The value to set.
43562 * Sets the <link linkend="gdbus-property-org-freedesktop-portal-NetworkMonitor.connectivity">"connectivity"</link> D-Bus property to @value.
43564 * Since this D-Bus property is not writable, it is only meaningful to use this function on the service-side.
43569 * gxdp_network_monitor_set_metered: (skip)
43570 * @object: A #GXdpNetworkMonitor.
43571 * @value: The value to set.
43573 * Sets the <link linkend="gdbus-property-org-freedesktop-portal-NetworkMonitor.metered">"metered"</link> D-Bus property to @value.
43575 * Since this D-Bus property is not writable, it is only meaningful to use this function on the service-side.
43580 * gxdp_network_monitor_skeleton_new:
43582 * Creates a skeleton object for the D-Bus interface <link linkend="gdbus-interface-org-freedesktop-portal-NetworkMonitor.top_of_page">org.freedesktop.portal.NetworkMonitor</link>.
43584 * Returns: (transfer full) (type GXdpNetworkMonitorSkeleton): The skeleton object.
43589 * gxdp_proxy_resolver_call_lookup:
43590 * @proxy: A #GXdpProxyResolverProxy.
43591 * @arg_uri: Argument to pass with the method invocation.
43592 * @cancellable: (allow-none): A #GCancellable or %NULL.
43593 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
43594 * @user_data: User data to pass to @callback.
43596 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-portal-ProxyResolver.Lookup">Lookup()</link> D-Bus method on @proxy.
43597 * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from.
43598 * You can then call gxdp_proxy_resolver_call_lookup_finish() to get the result of the operation.
43600 * See gxdp_proxy_resolver_call_lookup_sync() for the synchronous, blocking version of this method.
43605 * gxdp_proxy_resolver_call_lookup_finish:
43606 * @proxy: A #GXdpProxyResolverProxy.
43607 * @out_proxies: (out): Return location for return parameter or %NULL to ignore.
43608 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to gxdp_proxy_resolver_call_lookup().
43609 * @error: Return location for error or %NULL.
43611 * Finishes an operation started with gxdp_proxy_resolver_call_lookup().
43613 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
43618 * gxdp_proxy_resolver_call_lookup_sync:
43619 * @proxy: A #GXdpProxyResolverProxy.
43620 * @arg_uri: Argument to pass with the method invocation.
43621 * @out_proxies: (out): Return location for return parameter or %NULL to ignore.
43622 * @cancellable: (allow-none): A #GCancellable or %NULL.
43623 * @error: Return location for error or %NULL.
43625 * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-portal-ProxyResolver.Lookup">Lookup()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
43627 * See gxdp_proxy_resolver_call_lookup() for the asynchronous version of this method.
43629 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
43634 * gxdp_proxy_resolver_complete_lookup:
43635 * @object: A #GXdpProxyResolver.
43636 * @invocation: (transfer full): A #GDBusMethodInvocation.
43637 * @proxies: Parameter to return.
43639 * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-portal-ProxyResolver.Lookup">Lookup()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
43641 * This method will free @invocation, you cannot use it afterwards.
43646 * gxdp_proxy_resolver_interface_info:
43648 * Gets a machine-readable description of the <link linkend="gdbus-interface-org-freedesktop-portal-ProxyResolver.top_of_page">org.freedesktop.portal.ProxyResolver</link> D-Bus interface.
43650 * Returns: (transfer none): A #GDBusInterfaceInfo. Do not free.
43655 * gxdp_proxy_resolver_override_properties:
43656 * @klass: The class structure for a #GObject<!-- -->-derived class.
43657 * @property_id_begin: The property id to assign to the first overridden property.
43659 * Overrides all #GObject properties in the #GXdpProxyResolver interface for a concrete class.
43660 * The properties are overridden in the order they are defined.
43662 * Returns: The last property id.
43667 * gxdp_proxy_resolver_proxy_new:
43668 * @connection: A #GDBusConnection.
43669 * @flags: Flags from the #GDBusProxyFlags enumeration.
43670 * @name: (allow-none): A bus name (well-known or unique) or %NULL if @connection is not a message bus connection.
43671 * @object_path: An object path.
43672 * @cancellable: (allow-none): A #GCancellable or %NULL.
43673 * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
43674 * @user_data: User data to pass to @callback.
43676 * Asynchronously creates a proxy for the D-Bus interface <link linkend="gdbus-interface-org-freedesktop-portal-ProxyResolver.top_of_page">org.freedesktop.portal.ProxyResolver</link>. See g_dbus_proxy_new() for more details.
43678 * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from.
43679 * You can then call gxdp_proxy_resolver_proxy_new_finish() to get the result of the operation.
43681 * See gxdp_proxy_resolver_proxy_new_sync() for the synchronous, blocking version of this constructor.
43686 * gxdp_proxy_resolver_proxy_new_finish:
43687 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to gxdp_proxy_resolver_proxy_new().
43688 * @error: Return location for error or %NULL
43690 * Finishes an operation started with gxdp_proxy_resolver_proxy_new().
43692 * Returns: (transfer full) (type GXdpProxyResolverProxy): The constructed proxy object or %NULL if @error is set.
43697 * gxdp_proxy_resolver_proxy_new_for_bus:
43698 * @bus_type: A #GBusType.
43699 * @flags: Flags from the #GDBusProxyFlags enumeration.
43700 * @name: A bus name (well-known or unique).
43701 * @object_path: An object path.
43702 * @cancellable: (allow-none): A #GCancellable or %NULL.
43703 * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
43704 * @user_data: User data to pass to @callback.
43706 * Like gxdp_proxy_resolver_proxy_new() but takes a #GBusType instead of a #GDBusConnection.
43708 * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from.
43709 * You can then call gxdp_proxy_resolver_proxy_new_for_bus_finish() to get the result of the operation.
43711 * See gxdp_proxy_resolver_proxy_new_for_bus_sync() for the synchronous, blocking version of this constructor.
43716 * gxdp_proxy_resolver_proxy_new_for_bus_finish:
43717 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to gxdp_proxy_resolver_proxy_new_for_bus().
43718 * @error: Return location for error or %NULL
43720 * Finishes an operation started with gxdp_proxy_resolver_proxy_new_for_bus().
43722 * Returns: (transfer full) (type GXdpProxyResolverProxy): The constructed proxy object or %NULL if @error is set.
43727 * gxdp_proxy_resolver_proxy_new_for_bus_sync:
43728 * @bus_type: A #GBusType.
43729 * @flags: Flags from the #GDBusProxyFlags enumeration.
43730 * @name: A bus name (well-known or unique).
43731 * @object_path: An object path.
43732 * @cancellable: (allow-none): A #GCancellable or %NULL.
43733 * @error: Return location for error or %NULL
43735 * Like gxdp_proxy_resolver_proxy_new_sync() but takes a #GBusType instead of a #GDBusConnection.
43737 * The calling thread is blocked until a reply is received.
43739 * See gxdp_proxy_resolver_proxy_new_for_bus() for the asynchronous version of this constructor.
43741 * Returns: (transfer full) (type GXdpProxyResolverProxy): The constructed proxy object or %NULL if @error is set.
43746 * gxdp_proxy_resolver_proxy_new_sync:
43747 * @connection: A #GDBusConnection.
43748 * @flags: Flags from the #GDBusProxyFlags enumeration.
43749 * @name: (allow-none): A bus name (well-known or unique) or %NULL if @connection is not a message bus connection.
43750 * @object_path: An object path.
43751 * @cancellable: (allow-none): A #GCancellable or %NULL.
43752 * @error: Return location for error or %NULL
43754 * Synchronously creates a proxy for the D-Bus interface <link linkend="gdbus-interface-org-freedesktop-portal-ProxyResolver.top_of_page">org.freedesktop.portal.ProxyResolver</link>. See g_dbus_proxy_new_sync() for more details.
43756 * The calling thread is blocked until a reply is received.
43758 * See gxdp_proxy_resolver_proxy_new() for the asynchronous version of this constructor.
43760 * Returns: (transfer full) (type GXdpProxyResolverProxy): The constructed proxy object or %NULL if @error is set.
43765 * gxdp_proxy_resolver_skeleton_new:
43767 * Creates a skeleton object for the D-Bus interface <link linkend="gdbus-interface-org-freedesktop-portal-ProxyResolver.top_of_page">org.freedesktop.portal.ProxyResolver</link>.
43769 * Returns: (transfer full) (type GXdpProxyResolverSkeleton): The skeleton object.
43774 /************************************************************/
43775 /* THIS FILE IS GENERATED DO NOT EDIT */
43776 /************************************************************/