1 /************************************************************/
2 /* THIS FILE IS GENERATED DO NOT EDIT */
3 /************************************************************/
8 * If @action is currently enabled.
10 * If the action is disabled then calls to g_action_activate() and
11 * g_action_change_state() have no effect.
20 * The name of the action. This is mostly meaningful for identifying
21 * the action once it has been added to a #GActionGroup. It is immutable.
28 * GAction:parameter-type:
30 * The type of the parameter that must be given when activating the
31 * action. This is immutable, and may be %NULL if no parameter is needed when
32 * activating the action.
41 * The state of the action, or %NULL if the action is stateless.
50 * The #GVariantType of the state that the action has, or %NULL if the
51 * action is stateless. This is immutable.
59 * @name: the name of the action
60 * @activate: the callback to connect to the "activate" signal of the
61 * action. Since GLib 2.40, this can be %NULL for stateful
62 * actions, in which case the default handler is used. For
63 * boolean-stated actions with no parameter, this is a
64 * toggle. For other state types (and parameter type equal
65 * to the state type) this will be a function that
66 * just calls @change_state (which you should provide).
67 * @parameter_type: the type of the parameter that must be passed to the
68 * activate function for this action, given as a single
69 * GVariant type string (or %NULL for no parameter)
70 * @state: the initial state for this action, given in
71 * [GVariant text format][gvariant-text]. The state is parsed
72 * with no extra type information, so type tags must be added to
73 * the string if they are necessary. Stateless actions should
75 * @change_state: the callback to connect to the "change-state" signal
76 * of the action. All stateful actions should provide a
77 * handler here; stateless actions should not.
79 * This struct defines a single action. It is for use with
80 * g_action_map_add_action_entries().
82 * The order of the items in the structure are intended to reflect
83 * frequency of use. It is permissible to use an incomplete initialiser
84 * in order to leave some of the later values as %NULL. All values
85 * after @name are optional. Additional optional fields may be added in
88 * See g_action_map_add_action_entries() for an example.
93 * GActionGroup::action-added:
94 * @action_group: the #GActionGroup that changed
95 * @action_name: the name of the action in @action_group
97 * Signals that a new action was just added to the group.
98 * This signal is emitted after the action has been added
106 * GActionGroup::action-enabled-changed:
107 * @action_group: the #GActionGroup that changed
108 * @action_name: the name of the action in @action_group
109 * @enabled: whether the action is enabled or not
111 * Signals that the enabled status of the named action has changed.
118 * GActionGroup::action-removed:
119 * @action_group: the #GActionGroup that changed
120 * @action_name: the name of the action in @action_group
122 * Signals that an action is just about to be removed from the group.
123 * This signal is emitted before the action is removed, so the action
124 * is still visible and can be queried from the signal handler.
131 * GActionGroup::action-state-changed:
132 * @action_group: the #GActionGroup that changed
133 * @action_name: the name of the action in @action_group
134 * @value: the new value of the state
136 * Signals that the state of the named action has changed.
143 * GActionGroupInterface:
144 * @has_action: the virtual function pointer for g_action_group_has_action()
145 * @list_actions: the virtual function pointer for g_action_group_list_actions()
146 * @get_action_parameter_type: the virtual function pointer for g_action_group_get_action_parameter_type()
147 * @get_action_state_type: the virtual function pointer for g_action_group_get_action_state_type()
148 * @get_action_state_hint: the virtual function pointer for g_action_group_get_action_state_hint()
149 * @get_action_enabled: the virtual function pointer for g_action_group_get_action_enabled()
150 * @get_action_state: the virtual function pointer for g_action_group_get_action_state()
151 * @change_action_state: the virtual function pointer for g_action_group_change_action_state()
152 * @query_action: the virtual function pointer for g_action_group_query_action()
153 * @activate_action: the virtual function pointer for g_action_group_activate_action()
154 * @action_added: the class closure for the #GActionGroup::action-added signal
155 * @action_removed: the class closure for the #GActionGroup::action-removed signal
156 * @action_enabled_changed: the class closure for the #GActionGroup::action-enabled-changed signal
157 * @action_state_changed: the class closure for the #GActionGroup::action-enabled-changed signal
159 * The virtual function table for #GActionGroup.
167 * @get_name: the virtual function pointer for g_action_get_name()
168 * @get_parameter_type: the virtual function pointer for g_action_get_parameter_type()
169 * @get_state_type: the virtual function pointer for g_action_get_state_type()
170 * @get_state_hint: the virtual function pointer for g_action_get_state_hint()
171 * @get_enabled: the virtual function pointer for g_action_get_enabled()
172 * @get_state: the virtual function pointer for g_action_get_state()
173 * @change_state: the virtual function pointer for g_action_change_state()
174 * @activate: the virtual function pointer for g_action_activate(). Note that #GAction does not have an
175 * 'activate' signal but that implementations of it may have one.
177 * The virtual function table for #GAction.
184 * GActionMapInterface:
185 * @lookup_action: the virtual function pointer for g_action_map_lookup_action()
186 * @add_action: the virtual function pointer for g_action_map_add_action()
187 * @remove_action: the virtual function pointer for g_action_map_remove_action()
189 * The virtual function table for #GActionMap.
198 * The only thing you can do with this is to get it via
199 * g_app_info_monitor_get() and connect to the "changed" signal.
206 * GApplication::activate:
207 * @application: the application
209 * The ::activate signal is emitted on the primary instance when an
210 * activation occurs. See g_application_activate().
215 * GApplication::command-line:
216 * @application: the application
217 * @command_line: a #GApplicationCommandLine representing the
220 * The ::command-line signal is emitted on the primary instance when
221 * a commandline is not handled locally. See g_application_run() and
222 * the #GApplicationCommandLine documentation for more information.
224 * Returns: An integer that is set as the exit status for the calling
225 * process. See g_application_command_line_set_exit_status().
230 * GApplication::handle-local-options:
231 * @application: the application
232 * @options: the options dictionary
234 * The ::handle-local-options signal is emitted on the local instance
235 * after the parsing of the commandline options has occurred.
237 * You can add options to be recognised during commandline option
238 * parsing using g_application_add_main_option_entries() and
239 * g_application_add_option_group().
241 * Signal handlers can inspect @options (along with values pointed to
242 * from the @arg_data of an installed #GOptionEntrys) in order to
243 * decide to perform certain actions, including direct local handling
244 * (which may be useful for options like --version).
246 * If the options have been "handled" then a non-negative value should
247 * be returned. In this case, the return value is the exit status: 0
248 * for success and a positive value for failure. -1 means to continue
251 * In the event that the application is marked
252 * %G_APPLICATION_HANDLES_COMMAND_LINE the "normal processing" will
253 * send the @option dictionary to the primary instance where it can be
254 * read with g_application_command_line_get_options(). The signal
255 * handler can modify the dictionary before returning, and the
256 * modified dictionary will be sent.
258 * In the event that %G_APPLICATION_HANDLES_COMMAND_LINE is not set,
259 * "normal processing" will treat the remaining uncollected command
260 * line arguments as filenames or URIs. If there are no arguments,
261 * the application is activated by g_application_activate(). One or
262 * more arguments results in a call to g_application_open().
264 * If you want to handle the local commandline arguments for yourself
265 * by converting them to calls to g_application_open() or
266 * g_action_group_activate_action() then you must be sure to register
267 * the application first. You should probably not call
268 * g_application_activate() for yourself, however: just return -1 and
269 * allow the default handler to do it for you. This will ensure that
270 * the `--gapplication-service` switch works properly (i.e. no activation
273 * Note that this signal is emitted from the default implementation of
274 * local_command_line(). If you override that function and don't
275 * chain up then this signal will never be emitted.
277 * You can override local_command_line() if you need more powerful
278 * capabilities than what is provided here, but this should not
279 * normally be required.
286 * GApplication::open:
287 * @application: the application
288 * @files: (array length=n_files) (element-type GFile): an array of #GFiles
289 * @n_files: the length of @files
290 * @hint: a hint provided by the calling instance
292 * The ::open signal is emitted on the primary instance when there are
293 * files to open. See g_application_open() for more information.
298 * GApplication::shutdown:
299 * @application: the application
301 * The ::shutdown signal is emitted only on the registered primary instance
302 * immediately after the main loop terminates.
307 * GApplication::startup:
308 * @application: the application
310 * The ::startup signal is emitted on the primary instance immediately
311 * after registration. See g_application_register().
317 * @startup: invoked on the primary instance immediately after registration
318 * @shutdown: invoked only on the registered primary instance immediately
319 * after the main loop terminates
320 * @activate: invoked on the primary instance when an activation occurs
321 * @open: invoked on the primary instance when there are files to open
322 * @command_line: invoked on the primary instance when a command-line is
323 * not handled locally
324 * @local_command_line: invoked (locally) when the process has been invoked
325 * via commandline execution (as opposed to, say, D-Bus activation - which
326 * is not currently supported by GApplication). The virtual function has
327 * the chance to inspect (and possibly replace) the list of command line
328 * arguments. See g_application_run() for more information.
329 * @before_emit: invoked on the primary instance before 'activate', 'open',
330 * 'command-line' or any action invocation, gets the 'platform data' from
331 * the calling instance
332 * @after_emit: invoked on the primary instance after 'activate', 'open',
333 * 'command-line' or any action invocation, gets the 'platform data' from
334 * the calling instance
335 * @add_platform_data: invoked (locally) to add 'platform data' to be sent to
336 * the primary instance when activating, opening or invoking actions
337 * @quit_mainloop: Used to be invoked on the primary instance when the use
338 * count of the application drops to zero (and after any inactivity
339 * timeout, if requested). Not used anymore since 2.32
340 * @run_mainloop: Used to be invoked on the primary instance from
341 * g_application_run() if the use-count is non-zero. Since 2.32,
342 * GApplication is iterating the main context directly and is not
343 * using @run_mainloop anymore
344 * @dbus_register: invoked locally during registration, if the application is
345 * using its D-Bus backend. You can use this to export extra objects on the
346 * bus, that need to exist before the application tries to own the bus name.
347 * The function is passed the #GDBusConnection to to session bus, and the
348 * object path that #GApplication will use to export is D-Bus API.
349 * If this function returns %TRUE, registration will proceed; otherwise
350 * registration will abort. Since: 2.34
351 * @dbus_unregister: invoked locally during unregistration, if the application
352 * is using its D-Bus backend. Use this to undo anything done by the
353 * @dbus_register vfunc. Since: 2.34
355 * Virtual function table for #GApplication.
362 * GApplicationCommandLineClass:
364 * The #GApplicationCommandLineClass-struct
365 * contains private data only.
374 * The bytes containing the icon.
379 * GCancellable::cancelled:
380 * @cancellable: a #GCancellable.
382 * Emitted when the operation has been cancelled.
384 * Can be used by implementations of cancellable operations. If the
385 * operation is cancelled from another thread, the signal will be
386 * emitted in the thread that cancelled the operation, not the
387 * thread that is running the operation.
389 * Note that disconnecting from this signal (or any signal) in a
390 * multi-threaded program is prone to race conditions. For instance
391 * it is possible that a signal handler may be invoked even after
392 * a call to g_signal_handler_disconnect() for that handler has
395 * There is also a problem when cancellation happens right before
396 * connecting to the signal. If this happens the signal will
397 * unexpectedly not be emitted, and checking before connecting to
398 * the signal leaves a race condition where this is still happening.
400 * In order to make it safe and easy to connect handlers there
401 * are two helper functions: g_cancellable_connect() and
402 * g_cancellable_disconnect() which protect against problems
405 * An example of how to us this:
406 * |[<!-- language="C" -->
407 * // Make sure we don't do unnecessary work if already cancelled
408 * if (g_cancellable_set_error_if_cancelled (cancellable, error))
411 * // Set up all the data needed to be able to handle cancellation
412 * // of the operation
413 * my_data = my_data_new (...);
417 * id = g_cancellable_connect (cancellable,
418 * G_CALLBACK (cancelled_handler)
421 * // cancellable operation here...
423 * g_cancellable_disconnect (cancellable, id);
425 * // cancelled_handler is never called after this, it is now safe
426 * // to free the data
427 * my_data_free (my_data);
430 * Note that the cancelled signal is emitted in the thread that
431 * the user cancelled from, which may be the main thread. So, the
432 * cancellable signal should not do something that can block.
439 * Conversions between character sets.
446 * The #GCredentials structure contains only private data and
447 * should only be accessed using the provided API.
456 * Class structure for #GCredentials.
463 * GDBusAuthMechanism:credentials:
465 * If authenticating as a server, this property contains the
466 * received credentials, if any.
468 * If authenticating as a client, the property contains the
469 * credentials that were sent, if any.
476 * The #GDBusAuthObserver structure contains only private data and
477 * should only be accessed using the provided API.
484 * GDBusAuthObserver::allow-mechanism:
485 * @observer: The #GDBusAuthObserver emitting the signal.
486 * @mechanism: The name of the mechanism, e.g. `DBUS_COOKIE_SHA1`.
488 * Emitted to check if @mechanism is allowed to be used.
490 * Returns: %TRUE if @mechanism can be used to authenticate the other peer, %FALSE if not.
496 * GDBusAuthObserver::authorize-authenticated-peer:
497 * @observer: The #GDBusAuthObserver emitting the signal.
498 * @stream: A #GIOStream for the #GDBusConnection.
499 * @credentials: (allow-none): Credentials received from the peer or %NULL.
501 * Emitted to check if a peer that is successfully authenticated
504 * Returns: %TRUE if the peer is authorized, %FALSE if not.
510 * GDBusAuthObserverClass:
511 * @authorize_authenticated_peer: Signal class handler for the #GDBusAuthObserver::authorize-authenticated-peer signal.
513 * Class structure for #GDBusAuthObserverClass.
522 * The #GDBusConnection structure contains only private data and
523 * should only be accessed using the provided API.
530 * GDBusConnection::closed:
531 * @connection: the #GDBusConnection emitting the signal
532 * @remote_peer_vanished: %TRUE if @connection is closed because the
533 * remote peer closed its end of the connection
534 * @error: (allow-none): a #GError with more details about the event or %NULL
536 * Emitted when the connection is closed.
538 * The cause of this event can be
540 * - If g_dbus_connection_close() is called. In this case
541 * @remote_peer_vanished is set to %FALSE and @error is %NULL.
543 * - If the remote peer closes the connection. In this case
544 * @remote_peer_vanished is set to %TRUE and @error is set.
546 * - If the remote peer sends invalid or malformed data. In this
547 * case @remote_peer_vanished is set to %FALSE and @error is set.
549 * Upon receiving this signal, you should give up your reference to
550 * @connection. You are guaranteed that this signal is emitted only
558 * GDBusConnection:address:
560 * A D-Bus address specifying potential endpoints that can be used
561 * when establishing the connection.
568 * GDBusConnection:authentication-observer:
570 * A #GDBusAuthObserver object to assist in the authentication process or %NULL.
577 * GDBusConnection:capabilities:
579 * Flags from the #GDBusCapabilityFlags enumeration
580 * representing connection features negotiated with the other peer.
587 * GDBusConnection:closed:
589 * A boolean specifying whether the connection has been closed.
596 * GDBusConnection:exit-on-close:
598 * A boolean specifying whether the process will be terminated (by
599 * calling `raise(SIGTERM)`) if the connection is closed by the
602 * Note that #GDBusConnection objects returned by g_bus_get_finish()
603 * and g_bus_get_sync() will (usually) have this property set to %TRUE.
610 * GDBusConnection:flags:
612 * Flags from the #GDBusConnectionFlags enumeration.
619 * GDBusConnection:guid:
621 * The GUID of the peer performing the role of server when
624 * If you are constructing a #GDBusConnection and pass
625 * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER in the
626 * #GDBusConnection:flags property then you MUST also set this
627 * property to a valid guid.
629 * If you are constructing a #GDBusConnection and pass
630 * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_CLIENT in the
631 * #GDBusConnection:flags property you will be able to read the GUID
632 * of the other peer here after the connection has been successfully
640 * GDBusConnection:locked:
642 * A boolean specifying whether the message is locked.
649 * GDBusConnection:stream:
651 * The underlying #GIOStream used for I/O.
653 * If this is passed on construction and is a #GSocketConnection,
654 * then the corresponding #GSocket will be put into non-blocking mode.
656 * While the #GDBusConnection is active, it will interact with this
657 * stream from a worker thread, so it is not safe to interact with
658 * the stream directly.
665 * GDBusConnection:unique-name:
667 * The unique name as assigned by the message bus or %NULL if the
668 * connection is not open or not a message bus connection.
675 * GDBusConnectionClass:
676 * @closed: Signal class handler for the #GDBusConnection::closed signal.
678 * Class structure for #GDBusConnection.
685 * GDBusInterfaceSkeleton::g-authorize-method:
686 * @interface: The #GDBusInterfaceSkeleton emitting the signal.
687 * @invocation: A #GDBusMethodInvocation.
689 * Emitted when a method is invoked by a remote caller and used to
690 * determine if the method call is authorized.
692 * Note that this signal is emitted in a thread dedicated to
693 * handling the method call so handlers are allowed to perform
694 * blocking IO. This means that it is appropriate to call e.g.
695 * [polkit_authority_check_authorization_sync()](http://hal.freedesktop.org/docs/polkit/PolkitAuthority.html#polkit-authority-check-authorization-sync)
697 * [POLKIT_CHECK_AUTHORIZATION_FLAGS_ALLOW_USER_INTERACTION](http://hal.freedesktop.org/docs/polkit/PolkitAuthority.html#POLKIT-CHECK-AUTHORIZATION-FLAGS-ALLOW-USER-INTERACTION:CAPS)
700 * If %FALSE is returned then no further handlers are run and the
701 * signal handler must take a reference to @invocation and finish
702 * handling the call (e.g. return an error via
703 * g_dbus_method_invocation_return_error()).
705 * Otherwise, if %TRUE is returned, signal emission continues. If no
706 * handlers return %FALSE, then the method is dispatched. If
707 * @interface has an enclosing #GDBusObjectSkeleton, then the
708 * #GDBusObjectSkeleton::authorize-method signal handlers run before
709 * the handlers for this signal.
711 * The default class handler just returns %TRUE.
713 * Please note that the common case is optimized: if no signals
714 * handlers are connected and the default class handler isn't
715 * overridden (for both @interface and the enclosing
716 * #GDBusObjectSkeleton, if any) and #GDBusInterfaceSkeleton:g-flags does
718 * %G_DBUS_INTERFACE_SKELETON_FLAGS_HANDLE_METHOD_INVOCATIONS_IN_THREAD
719 * flags set, no dedicated thread is ever used and the call will be
720 * handled in the same thread as the object that @interface belongs
721 * to was exported in.
723 * Returns: %TRUE if the call is authorized, %FALSE otherwise.
729 * GDBusInterfaceSkeleton:g-flags:
731 * Flags from the #GDBusInterfaceSkeletonFlags enumeration.
740 * The #GDBusMessage structure contains only private data and should
741 * only be accessed using the provided API.
750 * Class structure for #GDBusMessage.
757 * GDBusMethodInvocation:
759 * The #GDBusMethodInvocation structure contains only private data and
760 * should only be accessed using the provided API.
767 * GDBusMethodInvocationClass:
769 * Class structure for #GDBusMethodInvocation.
776 * GDBusObject::interface-added:
777 * @object: The #GDBusObject emitting the signal.
778 * @interface: The #GDBusInterface that was added.
780 * Emitted when @interface is added to @object.
787 * GDBusObject::interface-removed:
788 * @object: The #GDBusObject emitting the signal.
789 * @interface: The #GDBusInterface that was removed.
791 * Emitted when @interface is removed from @object.
798 * GDBusObjectManager::interface-added:
799 * @manager: The #GDBusObjectManager emitting the signal.
800 * @object: The #GDBusObject on which an interface was added.
801 * @interface: The #GDBusInterface that was added.
803 * Emitted when @interface is added to @object.
805 * This signal exists purely as a convenience to avoid having to
806 * connect signals to all objects managed by @manager.
813 * GDBusObjectManager::interface-removed:
814 * @manager: The #GDBusObjectManager emitting the signal.
815 * @object: The #GDBusObject on which an interface was removed.
816 * @interface: The #GDBusInterface that was removed.
818 * Emitted when @interface has been removed from @object.
820 * This signal exists purely as a convenience to avoid having to
821 * connect signals to all objects managed by @manager.
828 * GDBusObjectManager::object-added:
829 * @manager: The #GDBusObjectManager emitting the signal.
830 * @object: The #GDBusObject that was added.
832 * Emitted when @object is added to @manager.
839 * GDBusObjectManager::object-removed:
840 * @manager: The #GDBusObjectManager emitting the signal.
841 * @object: The #GDBusObject that was removed.
843 * Emitted when @object is removed from @manager.
850 * GDBusObjectManagerClient::interface-proxy-properties-changed:
851 * @manager: The #GDBusObjectManagerClient emitting the signal.
852 * @object_proxy: The #GDBusObjectProxy on which an interface has properties that are changing.
853 * @interface_proxy: The #GDBusProxy that has properties that are changing.
854 * @changed_properties: A #GVariant containing the properties that changed.
855 * @invalidated_properties: A %NULL terminated array of properties that was invalidated.
857 * Emitted when one or more D-Bus properties on proxy changes. The
858 * local cache has already been updated when this signal fires. Note
859 * that both @changed_properties and @invalidated_properties are
860 * guaranteed to never be %NULL (either may be empty though).
862 * This signal exists purely as a convenience to avoid having to
863 * connect signals to all interface proxies managed by @manager.
865 * This signal is emitted in the
866 * [thread-default main context][g-main-context-push-thread-default]
867 * that @manager was constructed in.
874 * GDBusObjectManagerClient::interface-proxy-signal:
875 * @manager: The #GDBusObjectManagerClient emitting the signal.
876 * @object_proxy: The #GDBusObjectProxy on which an interface is emitting a D-Bus signal.
877 * @interface_proxy: The #GDBusProxy that is emitting a D-Bus signal.
878 * @sender_name: The sender of the signal or NULL if the connection is not a bus connection.
879 * @signal_name: The signal name.
880 * @parameters: A #GVariant tuple with parameters for the signal.
882 * Emitted when a D-Bus signal is received on @interface_proxy.
884 * This signal exists purely as a convenience to avoid having to
885 * connect signals to all interface proxies managed by @manager.
887 * This signal is emitted in the
888 * [thread-default main context][g-main-context-push-thread-default]
889 * that @manager was constructed in.
896 * GDBusObjectManagerClient:bus-type:
898 * If this property is not %G_BUS_TYPE_NONE, then
899 * #GDBusObjectManagerClient:connection must be %NULL and will be set to the
900 * #GDBusConnection obtained by calling g_bus_get() with the value
908 * GDBusObjectManagerClient:connection:
910 * The #GDBusConnection to use.
917 * GDBusObjectManagerClient:flags:
919 * Flags from the #GDBusObjectManagerClientFlags enumeration.
926 * GDBusObjectManagerClient:get-proxy-type-destroy-notify:
928 * A #GDestroyNotify for the #gpointer user_data in #GDBusObjectManagerClient:get-proxy-type-user-data.
935 * GDBusObjectManagerClient:get-proxy-type-func:
937 * The #GDBusProxyTypeFunc to use when determining what #GType to
938 * use for interface proxies or %NULL.
945 * GDBusObjectManagerClient:get-proxy-type-user-data:
947 * The #gpointer user_data to pass to #GDBusObjectManagerClient:get-proxy-type-func.
954 * GDBusObjectManagerClient:name:
956 * The well-known name or unique name that the manager is for.
963 * GDBusObjectManagerClient:name-owner:
965 * The unique name that owns #GDBusObjectManagerClient:name or %NULL if
966 * no-one is currently owning the name. Connect to the
967 * #GObject::notify signal to track changes to this property.
974 * GDBusObjectManagerClient:object-path:
976 * The object path the manager is for.
983 * GDBusObjectManagerServer:connection:
985 * The #GDBusConnection to export objects on.
992 * GDBusObjectManagerServer:object-path:
994 * The object path to register the manager object at.
1001 * GDBusObjectProxy:g-connection:
1003 * The connection of the proxy.
1010 * GDBusObjectProxy:g-object-path:
1012 * The object path of the proxy.
1019 * GDBusObjectSkeleton::authorize-method:
1020 * @object: The #GDBusObjectSkeleton emitting the signal.
1021 * @interface: The #GDBusInterfaceSkeleton that @invocation is for.
1022 * @invocation: A #GDBusMethodInvocation.
1024 * Emitted when a method is invoked by a remote caller and used to
1025 * determine if the method call is authorized.
1027 * This signal is like #GDBusInterfaceSkeleton's
1028 * #GDBusInterfaceSkeleton::g-authorize-method signal,
1029 * except that it is for the enclosing object.
1031 * The default class handler just returns %TRUE.
1033 * Returns: %TRUE if the call is authorized, %FALSE otherwise.
1039 * GDBusObjectSkeleton:g-object-path:
1041 * The object path where the object is exported.
1048 * GDBusProxy::g-properties-changed:
1049 * @proxy: The #GDBusProxy emitting the signal.
1050 * @changed_properties: A #GVariant containing the properties that changed
1051 * @invalidated_properties: A %NULL terminated array of properties that was invalidated
1053 * Emitted when one or more D-Bus properties on @proxy changes. The
1054 * local cache has already been updated when this signal fires. Note
1055 * that both @changed_properties and @invalidated_properties are
1056 * guaranteed to never be %NULL (either may be empty though).
1058 * If the proxy has the flag
1059 * %G_DBUS_PROXY_FLAGS_GET_INVALIDATED_PROPERTIES set, then
1060 * @invalidated_properties will always be empty.
1062 * This signal corresponds to the
1063 * `PropertiesChanged` D-Bus signal on the
1064 * `org.freedesktop.DBus.Properties` interface.
1071 * GDBusProxy::g-signal:
1072 * @proxy: The #GDBusProxy emitting the signal.
1073 * @sender_name: (allow-none): The sender of the signal or %NULL if the connection is not a bus connection.
1074 * @signal_name: The name of the signal.
1075 * @parameters: A #GVariant tuple with parameters for the signal.
1077 * Emitted when a signal from the remote object and interface that @proxy is for, has been received.
1084 * GDBusProxy:g-bus-type:
1086 * If this property is not %G_BUS_TYPE_NONE, then
1087 * #GDBusProxy:g-connection must be %NULL and will be set to the
1088 * #GDBusConnection obtained by calling g_bus_get() with the value
1096 * GDBusProxy:g-connection:
1098 * The #GDBusConnection the proxy is for.
1105 * GDBusProxy:g-default-timeout:
1107 * The timeout to use if -1 (specifying default timeout) is passed
1108 * as @timeout_msec in the g_dbus_proxy_call() and
1109 * g_dbus_proxy_call_sync() functions.
1111 * This allows applications to set a proxy-wide timeout for all
1112 * remote method invocations on the proxy. If this property is -1,
1113 * the default timeout (typically 25 seconds) is used. If set to
1114 * %G_MAXINT, then no timeout is used.
1121 * GDBusProxy:g-flags:
1123 * Flags from the #GDBusProxyFlags enumeration.
1130 * GDBusProxy:g-interface-info:
1132 * Ensure that interactions with this proxy conform to the given
1133 * interface. This is mainly to ensure that malformed data received
1134 * from the other peer is ignored. The given #GDBusInterfaceInfo is
1135 * said to be the "expected interface".
1137 * The checks performed are:
1138 * - When completing a method call, if the type signature of
1139 * the reply message isn't what's expected, the reply is
1140 * discarded and the #GError is set to %G_IO_ERROR_INVALID_ARGUMENT.
1142 * - Received signals that have a type signature mismatch are dropped and
1143 * a warning is logged via g_warning().
1145 * - Properties received via the initial `GetAll()` call or via the
1146 * `::PropertiesChanged` signal (on the
1147 * [org.freedesktop.DBus.Properties](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties)
1148 * interface) or set using g_dbus_proxy_set_cached_property()
1149 * with a type signature mismatch are ignored and a warning is
1150 * logged via g_warning().
1152 * Note that these checks are never done on methods, signals and
1153 * properties that are not referenced in the given
1154 * #GDBusInterfaceInfo, since extending a D-Bus interface on the
1155 * service-side is not considered an ABI break.
1162 * GDBusProxy:g-interface-name:
1164 * The D-Bus interface name the proxy is for.
1171 * GDBusProxy:g-name:
1173 * The well-known or unique name that the proxy is for.
1180 * GDBusProxy:g-name-owner:
1182 * The unique name that owns #GDBusProxy:g-name or %NULL if no-one
1183 * currently owns that name. You may connect to #GObject::notify signal to
1184 * track changes to this property.
1191 * GDBusProxy:g-object-path:
1193 * The object path the proxy is for.
1202 * The #GDBusServer structure contains only private data and
1203 * should only be accessed using the provided API.
1210 * GDBusServer::new-connection:
1211 * @server: The #GDBusServer emitting the signal.
1212 * @connection: A #GDBusConnection for the new connection.
1214 * Emitted when a new authenticated connection has been made. Use
1215 * g_dbus_connection_get_peer_credentials() to figure out what
1216 * identity (if any), was authenticated.
1218 * If you want to accept the connection, take a reference to the
1219 * @connection object and return %TRUE. When you are done with the
1220 * connection call g_dbus_connection_close() and give up your
1221 * reference. Note that the other peer may disconnect at any time -
1222 * a typical thing to do when accepting a connection is to listen to
1223 * the #GDBusConnection::closed signal.
1225 * If #GDBusServer:flags contains %G_DBUS_SERVER_FLAGS_RUN_IN_THREAD
1226 * then the signal is emitted in a new thread dedicated to the
1227 * connection. Otherwise the signal is emitted in the
1228 * [thread-default main context][g-main-context-push-thread-default]
1229 * of the thread that @server was constructed in.
1231 * You are guaranteed that signal handlers for this signal runs
1232 * before incoming messages on @connection are processed. This means
1233 * that it's suitable to call g_dbus_connection_register_object() or
1234 * similar from the signal handler.
1236 * Returns: %TRUE to claim @connection, %FALSE to let other handlers
1243 * GDBusServer:active:
1245 * Whether the server is currently active.
1252 * GDBusServer:address:
1254 * The D-Bus address to listen on.
1261 * GDBusServer:authentication-observer:
1263 * A #GDBusAuthObserver object to assist in the authentication process or %NULL.
1270 * GDBusServer:client-address:
1272 * The D-Bus address that clients can use.
1279 * GDBusServer:flags:
1281 * Flags from the #GDBusServerFlags enumeration.
1290 * The guid of the server.
1298 * @new_connection: Signal class handler for the #GDBusServer::new-connection signal.
1300 * Class structure for #GDBusServer.
1307 * GDataOutputStream:byte-order:
1309 * Determines the byte ordering that is used when writing
1310 * multi-byte entities (such as integers) to the stream.
1315 * GDataStream:byte-order:
1317 * The ::byte-order property determines the byte ordering that
1318 * is used when reading multi-byte entities (such as integers)
1324 * GDataStream:newline-type:
1326 * The :newline-type property determines what is considered
1327 * as a line ending when reading complete lines from the stream.
1334 * Information about an installed application from a desktop file.
1339 * GDesktopAppInfo:filename:
1341 * The origin filename of this #GDesktopAppInfo
1347 * @drive: a #GDrive.
1349 * Emitted when the drive's state has changed.
1354 * GDrive::disconnected:
1355 * @drive: a #GDrive.
1357 * This signal is emitted when the #GDrive have been
1358 * disconnected. If the recipient is holding references to the
1359 * object they should release them so the object can be
1365 * GDrive::eject-button:
1366 * @drive: a #GDrive.
1368 * Emitted when the physical eject button (if any) of a drive has
1374 * GDrive::stop-button:
1375 * @drive: a #GDrive.
1377 * Emitted when the physical stop button (if any) of a drive has
1387 * The file containing the icon.
1392 * GFileMonitor::changed:
1393 * @monitor: a #GFileMonitor.
1395 * @other_file: (allow-none): a #GFile or #NULL.
1396 * @event_type: a #GFileMonitorEvent.
1398 * Emitted when @file has been changed.
1400 * If using #G_FILE_MONITOR_SEND_MOVED flag and @event_type is
1401 * #G_FILE_MONITOR_EVENT_MOVED, @file will be set to a #GFile containing the
1402 * old path, and @other_file will be set to a #GFile containing the new path.
1404 * In all the other cases, @other_file will be set to #NULL.
1409 * GFilenameCompleter::got-completion-data:
1411 * Emitted when the file name completion information comes available.
1418 * Represents a scope for loading IO modules. A scope can be used for blocking
1419 * duplicate modules, or blocking a module you don't want to load.
1421 * The scope can be used with g_io_modules_load_all_in_directory_with_scope()
1422 * or g_io_modules_scan_all_in_directory_with_scope().
1431 * An IPv4 or IPv6 internet address.
1436 * GInetAddress:is-any:
1438 * Whether this is the "any" address for its family.
1439 * See g_inet_address_get_is_any().
1446 * GInetAddress:is-link-local:
1448 * Whether this is a link-local address.
1449 * See g_inet_address_get_is_link_local().
1456 * GInetAddress:is-loopback:
1458 * Whether this is the loopback address for its family.
1459 * See g_inet_address_get_is_loopback().
1466 * GInetAddress:is-mc-global:
1468 * Whether this is a global multicast address.
1469 * See g_inet_address_get_is_mc_global().
1476 * GInetAddress:is-mc-link-local:
1478 * Whether this is a link-local multicast address.
1479 * See g_inet_address_get_is_mc_link_local().
1486 * GInetAddress:is-mc-node-local:
1488 * Whether this is a node-local multicast address.
1489 * See g_inet_address_get_is_mc_node_local().
1496 * GInetAddress:is-mc-org-local:
1498 * Whether this is an organization-local multicast address.
1499 * See g_inet_address_get_is_mc_org_local().
1506 * GInetAddress:is-mc-site-local:
1508 * Whether this is a site-local multicast address.
1509 * See g_inet_address_get_is_mc_site_local().
1516 * GInetAddress:is-multicast:
1518 * Whether this is a multicast address.
1519 * See g_inet_address_get_is_multicast().
1526 * GInetAddress:is-site-local:
1528 * Whether this is a site-local address.
1529 * See g_inet_address_get_is_loopback().
1538 * A combination of an IPv4 or IPv6 base address and a length,
1539 * representing a range of IP addresses.
1546 * GInetSocketAddress:
1548 * An IPv4 or IPv6 socket address, corresponding to a struct
1549 * sockaddr_in or struct sockaddr_in6.
1554 * GInetSocketAddress:flowinfo:
1556 * The `sin6_flowinfo` field, for IPv6 addresses.
1563 * GInetSocketAddress:scope_id:
1565 * The `sin6_scope_id` field, for IPv6 addresses.
1572 * GMemoryOutputStream:data:
1574 * Pointer to buffer where data will be written.
1581 * GMemoryOutputStream:data-size:
1583 * Size of data written to the buffer.
1590 * GMemoryOutputStream:destroy-function: (skip)
1592 * Function called with the buffer as argument when the stream is destroyed.
1599 * GMemoryOutputStream:realloc-function: (skip)
1601 * Function with realloc semantics called to enlarge the buffer.
1608 * GMemoryOutputStream:size:
1610 * Current size of the data buffer.
1619 * #GMenu is an opaque structure type. You must access it using the
1627 * GMenuAttributeIter:
1629 * #GMenuAttributeIter is an opaque structure type. You must access it
1630 * using the functions below.
1639 * #GMenuItem is an opaque structure type. You must access it using the
1649 * #GMenuLinkIter is an opaque structure type. You must access it using
1650 * the functions below.
1659 * #GMenuModel is an opaque structure type. You must access it using the
1667 * GMenuModel::items-changed:
1668 * @model: the #GMenuModel that is changing
1669 * @position: the position of the change
1670 * @removed: the number of items removed
1671 * @added: the number of items added
1673 * Emitted when a change has occured to the menu.
1675 * The only changes that can occur to a menu is that items are removed
1676 * or added. Items may not change (except by being removed and added
1677 * back in the same location). This signal is capable of describing
1678 * both of those changes (at the same time).
1680 * The signal means that starting at the index @position, @removed
1681 * items were removed and @added items were added in their place. If
1682 * @removed is zero then only items were added. If @added is zero
1683 * then only items were removed.
1685 * As an example, if the menu contains items a, b, c, d (in that
1686 * order) and the signal (2, 1, 3) occurs then the new composition of
1687 * the menu will be a, b, _, _, _, d (with each _ representing some
1690 * Signal handlers may query the model (particularly the added items)
1691 * and expect to see the results of the modification that is being
1692 * reported. The signal is emitted after the modification.
1698 * @mount: the object on which the signal is emitted
1700 * Emitted when the mount has been changed.
1705 * GMount::pre-unmount:
1706 * @mount: the object on which the signal is emitted
1708 * This signal is emitted when the #GMount is about to be
1716 * GMount::unmounted:
1717 * @mount: the object on which the signal is emitted
1719 * This signal is emitted when the #GMount have been
1720 * unmounted. If the recipient is holding references to the
1721 * object they should release them so the object can be
1727 * GMountOperation::aborted:
1729 * Emitted by the backend when e.g. a device becomes unavailable
1730 * while a mount operation is in progress.
1732 * Implementations of GMountOperation should handle this signal
1733 * by dismissing open password dialogs.
1740 * GMountOperation::ask-password:
1741 * @op: a #GMountOperation requesting a password.
1742 * @message: string containing a message to display to the user.
1743 * @default_user: string containing the default user name.
1744 * @default_domain: string containing the default domain.
1745 * @flags: a set of #GAskPasswordFlags.
1747 * Emitted when a mount operation asks the user for a password.
1749 * If the message contains a line break, the first line should be
1750 * presented as a heading. For example, it may be used as the
1751 * primary text in a #GtkMessageDialog.
1756 * GMountOperation::ask-question:
1757 * @op: a #GMountOperation asking a question.
1758 * @message: string containing a message to display to the user.
1759 * @choices: an array of strings for each possible choice.
1761 * Emitted when asking the user a question and gives a list of
1762 * choices for the user to choose from.
1764 * If the message contains a line break, the first line should be
1765 * presented as a heading. For example, it may be used as the
1766 * primary text in a #GtkMessageDialog.
1771 * GMountOperation::reply:
1772 * @op: a #GMountOperation.
1773 * @result: a #GMountOperationResult indicating how the request was handled
1775 * Emitted when the user has replied to the mount operation.
1780 * GMountOperation::show-processes:
1781 * @op: a #GMountOperation.
1782 * @message: string containing a message to display to the user.
1783 * @processes: (element-type GPid): an array of #GPid for processes
1784 * blocking the operation.
1785 * @choices: an array of strings for each possible choice.
1787 * Emitted when one or more processes are blocking an operation
1788 * e.g. unmounting/ejecting a #GMount or stopping a #GDrive.
1790 * Note that this signal may be emitted several times to update the
1791 * list of blocking processes as processes close files. The
1792 * application should only respond with g_mount_operation_reply() to
1793 * the latest signal (setting #GMountOperation:choice to the choice
1796 * If the message contains a line break, the first line should be
1797 * presented as a heading. For example, it may be used as the
1798 * primary text in a #GtkMessageDialog.
1805 * GMountOperation::show-unmount-progress:
1806 * @op: a #GMountOperation:
1807 * @message: string containing a mesage to display to the user
1808 * @time_left: the estimated time left before the operation completes,
1809 * in microseconds, or -1
1810 * @bytes_left: the amount of bytes to be written before the operation
1811 * completes (or -1 if such amount is not known), or zero if the operation
1814 * Emitted when an unmount operation has been busy for more than some time
1815 * (typically 1.5 seconds).
1817 * When unmounting or ejecting a volume, the kernel might need to flush
1818 * pending data in its buffers to the volume stable storage, and this operation
1819 * can take a considerable amount of time. This signal may be emitted several
1820 * times as long as the unmount operation is outstanding, and then one
1821 * last time when the operation is completed, with @bytes_left set to zero.
1823 * Implementations of GMountOperation should handle this signal by
1824 * showing an UI notification, and then dismiss it, or show another notification
1825 * of completion, when @bytes_left reaches zero.
1827 * If the message contains a line break, the first line should be
1828 * presented as a heading. For example, it may be used as the
1829 * primary text in a #GtkMessageDialog.
1836 * GMountOperation:anonymous:
1838 * Whether to use an anonymous user when authenticating.
1843 * GMountOperation:choice:
1845 * The index of the user's choice when a question is asked during the
1846 * mount operation. See the #GMountOperation::ask-question signal.
1851 * GMountOperation:domain:
1853 * The domain to use for the mount operation.
1858 * GMountOperation:password:
1860 * The password that is used for authentication when carrying out
1861 * the mount operation.
1866 * GMountOperation:password-save:
1868 * Determines if and how the password information should be saved.
1873 * GMountOperation:username:
1875 * The user name that is used for authentication when carrying out
1876 * the mount operation.
1883 * A #GSocketConnectable for resolving a hostname and connecting to
1891 * #GNetworkMonitor monitors the status of network connections and
1892 * indicates when a possibly-user-visible change has occurred.
1899 * GNetworkMonitor::network-changed:
1900 * @monitor: a #GNetworkMonitor
1901 * @available: the current value of #GNetworkMonitor:network-available
1903 * Emitted when the network configuration changes. If @available is
1904 * %TRUE, then some hosts may be reachable that were not reachable
1905 * before, while others that were reachable before may no longer be
1906 * reachable. If @available is %FALSE, then no remote hosts are
1914 * GNetworkMonitor:network-available:
1916 * Whether the network is considered available. That is, whether the
1917 * system has a default route for at least one of IPv4 or IPv6.
1919 * Real-world networks are of course much more complicated than
1920 * this; the machine may be connected to a wifi hotspot that
1921 * requires payment before allowing traffic through, or may be
1922 * connected to a functioning router that has lost its own upstream
1923 * connectivity. Some hosts might only be accessible when a VPN is
1924 * active. Other hosts might only be accessible when the VPN is
1925 * not active. Thus, it is best to use g_network_monitor_can_reach()
1926 * or g_network_monitor_can_reach_async() to test for reachability
1927 * on a host-by-host basis. (On the other hand, when the property is
1928 * %FALSE, the application can reasonably expect that no remote
1929 * hosts at all are reachable, and should indicate this to the user
1932 * See also #GNetworkMonitor::network-changed.
1941 * A #GSocketConnectable for resolving a SRV record and connecting to
1949 * This structure type is private and should only be accessed using the
1959 * #GPermission is an opaque data structure and can only be accessed
1960 * using the following functions.
1965 * GPermission:allowed:
1967 * %TRUE if the caller currently has permission to perform the action that
1968 * @permission represents the permission to perform.
1973 * GPermission:can-acquire:
1975 * %TRUE if it is generally possible to acquire the permission by calling
1976 * g_permission_acquire().
1981 * GPermission:can-release:
1983 * %TRUE if it is generally possible to release the permission by calling
1984 * g_permission_release().
1991 * This type is opaque.
1998 * GPropertyAction:enabled:
2000 * If @action is currently enabled.
2002 * If the action is disabled then calls to g_action_activate() and
2003 * g_action_change_state() have no effect.
2010 * GPropertyAction:name:
2012 * The name of the action. This is mostly meaningful for identifying
2013 * the action once it has been added to a #GActionMap.
2020 * GPropertyAction:object:
2022 * The object to wrap a property on.
2024 * The object must be a non-%NULL #GObject with properties.
2031 * GPropertyAction:parameter-type:
2033 * The type of the parameter that must be given when activating the
2041 * GPropertyAction:property-name:
2043 * The name of the property to wrap on the object.
2045 * The property must exist on the passed-in object and it must be
2046 * readable and writable (and not construct-only).
2053 * GPropertyAction:state:
2055 * The state of the action, or %NULL if the action is stateless.
2062 * GPropertyAction:state-type:
2064 * The #GVariantType of the state that the action has, or %NULL if the
2065 * action is stateless.
2074 * A #GInetSocketAddress representing a connection via a proxy server
2081 * GProxyAddress:destination-protocol:
2083 * The protocol being spoke to the destination host, or %NULL if
2084 * the #GProxyAddress doesn't know.
2091 * GProxyAddress:uri:
2093 * The URI string that the proxy was constructed from (or %NULL
2094 * if the creator didn't specify this).
2101 * GProxyAddressEnumerator:default-port:
2103 * The default port to use if #GProxyAddressEnumerator:uri does not
2111 * GProxyAddressEnumerator:proxy-resolver:
2113 * The proxy resolver to use.
2120 * GRemoteActionGroupInterface:
2121 * @activate_action_full: the virtual function pointer for g_remote_action_group_activate_action_full()
2122 * @change_action_state_full: the virtual function pointer for g_remote_action_group_change_action_state_full()
2124 * The virtual function table for #GRemoteActionGroup.
2133 * The object that handles DNS resolution. Use g_resolver_get_default()
2134 * to get the default resolver.
2139 * GResolver::reload:
2140 * @resolver: a #GResolver
2142 * Emitted when the resolver notices that the system resolver
2143 * configuration has changed.
2148 * GSettings::change-event:
2149 * @settings: the object on which the signal was emitted
2150 * @keys: (array length=n_keys) (element-type GQuark) (allow-none):
2151 * an array of #GQuarks for the changed keys, or %NULL
2152 * @n_keys: the length of the @keys array, or 0
2154 * The "change-event" signal is emitted once per change event that
2155 * affects this settings object. You should connect to this signal
2156 * only if you are interested in viewing groups of changes before they
2157 * are split out into multiple emissions of the "changed" signal.
2158 * For most use cases it is more appropriate to use the "changed" signal.
2160 * In the event that the change event applies to one or more specified
2161 * keys, @keys will be an array of #GQuark of length @n_keys. In the
2162 * event that the change event applies to the #GSettings object as a
2163 * whole (ie: potentially every key has been changed) then @keys will
2164 * be %NULL and @n_keys will be 0.
2166 * The default handler for this signal invokes the "changed" signal
2167 * for each affected key. If any other connected handler returns
2168 * %TRUE then this default functionality will be suppressed.
2170 * Returns: %TRUE to stop other handlers from being invoked for the
2171 * event. FALSE to propagate the event further.
2176 * GSettings::changed:
2177 * @settings: the object on which the signal was emitted
2178 * @key: the name of the key that changed
2180 * The "changed" signal is emitted when a key has potentially changed.
2181 * You should call one of the g_settings_get() calls to check the new
2184 * This signal supports detailed connections. You can connect to the
2185 * detailed signal "changed::x" in order to only receive callbacks
2186 * when key "x" changes.
2191 * GSettings::writable-change-event:
2192 * @settings: the object on which the signal was emitted
2193 * @key: the quark of the key, or 0
2195 * The "writable-change-event" signal is emitted once per writability
2196 * change event that affects this settings object. You should connect
2197 * to this signal if you are interested in viewing groups of changes
2198 * before they are split out into multiple emissions of the
2199 * "writable-changed" signal. For most use cases it is more
2200 * appropriate to use the "writable-changed" signal.
2202 * In the event that the writability change applies only to a single
2203 * key, @key will be set to the #GQuark for that key. In the event
2204 * that the writability change affects the entire settings object,
2207 * The default handler for this signal invokes the "writable-changed"
2208 * and "changed" signals for each affected key. This is done because
2209 * changes in writability might also imply changes in value (if for
2210 * example, a new mandatory setting is introduced). If any other
2211 * connected handler returns %TRUE then this default functionality
2212 * will be suppressed.
2214 * Returns: %TRUE to stop other handlers from being invoked for the
2215 * event. FALSE to propagate the event further.
2220 * GSettings::writable-changed:
2221 * @settings: the object on which the signal was emitted
2224 * The "writable-changed" signal is emitted when the writability of a
2225 * key has potentially changed. You should call
2226 * g_settings_is_writable() in order to determine the new status.
2228 * This signal supports detailed connections. You can connect to the
2229 * detailed signal "writable-changed::x" in order to only receive
2230 * callbacks when the writability of "x" changes.
2235 * GSettings:context:
2237 * The name of the context that the settings are stored in.
2242 * GSettings:delay-apply:
2244 * Whether the #GSettings object is in 'delay-apply' mode. See
2245 * g_settings_delay() for details.
2252 * GSettings:has-unapplied:
2254 * If this property is %TRUE, the #GSettings object has outstanding
2255 * changes that will be applied when g_settings_apply() is called.
2262 * The path within the backend where the settings are stored.
2269 * The name of the schema that describes the types of keys
2270 * for this #GSettings object.
2272 * The type of this property is *not* #GSettingsSchema.
2273 * #GSettingsSchema has only existed since version 2.32 and
2274 * unfortunately this name was used in previous versions to refer to
2275 * the schema ID rather than the schema itself. Take care to use the
2276 * 'settings-schema' property if you wish to pass in a
2279 * Deprecated: 2.32: Use the 'schema-id' property instead. In a future
2280 * version, this property may instead refer to a #GSettingsSchema.
2285 * GSettings:schema-id:
2287 * The name of the schema that describes the types of keys
2288 * for this #GSettings object.
2293 * GSettings:settings-schema:
2295 * The #GSettingsSchema describing the types of keys for this
2296 * #GSettings object.
2298 * Ideally, this property would be called 'schema'. #GSettingsSchema
2299 * has only existed since version 2.32, however, and before then the
2300 * 'schema' property was used to refer to the ID of the schema rather
2301 * than the schema itself. Take care.
2308 * This is an opaque structure type. You may not access it directly.
2315 * GSettingsSchemaSource:
2317 * This is an opaque structure type. You may not access it directly.
2324 * GSimpleAction::activate:
2325 * @simple: the #GSimpleAction
2326 * @parameter: (allow-none): the parameter to the activation
2328 * Indicates that the action was just activated.
2330 * @parameter will always be of the expected type. In the event that
2331 * an incorrect type was given, no signal will be emitted.
2333 * Since GLib 2.40, if no handler is connected to this signal then the
2334 * default behaviour for boolean-stated actions with a %NULL parameter
2335 * type is to toggle them via the #GSimpleAction::change-state signal.
2336 * For stateful actions where the state type is equal to the parameter
2337 * type, the default is to forward them directly to
2338 * #GSimpleAction::change-state. This should allow almost all users
2339 * of #GSimpleAction to connect only one handler or the other.
2346 * GSimpleAction::change-state:
2347 * @simple: the #GSimpleAction
2348 * @value: (allow-none): the requested value for the state
2350 * Indicates that the action just received a request to change its
2353 * @value will always be of the correct state type. In the event that
2354 * an incorrect type was given, no signal will be emitted.
2356 * If no handler is connected to this signal then the default
2357 * behaviour is to call g_simple_action_set_state() to set the state
2358 * to the requested value. If you connect a signal handler then no
2359 * default action is taken. If the state should change then you must
2360 * call g_simple_action_set_state() from the handler.
2362 * An example of a 'change-state' handler:
2363 * |[<!-- language="C" -->
2365 * change_volume_state (GSimpleAction *action,
2367 * gpointer user_data)
2371 * requested = g_variant_get_int32 (value);
2373 * // Volume only goes from 0 to 10
2374 * if (0 <= requested && requested <= 10)
2375 * g_simple_action_set_state (action, value);
2379 * The handler need not set the state to the requested value.
2380 * It could set it to any value at all, or take some other action.
2387 * GSimpleAction:enabled:
2389 * If @action is currently enabled.
2391 * If the action is disabled then calls to g_action_activate() and
2392 * g_action_change_state() have no effect.
2399 * GSimpleAction:name:
2401 * The name of the action. This is mostly meaningful for identifying
2402 * the action once it has been added to a #GSimpleActionGroup.
2409 * GSimpleAction:parameter-type:
2411 * The type of the parameter that must be given when activating the
2419 * GSimpleAction:state:
2421 * The state of the action, or %NULL if the action is stateless.
2428 * GSimpleAction:state-type:
2430 * The #GVariantType of the state that the action has, or %NULL if the
2431 * action is stateless.
2438 * GSimplePermission:
2440 * #GSimplePermission is an opaque data structure. There are no methods
2441 * except for those defined by #GPermission.
2446 * GSimpleProxyResolver:default-proxy:
2448 * The default proxy URI that will be used for any URI that doesn't
2449 * match #GSimpleProxyResolver:ignore-hosts, and doesn't match any
2450 * of the schemes set with g_simple_proxy_resolver_set_uri_proxy().
2452 * Note that as a special case, if this URI starts with
2453 * "socks://", #GSimpleProxyResolver will treat it as referring
2454 * to all three of the socks5, socks4a, and socks4 proxy types.
2459 * GSimpleProxyResolver:ignore-hosts:
2461 * A list of hostnames and IP addresses that the resolver should
2462 * allow direct connections to.
2464 * Entries can be in one of 4 formats:
2466 * - A hostname, such as "example.com", ".example.com", or
2467 * "*.example.com", any of which match "example.com" or
2468 * any subdomain of it.
2470 * - An IPv4 or IPv6 address, such as "192.168.1.1",
2471 * which matches only that address.
2473 * - A hostname or IP address followed by a port, such as
2474 * "example.com:80", which matches whatever the hostname or IP
2475 * address would match, but only for URLs with the (explicitly)
2476 * indicated port. In the case of an IPv6 address, the address
2477 * part must appear in brackets: "[::1]:443"
2479 * - An IP address range, given by a base address and prefix length,
2480 * such as "fe80::/10", which matches any address in that range.
2482 * Note that when dealing with Unicode hostnames, the matching is
2483 * done against the ASCII form of the name.
2485 * Also note that hostname exclusions apply only to connections made
2486 * to hosts identified by name, and IP address exclusions apply only
2487 * to connections made to hosts identified by address. That is, if
2488 * example.com has an address of 192.168.1.1, and the :ignore-hosts list
2489 * contains only "192.168.1.1", then a connection to "example.com"
2490 * (eg, via a #GNetworkAddress) will use the proxy, and a connection to
2491 * "192.168.1.1" (eg, via a #GInetSocketAddress) will not.
2493 * These rules match the "ignore-hosts"/"noproxy" rules most
2494 * commonly used by other applications.
2499 * GSocket:broadcast:
2501 * Whether the socket should allow sending to broadcast addresses.
2508 * GSocket:multicast-loopback:
2510 * Whether outgoing multicast packets loop back to the local host.
2517 * GSocket:multicast-ttl:
2519 * Time-to-live out outgoing multicast packets
2528 * The timeout in seconds on socket I/O
2537 * Time-to-live for outgoing unicast packets
2546 * A socket endpoint address, corresponding to struct sockaddr
2547 * or one of its subtypes.
2552 * GSocketClient::event:
2553 * @client: the #GSocketClient
2554 * @event: the event that is occurring
2555 * @connectable: the #GSocketConnectable that @event is occurring on
2556 * @connection: the current representation of the connection
2558 * Emitted when @client's activity on @connectable changes state.
2559 * Among other things, this can be used to provide progress
2560 * information about a network connection in the UI. The meanings of
2561 * the different @event values are as follows:
2563 * - %G_SOCKET_CLIENT_RESOLVING: @client is about to look up @connectable
2564 * in DNS. @connection will be %NULL.
2566 * - %G_SOCKET_CLIENT_RESOLVED: @client has successfully resolved
2567 * @connectable in DNS. @connection will be %NULL.
2569 * - %G_SOCKET_CLIENT_CONNECTING: @client is about to make a connection
2570 * to a remote host; either a proxy server or the destination server
2571 * itself. @connection is the #GSocketConnection, which is not yet
2572 * connected. Since GLib 2.40, you can access the remote
2573 * address via g_socket_connection_get_remote_address().
2575 * - %G_SOCKET_CLIENT_CONNECTED: @client has successfully connected
2576 * to a remote host. @connection is the connected #GSocketConnection.
2578 * - %G_SOCKET_CLIENT_PROXY_NEGOTIATING: @client is about to negotiate
2579 * with a proxy to get it to connect to @connectable. @connection is
2580 * the #GSocketConnection to the proxy server.
2582 * - %G_SOCKET_CLIENT_PROXY_NEGOTIATED: @client has negotiated a
2583 * connection to @connectable through a proxy server. @connection is
2584 * the stream returned from g_proxy_connect(), which may or may not
2585 * be a #GSocketConnection.
2587 * - %G_SOCKET_CLIENT_TLS_HANDSHAKING: @client is about to begin a TLS
2588 * handshake. @connection is a #GTlsClientConnection.
2590 * - %G_SOCKET_CLIENT_TLS_HANDSHAKED: @client has successfully completed
2591 * the TLS handshake. @connection is a #GTlsClientConnection.
2593 * - %G_SOCKET_CLIENT_COMPLETE: @client has either successfully connected
2594 * to @connectable (in which case @connection is the #GSocketConnection
2595 * that it will be returning to the caller) or has failed (in which
2596 * case @connection is %NULL and the client is about to return an error).
2598 * Each event except %G_SOCKET_CLIENT_COMPLETE may be emitted
2599 * multiple times (or not at all) for a given connectable (in
2600 * particular, if @client ends up attempting to connect to more than
2601 * one address). However, if @client emits the #GSocketClient::event
2602 * signal at all for a given connectable, that it will always emit
2603 * it with %G_SOCKET_CLIENT_COMPLETE when it is done.
2605 * Note that there may be additional #GSocketClientEvent values in
2606 * the future; unrecognized @event values should be ignored.
2613 * GSocketClient:proxy-resolver:
2615 * The proxy resolver to use
2622 * GSocketService::incoming:
2623 * @service: the #GSocketService
2624 * @connection: a new #GSocketConnection object
2625 * @source_object: (allow-none): the source_object passed to
2626 * g_socket_listener_add_address()
2628 * The ::incoming signal is emitted when a new incoming connection
2629 * to @service needs to be handled. The handler must initiate the
2630 * handling of @connection, but may not block; in essence,
2631 * asynchronous operations must be used.
2633 * @connection will be unreffed once the signal handler returns,
2634 * so you need to ref it yourself if you are planning to use it.
2636 * Returns: %TRUE to stop other handlers from being called
2644 * A single target host/port that a network service is running on.
2651 * The opaque object representing a synchronous or asynchronous task
2659 * @source_object: (type GObject): @task's source object
2660 * @task_data: @task's task data
2661 * @cancellable: @task's #GCancellable, or %NULL
2663 * The prototype for a task function to be run in a thread via
2664 * g_task_run_in_thread() or g_task_run_in_thread_sync().
2666 * If the return-on-cancel flag is set on @task, and @cancellable gets
2667 * cancelled, then the #GTask will be completed immediately (as though
2668 * g_task_return_error_if_cancelled() had been called), without
2669 * waiting for the task function to complete. However, the task
2670 * function will continue running in its thread in the background. The
2671 * function therefore needs to be careful about how it uses
2672 * externally-visible state in this case. See
2673 * g_task_set_return_on_cancel() for more details.
2675 * Other than in that case, @task will be completed when the
2676 * #GTaskThreadFunc returns, not when it calls a
2677 * `g_task_return_` function.
2686 * The #GTestDBus structure contains only private data and
2687 * should only be accessed using the provided API.
2696 * #GTestDBusFlags specifying the behaviour of the D-Bus session.
2710 * GThemedIcon:names:
2712 * A %NULL-terminated array of icon names.
2717 * GThemedIcon:use-default-fallbacks:
2719 * Whether to use the default fallbacks found by shortening the icon name
2720 * at '-' characters. If the "names" array has more than one element,
2721 * ignores any past the first.
2723 * For example, if the icon name was "gnome-dev-cdrom-audio", the array
2725 * |[<!-- language="C" -->
2727 * "gnome-dev-cdrom-audio",
2728 * "gnome-dev-cdrom",
2738 * GThreadedSocketService::run:
2739 * @service: the #GThreadedSocketService.
2740 * @connection: a new #GSocketConnection object.
2741 * @source_object: the source_object passed to g_socket_listener_add_address().
2743 * The ::run signal is emitted in a worker thread in response to an
2744 * incoming connection. This thread is dedicated to handling
2745 * @connection and may perform blocking IO. The signal handler need
2746 * not return until the connection is closed.
2748 * Returns: %TRUE to stop further signal handlers from being called
2755 * TLS (Transport Layer Security, aka SSL) backend. This is an
2756 * internal type used to coordinate the different classes implemented
2766 * Abstract base class for TLS certificate types.
2773 * GTlsCertificate:certificate:
2775 * The DER (binary) encoded representation of the certificate.
2776 * This property and the #GTlsCertificate:certificate-pem property
2777 * represent the same data, just in different forms.
2784 * GTlsCertificate:certificate-pem:
2786 * The PEM (ASCII) encoded representation of the certificate.
2787 * This property and the #GTlsCertificate:certificate
2788 * property represent the same data, just in different forms.
2795 * GTlsCertificate:issuer:
2797 * A #GTlsCertificate representing the entity that issued this
2798 * certificate. If %NULL, this means that the certificate is either
2799 * self-signed, or else the certificate of the issuer is not
2807 * GTlsCertificate:private-key:
2809 * The DER (binary) encoded representation of the certificate's
2810 * private key, in either PKCS#1 format or unencrypted PKCS#8
2811 * format. This property (or the #GTlsCertificate:private-key-pem
2812 * property) can be set when constructing a key (eg, from a file),
2813 * but cannot be read.
2815 * PKCS#8 format is supported since 2.32; earlier releases only
2816 * support PKCS#1. You can use the `openssl rsa`
2817 * tool to convert PKCS#8 keys to PKCS#1.
2824 * GTlsCertificate:private-key-pem:
2826 * The PEM (ASCII) encoded representation of the certificate's
2827 * private key in either PKCS#1 format ("`BEGIN RSA PRIVATE
2828 * KEY`") or unencrypted PKCS#8 format ("`BEGIN
2829 * PRIVATE KEY`"). This property (or the
2830 * #GTlsCertificate:private-key property) can be set when
2831 * constructing a key (eg, from a file), but cannot be read.
2833 * PKCS#8 format is supported since 2.32; earlier releases only
2834 * support PKCS#1. You can use the `openssl rsa`
2835 * tool to convert PKCS#8 keys to PKCS#1.
2842 * GTlsClientConnection:
2844 * Abstract base class for the backend-specific client connection
2852 * GTlsClientConnection:accepted-cas: (type GLib.List) (element-type GLib.ByteArray)
2854 * A list of the distinguished names of the Certificate Authorities
2855 * that the server will accept client certificates signed by. If the
2856 * server requests a client certificate during the handshake, then
2857 * this property will be set after the handshake completes.
2859 * Each item in the list is a #GByteArray which contains the complete
2860 * subject DN of the certificate authority.
2867 * GTlsClientConnection:server-identity:
2869 * A #GSocketConnectable describing the identity of the server that
2870 * is expected on the other end of the connection.
2872 * If the %G_TLS_CERTIFICATE_BAD_IDENTITY flag is set in
2873 * #GTlsClientConnection:validation-flags, this object will be used
2874 * to determine the expected identify of the remote end of the
2875 * connection; if #GTlsClientConnection:server-identity is not set,
2876 * or does not match the identity presented by the server, then the
2877 * %G_TLS_CERTIFICATE_BAD_IDENTITY validation will fail.
2879 * In addition to its use in verifying the server certificate,
2880 * this is also used to give a hint to the server about what
2881 * certificate we expect, which is useful for servers that serve
2889 * GTlsClientConnection:use-ssl3:
2891 * If %TRUE, tells the connection to use SSL 3.0 rather than trying
2892 * to negotiate the best version of TLS or SSL to use. This can be
2893 * used when talking to servers that don't implement version
2894 * negotiation correctly and therefore refuse to handshake at all with
2895 * a "modern" TLS handshake.
2902 * GTlsClientConnection:validation-flags:
2904 * What steps to perform when validating a certificate received from
2905 * a server. Server certificates that fail to validate in all of the
2906 * ways indicated here will be rejected unless the application
2907 * overrides the default via #GTlsConnection::accept-certificate.
2916 * Abstract base class for the backend-specific #GTlsClientConnection
2917 * and #GTlsServerConnection types.
2924 * GTlsConnection::accept-certificate:
2925 * @conn: a #GTlsConnection
2926 * @peer_cert: the peer's #GTlsCertificate
2927 * @errors: the problems with @peer_cert.
2929 * Emitted during the TLS handshake after the peer certificate has
2930 * been received. You can examine @peer_cert's certification path by
2931 * calling g_tls_certificate_get_issuer() on it.
2933 * For a client-side connection, @peer_cert is the server's
2934 * certificate, and the signal will only be emitted if the
2935 * certificate was not acceptable according to @conn's
2936 * #GTlsClientConnection:validation_flags. If you would like the
2937 * certificate to be accepted despite @errors, return %TRUE from the
2938 * signal handler. Otherwise, if no handler accepts the certificate,
2939 * the handshake will fail with %G_TLS_ERROR_BAD_CERTIFICATE.
2941 * For a server-side connection, @peer_cert is the certificate
2942 * presented by the client, if this was requested via the server's
2943 * #GTlsServerConnection:authentication_mode. On the server side,
2944 * the signal is always emitted when the client presents a
2945 * certificate, and the certificate will only be accepted if a
2946 * handler returns %TRUE.
2948 * Note that if this signal is emitted as part of asynchronous I/O
2949 * in the main thread, then you should not attempt to interact with
2950 * the user before returning from the signal handler. If you want to
2951 * let the user decide whether or not to accept the certificate, you
2952 * would have to return %FALSE from the signal handler on the first
2953 * attempt, and then after the connection attempt returns a
2954 * %G_TLS_ERROR_HANDSHAKE, you can interact with the user, and if
2955 * the user decides to accept the certificate, remember that fact,
2956 * create a new connection, and return %TRUE from the signal handler
2959 * If you are doing I/O in another thread, you do not
2960 * need to worry about this, and can simply block in the signal
2961 * handler until the UI thread returns an answer.
2963 * Returns: %TRUE to accept @peer_cert (which will also
2964 * immediately end the signal emission). %FALSE to allow the signal
2965 * emission to continue, which will cause the handshake to fail if
2966 * no one else overrides it.
2972 * GTlsConnection:base-io-stream:
2974 * The #GIOStream that the connection wraps
2981 * GTlsConnection:certificate:
2983 * The connection's certificate; see
2984 * g_tls_connection_set_certificate().
2991 * GTlsConnection:database:
2993 * The certificate database to use when verifying this TLS connection.
2994 * If no cerificate database is set, then the default database will be
2995 * used. See g_tls_backend_get_default_database().
3002 * GTlsConnection:interaction:
3004 * A #GTlsInteraction object to be used when the connection or certificate
3005 * database need to interact with the user. This will be used to prompt the
3006 * user for passwords where necessary.
3013 * GTlsConnection:peer-certificate:
3015 * The connection's peer's certificate, after the TLS handshake has
3016 * completed and the certificate has been accepted. Note in
3017 * particular that this is not yet set during the emission of
3018 * #GTlsConnection::accept-certificate.
3020 * (You can watch for a #GObject::notify signal on this property to
3021 * detect when a handshake has occurred.)
3028 * GTlsConnection:peer-certificate-errors:
3030 * The errors noticed-and-ignored while verifying
3031 * #GTlsConnection:peer-certificate. Normally this should be 0, but
3032 * it may not be if #GTlsClientConnection:validation-flags is not
3033 * %G_TLS_CERTIFICATE_VALIDATE_ALL, or if
3034 * #GTlsConnection::accept-certificate overrode the default
3042 * GTlsConnection:rehandshake-mode:
3044 * The rehandshaking mode. See
3045 * g_tls_connection_set_rehandshake_mode().
3052 * GTlsConnection:require-close-notify:
3054 * Whether or not proper TLS close notification is required.
3055 * See g_tls_connection_set_require_close_notify().
3062 * GTlsConnection:use-system-certdb:
3064 * Whether or not the system certificate database will be used to
3065 * verify peer certificates. See
3066 * g_tls_connection_set_use_system_certdb().
3068 * Deprecated: 2.30: Use GTlsConnection:database instead
3075 * Abstract base class for the backend-specific database types.
3084 * Implemented by a #GTlsDatabase which allows you to load certificates
3092 * GTlsFileDatabase:anchors:
3094 * The path to a file containing PEM encoded certificate authority
3095 * root anchors. The certificates in this file will be treated as
3096 * root authorities for the purpose of verifying other certificates
3097 * via the g_tls_database_verify_chain() operation.
3106 * An object representing interaction that the TLS connection and database
3107 * might have with the user.
3114 * GTlsInteractionClass:
3115 * @ask_password: ask for a password synchronously. If the implementation
3116 * returns %G_TLS_INTERACTION_HANDLED, then the password argument should
3117 * have been filled in by using g_tls_password_set_value() or a similar
3119 * @ask_password_async: ask for a password asynchronously.
3120 * @ask_password_finish: complete operation to ask for a password asynchronously.
3121 * If the implementation returns %G_TLS_INTERACTION_HANDLED, then the
3122 * password argument of the async method should have been filled in by using
3123 * g_tls_password_set_value() or a similar function.
3125 * The class for #GTlsInteraction. Derived classes implement the various
3126 * virtual interaction methods to handle TLS interactions.
3128 * Derived classes can choose to implement whichever interactions methods they'd
3129 * like to support by overriding those virtual methods in their class
3130 * initialization function. If a derived class implements an async method,
3131 * it must also implement the corresponding finish method.
3133 * The synchronous interaction methods should implement to display modal dialogs,
3134 * and the asynchronous methods to display modeless dialogs.
3136 * If the user cancels an interaction, then the result should be
3137 * %G_TLS_INTERACTION_FAILED and the error should be set with a domain of
3138 * %G_IO_ERROR and code of %G_IO_ERROR_CANCELLED.
3147 * An abstract interface representing a password used in TLS. Often used in
3148 * user interaction such as unlocking a key storage token.
3155 * GTlsServerConnection:authentication-mode:
3157 * The #GTlsAuthenticationMode for the server. This can be changed
3158 * before calling g_tls_connection_handshake() if you want to
3159 * rehandshake with a different mode from the initial handshake.
3166 * GUnixCredentialsMessage:credentials:
3168 * The credentials stored in the message.
3175 * GUnixInputStream:close-fd:
3177 * Whether to close the file descriptor when the stream is closed.
3184 * GUnixInputStream:fd:
3186 * The file descriptor that the stream reads from.
3193 * GUnixMountMonitor::mountpoints-changed:
3194 * @monitor: the object on which the signal is emitted
3196 * Emitted when the unix mount points have changed.
3201 * GUnixMountMonitor::mounts-changed:
3202 * @monitor: the object on which the signal is emitted
3204 * Emitted when the unix mounts have changed.
3209 * GUnixOutputStream:close-fd:
3211 * Whether to close the file descriptor when the stream is closed.
3218 * GUnixOutputStream:fd:
3220 * The file descriptor that the stream writes to.
3227 * GUnixSocketAddress:
3229 * A UNIX-domain (local) socket address, corresponding to a
3230 * struct sockaddr_un.
3235 * GUnixSocketAddress:abstract:
3237 * Whether or not this is an abstract address
3239 * Deprecated: Use #GUnixSocketAddress:address-type, which
3240 * distinguishes between zero-padded and non-zero-padded
3241 * abstract addresses.
3248 * Emitted when the volume has been changed.
3255 * This signal is emitted when the #GVolume have been removed. If
3256 * the recipient is holding references to the object they should
3257 * release them so the object can be finalized.
3262 * GVolumeMonitor::drive-changed:
3263 * @volume_monitor: The volume monitor emitting the signal.
3264 * @drive: the drive that changed
3266 * Emitted when a drive changes.
3271 * GVolumeMonitor::drive-connected:
3272 * @volume_monitor: The volume monitor emitting the signal.
3273 * @drive: a #GDrive that was connected.
3275 * Emitted when a drive is connected to the system.
3280 * GVolumeMonitor::drive-disconnected:
3281 * @volume_monitor: The volume monitor emitting the signal.
3282 * @drive: a #GDrive that was disconnected.
3284 * Emitted when a drive is disconnected from the system.
3289 * GVolumeMonitor::drive-eject-button:
3290 * @volume_monitor: The volume monitor emitting the signal.
3291 * @drive: the drive where the eject button was pressed
3293 * Emitted when the eject button is pressed on @drive.
3300 * GVolumeMonitor::drive-stop-button:
3301 * @volume_monitor: The volume monitor emitting the signal.
3302 * @drive: the drive where the stop button was pressed
3304 * Emitted when the stop button is pressed on @drive.
3311 * GVolumeMonitor::mount-added:
3312 * @volume_monitor: The volume monitor emitting the signal.
3313 * @mount: a #GMount that was added.
3315 * Emitted when a mount is added.
3320 * GVolumeMonitor::mount-changed:
3321 * @volume_monitor: The volume monitor emitting the signal.
3322 * @mount: a #GMount that changed.
3324 * Emitted when a mount changes.
3329 * GVolumeMonitor::mount-pre-unmount:
3330 * @volume_monitor: The volume monitor emitting the signal.
3331 * @mount: a #GMount that is being unmounted.
3333 * Emitted when a mount is about to be removed.
3338 * GVolumeMonitor::mount-removed:
3339 * @volume_monitor: The volume monitor emitting the signal.
3340 * @mount: a #GMount that was removed.
3342 * Emitted when a mount is removed.
3347 * GVolumeMonitor::volume-added:
3348 * @volume_monitor: The volume monitor emitting the signal.
3349 * @volume: a #GVolume that was added.
3351 * Emitted when a mountable volume is added to the system.
3356 * GVolumeMonitor::volume-changed:
3357 * @volume_monitor: The volume monitor emitting the signal.
3358 * @volume: a #GVolume that changed.
3360 * Emitted when mountable volume is changed.
3365 * GVolumeMonitor::volume-removed:
3366 * @volume_monitor: The volume monitor emitting the signal.
3367 * @volume: a #GVolume that was removed.
3369 * Emitted when a mountable volume is removed from the system.
3374 * GWin32InputStream:close-handle:
3376 * Whether to close the file handle when the stream is closed.
3383 * GWin32InputStream:handle:
3385 * The handle that the stream reads from.
3392 * GWin32OutputStream:close-handle:
3394 * Whether to close the file handle when the stream is closed.
3401 * GWin32OutputStream:handle:
3403 * The file handle that the stream writes to.
3412 * Zlib decompression
3417 * GZlibCompressor:file-info:
3419 * If set to a non-%NULL #GFileInfo object, and #GZlibCompressor:format is
3420 * %G_ZLIB_COMPRESSOR_FORMAT_GZIP, the compressor will write the file name
3421 * and modification time from the file info to the GZIP header.
3428 * GZlibDecompressor:
3430 * Zlib decompression
3435 * GZlibDecompressor:file-info:
3437 * A #GFileInfo containing the information found in the GZIP header
3438 * of the data stream processed, or %NULL if the header was not yet
3439 * fully processed, is not present at all, or the compressor's
3440 * #GZlibDecompressor:format property is not %G_ZLIB_COMPRESSOR_FORMAT_GZIP.
3447 * G_TLS_DATABASE_PURPOSE_AUTHENTICATE_CLIENT:
3449 * The purpose used to verify the client certificate in a TLS connection.
3450 * Used by TLS servers.
3455 * G_TLS_DATABASE_PURPOSE_AUTHENTICATE_SERVER:
3457 * The purpose used to verify the server certificate in a TLS connection. This
3458 * is the most common purpose in use. Used by TLS clients.
3463 * G_TYPE_SETTINGS_SCHEMA:
3465 * A boxed #GType corresponding to #GSettingsSchema.
3472 * G_TYPE_SETTINGS_SCHEMA_SOURCE:
3474 * A boxed #GType corresponding to #GSettingsSchemaSource.
3481 * SECTION:_GFreedesktopDBus
3482 * @title: _GFreedesktopDBus
3483 * @short_description: Generated C code for the org.freedesktop.DBus D-Bus interface
3485 * 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.
3490 * SECTION:extensionpoints
3491 * @short_description: Extension Points
3493 * @see_also: [Extending GIO][extending-gio]
3495 * #GIOExtensionPoint provides a mechanism for modules to extend the
3496 * functionality of the library or application that loaded it in an
3497 * organized fashion.
3499 * An extension point is identified by a name, and it may optionally
3500 * require that any implementation must be of a certain type (or derived
3501 * thereof). Use g_io_extension_point_register() to register an
3502 * extension point, and g_io_extension_point_set_required_type() to
3503 * set a required type.
3505 * A module can implement an extension point by specifying the #GType
3506 * that implements the functionality. Additionally, each implementation
3507 * of an extension point has a name, and a priority. Use
3508 * g_io_extension_point_implement() to implement an extension point.
3510 * |[<!-- language="C" -->
3511 * GIOExtensionPoint *ep;
3513 * // Register an extension point
3514 * ep = g_io_extension_point_register ("my-extension-point");
3515 * g_io_extension_point_set_required_type (ep, MY_TYPE_EXAMPLE);
3518 * |[<!-- language="C" -->
3519 * // Implement an extension point
3520 * G_DEFINE_TYPE (MyExampleImpl, my_example_impl, MY_TYPE_EXAMPLE);
3521 * g_io_extension_point_implement ("my-extension-point",
3522 * my_example_impl_get_type (),
3527 * It is up to the code that registered the extension point how
3528 * it uses the implementations that have been associated with it.
3529 * Depending on the use case, it may use all implementations, or
3530 * only the one with the highest priority, or pick a specific
3533 * To avoid opening all modules just to find out what extension
3534 * points they implement, GIO makes use of a caching mechanism,
3535 * see [gio-querymodules][gio-querymodules].
3536 * You are expected to run this command after installing a
3539 * The `GIO_EXTRA_MODULES` environment variable can be used to
3540 * specify additional directories to automatically load modules
3541 * from. This environment variable has the same syntax as the
3542 * `PATH`. If two modules have the same base name in different
3543 * directories, then the latter one will be ignored. If additional
3544 * directories are specified GIO will load modules from the built-in
3552 * @short_description: An action interface
3553 * @include: gio/gio.h
3555 * #GAction represents a single named action.
3557 * The main interface to an action is that it can be activated with
3558 * g_action_activate(). This results in the 'activate' signal being
3559 * emitted. An activation has a #GVariant parameter (which may be
3560 * %NULL). The correct type for the parameter is determined by a static
3561 * parameter type (which is given at construction time).
3563 * An action may optionally have a state, in which case the state may be
3564 * set with g_action_change_state(). This call takes a #GVariant. The
3565 * correct type for the state is determined by a static state type
3566 * (which is given at construction time).
3568 * The state may have a hint associated with it, specifying its valid
3571 * #GAction is merely the interface to the concept of an action, as
3572 * described above. Various implementations of actions exist, including
3575 * In all cases, the implementing class is responsible for storing the
3576 * name of the action, the parameter type, the enabled state, the
3577 * optional state type and the state and emitting the appropriate
3578 * signals when these change. The implementor responsible for filtering
3579 * calls to g_action_activate() and g_action_change_state() for type
3580 * safety and for the state being enabled.
3582 * Probably the only useful thing to do with a #GAction is to put it
3583 * inside of a #GSimpleActionGroup.
3588 * SECTION:gactiongroup
3589 * @title: GActionGroup
3590 * @short_description: A group of actions
3591 * @include: gio/gio.h
3592 * @see_also: #GAction
3594 * #GActionGroup represents a group of actions. Actions can be used to
3595 * expose functionality in a structured way, either from one part of a
3596 * program to another, or to the outside world. Action groups are often
3597 * used together with a #GMenuModel that provides additional
3598 * representation data for displaying the actions to the user, e.g. in
3601 * The main way to interact with the actions in a GActionGroup is to
3602 * activate them with g_action_group_activate_action(). Activating an
3603 * action may require a #GVariant parameter. The required type of the
3604 * parameter can be inquired with g_action_group_get_action_parameter_type().
3605 * Actions may be disabled, see g_action_group_get_action_enabled().
3606 * Activating a disabled action has no effect.
3608 * Actions may optionally have a state in the form of a #GVariant. The
3609 * current state of an action can be inquired with
3610 * g_action_group_get_action_state(). Activating a stateful action may
3611 * change its state, but it is also possible to set the state by calling
3612 * g_action_group_change_action_state().
3614 * As typical example, consider a text editing application which has an
3615 * option to change the current font to 'bold'. A good way to represent
3616 * this would be a stateful action, with a boolean state. Activating the
3617 * action would toggle the state.
3619 * Each action in the group has a unique name (which is a string). All
3620 * method calls, except g_action_group_list_actions() take the name of
3621 * an action as an argument.
3623 * The #GActionGroup API is meant to be the 'public' API to the action
3624 * group. The calls here are exactly the interaction that 'external
3625 * forces' (eg: UI, incoming D-Bus messages, etc.) are supposed to have
3626 * with actions. 'Internal' APIs (ie: ones meant only to be accessed by
3627 * the action group implementation) are found on subclasses. This is
3628 * why you will find - for example - g_action_group_get_action_enabled()
3629 * but not an equivalent set() call.
3631 * Signals are emitted on the action group in response to state changes
3632 * on individual actions.
3634 * Implementations of #GActionGroup should provide implementations for
3635 * the virtual functions g_action_group_list_actions() and
3636 * g_action_group_query_action(). The other virtual functions should
3637 * not be implemented - their "wrappers" are actually implemented with
3638 * calls to g_action_group_query_action().
3643 * SECTION:gactiongroupexporter
3644 * @title: GActionGroup exporter
3645 * @include: gio/gio.h
3646 * @short_description: Export GActionGroups on D-Bus
3647 * @see_also: #GActionGroup, #GDBusActionGroup
3649 * These functions support exporting a #GActionGroup on D-Bus.
3650 * The D-Bus interface that is used is a private implementation
3653 * To access an exported #GActionGroup remotely, use
3654 * g_dbus_action_group_get() to obtain a #GDBusActionGroup.
3659 * SECTION:gactionmap
3660 * @title: GActionMap
3661 * @include: gio/gio.h
3662 * @short_description: Interface for action containers
3664 * The GActionMap interface is implemented by #GActionGroup
3665 * implementations that operate by containing a number of
3666 * named #GAction instances, such as #GSimpleActionGroup.
3668 * One useful application of this interface is to map the
3669 * names of actions from various action groups to unique,
3670 * prefixed names (e.g. by prepending "app." or "win.").
3671 * This is the motivation for the 'Map' part of the interface
3680 * @short_description: Application information and launch contexts
3681 * @include: gio/gio.h
3682 * @see_also: #GAppInfoMonitor
3684 * #GAppInfo and #GAppLaunchContext are used for describing and launching
3685 * applications installed on the system.
3687 * As of GLib 2.20, URIs will always be converted to POSIX paths
3688 * (using g_file_get_path()) when using g_app_info_launch() even if
3689 * the application requested an URI and not a POSIX path. For example
3690 * for an desktop-file based application with Exec key `totem
3691 * %U` and a single URI, `sftp://foo/file.avi`, then
3692 * `/home/user/.gvfs/sftp on foo/file.avi` will be passed. This will
3693 * only work if a set of suitable GIO extensions (such as gvfs 2.26
3694 * compiled with FUSE support), is available and operational; if this
3695 * is not the case, the URI will be passed unmodified to the application.
3696 * Some URIs, such as `mailto:`, of course cannot be mapped to a POSIX
3697 * path (in gvfs there's no FUSE mount for it); such URIs will be
3698 * passed unmodified to the application.
3700 * Specifically for gvfs 2.26 and later, the POSIX URI will be mapped
3701 * back to the GIO URI in the #GFile constructors (since gvfs
3702 * implements the #GVfs extension point). As such, if the application
3703 * needs to examine the URI, it needs to use g_file_get_uri() or
3704 * similar on #GFile. In other words, an application cannot assume
3705 * that the URI passed to e.g. g_file_new_for_commandline_arg() is
3706 * equal to the result of g_file_get_uri(). The following snippet
3713 * file = g_file_new_for_commandline_arg (uri_from_commandline);
3715 * uri = g_file_get_uri (file);
3716 * strcmp (uri, uri_from_commandline) == 0;
3719 * if (g_file_has_uri_scheme (file, "cdda"))
3721 * // do something special with uri
3723 * g_object_unref (file);
3726 * This code will work when both `cdda://sr0/Track 1.wav` and
3727 * `/home/user/.gvfs/cdda on sr0/Track 1.wav` is passed to the
3728 * application. It should be noted that it's generally not safe
3729 * for applications to rely on the format of a particular URIs.
3730 * Different launcher applications (e.g. file managers) may have
3731 * different ideas of what a given URI means.
3736 * SECTION:gappinfomonitor
3737 * @short_description: Monitor application information for changes
3739 * #GAppInfoMonitor is a very simple object used for monitoring the app
3740 * info database for changes (ie: newly installed or removed
3743 * Call g_app_info_monitor_get() to get a #GAppInfoMonitor and connect
3744 * to the "changed" signal.
3746 * In the usual case, applications should try to make note of the change
3747 * (doing things like invalidating caches) but not act on it. In
3748 * particular, applications should avoid making calls to #GAppInfo APIs
3749 * in response to the change signal, deferring these until the time that
3750 * the data is actually required. The exception to this case is when
3751 * application information is actually being displayed on the screen
3752 * (eg: during a search or when the list of all applications is shown).
3753 * The reason for this is that changes to the list of installed
3754 * applications often come in groups (like during system updates) and
3755 * rescanning the list on every change is pointless and expensive.
3762 * SECTION:gapplication
3763 * @title: GApplication
3764 * @short_description: Core application class
3765 * @include: gio/gio.h
3767 * A #GApplication is the foundation of an application. It wraps some
3768 * low-level platform-specific services and is intended to act as the
3769 * foundation for higher-level application classes such as
3770 * #GtkApplication or #MxApplication. In general, you should not use
3771 * this class outside of a higher level framework.
3773 * GApplication provides convenient life cycle management by maintaining
3774 * a "use count" for the primary application instance. The use count can
3775 * be changed using g_application_hold() and g_application_release(). If
3776 * it drops to zero, the application exits. Higher-level classes such as
3777 * #GtkApplication employ the use count to ensure that the application
3778 * stays alive as long as it has any opened windows.
3780 * Another feature that GApplication (optionally) provides is process
3781 * uniqueness. Applications can make use of this functionality by
3782 * providing a unique application ID. If given, only one application
3783 * with this ID can be running at a time per session. The session
3784 * concept is platform-dependent, but corresponds roughly to a graphical
3785 * desktop login. When your application is launched again, its
3786 * arguments are passed through platform communication to the already
3787 * running program. The already running instance of the program is
3788 * called the "primary instance"; for non-unique applications this is
3789 * the always the current instance. On Linux, the D-Bus session bus
3790 * is used for communication.
3792 * The use of #GApplication differs from some other commonly-used
3793 * uniqueness libraries (such as libunique) in important ways. The
3794 * application is not expected to manually register itself and check
3795 * if it is the primary instance. Instead, the main() function of a
3796 * #GApplication should do very little more than instantiating the
3797 * application instance, possibly connecting signal handlers, then
3798 * calling g_application_run(). All checks for uniqueness are done
3799 * internally. If the application is the primary instance then the
3800 * startup signal is emitted and the mainloop runs. If the application
3801 * is not the primary instance then a signal is sent to the primary
3802 * instance and g_application_run() promptly returns. See the code
3805 * If used, the expected form of an application identifier is very close
3807 * [DBus bus name](http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-interface).
3808 * Examples include: "com.example.MyApp", "org.example.internal-apps.Calculator".
3809 * For details on valid application identifiers, see g_application_id_is_valid().
3811 * On Linux, the application identifier is claimed as a well-known bus name
3812 * on the user's session bus. This means that the uniqueness of your
3813 * application is scoped to the current session. It also means that your
3814 * application may provide additional services (through registration of other
3815 * object paths) at that bus name. The registration of these object paths
3816 * should be done with the shared GDBus session bus. Note that due to the
3817 * internal architecture of GDBus, method calls can be dispatched at any time
3818 * (even if a main loop is not running). For this reason, you must ensure that
3819 * any object paths that you wish to register are registered before #GApplication
3820 * attempts to acquire the bus name of your application (which happens in
3821 * g_application_register()). Unfortunately, this means that you cannot use
3822 * g_application_get_is_remote() to decide if you want to register object paths.
3824 * GApplication also implements the #GActionGroup and #GActionMap
3825 * interfaces and lets you easily export actions by adding them with
3826 * g_action_map_add_action(). When invoking an action by calling
3827 * g_action_group_activate_action() on the application, it is always
3828 * invoked in the primary instance. The actions are also exported on
3829 * the session bus, and GIO provides the #GDBusActionGroup wrapper to
3830 * conveniently access them remotely. GIO provides a #GDBusMenuModel wrapper
3831 * for remote access to exported #GMenuModels.
3833 * There is a number of different entry points into a GApplication:
3835 * - via 'Activate' (i.e. just starting the application)
3837 * - via 'Open' (i.e. opening some files)
3839 * - by handling a command-line
3841 * - via activating an action
3843 * The #GApplication::startup signal lets you handle the application
3844 * initialization for all of these in a single place.
3846 * Regardless of which of these entry points is used to start the
3847 * application, GApplication passes some "platform data from the
3848 * launching instance to the primary instance, in the form of a
3849 * #GVariant dictionary mapping strings to variants. To use platform
3850 * data, override the @before_emit or @after_emit virtual functions
3851 * in your #GApplication subclass. When dealing with
3852 * #GApplicationCommandLine objects, the platform data is
3853 * directly available via g_application_command_line_get_cwd(),
3854 * g_application_command_line_get_environ() and
3855 * g_application_command_line_get_platform_data().
3857 * As the name indicates, the platform data may vary depending on the
3858 * operating system, but it always includes the current directory (key
3859 * "cwd"), and optionally the environment (ie the set of environment
3860 * variables and their values) of the calling process (key "environ").
3861 * The environment is only added to the platform data if the
3862 * %G_APPLICATION_SEND_ENVIRONMENT flag is set. #GApplication subclasses
3863 * can add their own platform data by overriding the @add_platform_data
3864 * virtual function. For instance, #GtkApplication adds startup notification
3867 * To parse commandline arguments you may handle the
3868 * #GApplication::command-line signal or override the local_command_line()
3869 * vfunc, to parse them in either the primary instance or the local instance,
3872 * For an example of opening files with a GApplication, see
3873 * [gapplication-example-open.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-open.c).
3875 * For an example of using actions with GApplication, see
3876 * [gapplication-example-actions.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-actions.c).
3878 * For an example of using extra D-Bus hooks with GApplication, see
3879 * [gapplication-example-dbushooks.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-dbushooks.c).
3884 * SECTION:gapplicationcommandline
3885 * @title: GApplicationCommandLine
3886 * @short_description: A command-line invocation of an application
3887 * @include: gio/gio.h
3888 * @see_also: #GApplication
3890 * #GApplicationCommandLine represents a command-line invocation of
3891 * an application. It is created by #GApplication and emitted
3892 * in the #GApplication::command-line signal and virtual function.
3894 * The class contains the list of arguments that the program was invoked
3895 * with. It is also possible to query if the commandline invocation was
3896 * local (ie: the current process is running in direct response to the
3897 * invocation) or remote (ie: some other process forwarded the
3898 * commandline to this process).
3900 * The GApplicationCommandLine object can provide the @argc and @argv
3901 * parameters for use with the #GOptionContext command-line parsing API,
3902 * with the g_application_command_line_get_arguments() function. See
3903 * [gapplication-example-cmdline3.c][gapplication-example-cmdline3]
3906 * The exit status of the originally-invoked process may be set and
3907 * messages can be printed to stdout or stderr of that process. The
3908 * lifecycle of the originally-invoked process is tied to the lifecycle
3909 * of this object (ie: the process exits when the last reference is
3912 * The main use for #GApplicationCommandLine (and the
3913 * #GApplication::command-line signal) is 'Emacs server' like use cases:
3914 * You can set the `EDITOR` environment variable to have e.g. git use
3915 * your favourite editor to edit commit messages, and if you already
3916 * have an instance of the editor running, the editing will happen
3917 * in the running instance, instead of opening a new one. An important
3918 * aspect of this use case is that the process that gets started by git
3919 * does not return until the editing is done.
3921 * Normally, the commandline is completely handled in the
3922 * #GApplication::command-line handler. The launching instance exits
3923 * once the signal handler in the primary instance has returned, and
3924 * the return value of the signal handler becomes the exit status
3925 * of the launching instance.
3926 * |[<!-- language="C" -->
3928 * command_line (GApplication *application,
3929 * GApplicationCommandLine *cmdline)
3935 * argv = g_application_command_line_get_arguments (cmdline, &argc);
3937 * g_application_command_line_print (cmdline,
3938 * "This text is written back\n"
3939 * "to stdout of the caller\n");
3941 * for (i = 0; i < argc; i++)
3942 * g_print ("argument %d: %s\n", i, argv[i]);
3944 * g_strfreev (argv);
3949 * The complete example can be found here:
3950 * [gapplication-example-cmdline.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-cmdline.c)
3952 * In more complicated cases, the handling of the comandline can be
3953 * split between the launcher and the primary instance.
3954 * |[<!-- language="C" -->
3956 * test_local_cmdline (GApplication *application,
3957 * gchar ***arguments,
3958 * gint *exit_status)
3963 * argv = *arguments;
3968 * if (g_str_has_prefix (argv[i], "--local-"))
3970 * g_print ("handling argument %s locally\n", argv[i]);
3972 * for (j = i; argv[j]; j++)
3973 * argv[j] = argv[j + 1];
3977 * g_print ("not handling argument %s locally\n", argv[i]);
3988 * test_application_class_init (TestApplicationClass *class)
3990 * G_APPLICATION_CLASS (class)->local_command_line = test_local_cmdline;
3995 * In this example of split commandline handling, options that start
3996 * with `--local-` are handled locally, all other options are passed
3997 * to the #GApplication::command-line handler which runs in the primary
4000 * The complete example can be found here:
4001 * [gapplication-example-cmdline2.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-cmdline2.c)
4003 * If handling the commandline requires a lot of work, it may
4004 * be better to defer it.
4005 * |[<!-- language="C" -->
4007 * my_cmdline_handler (gpointer data)
4009 * GApplicationCommandLine *cmdline = data;
4011 * // do the heavy lifting in an idle
4013 * g_application_command_line_set_exit_status (cmdline, 0);
4014 * g_object_unref (cmdline); // this releases the application
4016 * return G_SOURCE_REMOVE;
4020 * command_line (GApplication *application,
4021 * GApplicationCommandLine *cmdline)
4023 * // keep the application running until we are done with this commandline
4024 * g_application_hold (application);
4026 * g_object_set_data_full (G_OBJECT (cmdline),
4027 * "application", application,
4028 * (GDestroyNotify)g_application_release);
4030 * g_object_ref (cmdline);
4031 * g_idle_add (my_cmdline_handler, cmdline);
4036 * In this example the commandline is not completely handled before
4037 * the #GApplication::command-line handler returns. Instead, we keep
4038 * a reference to the #GApplicationCommandLine object and handle it
4039 * later (in this example, in an idle). Note that it is necessary to
4040 * hold the application until you are done with the commandline.
4042 * The complete example can be found here:
4043 * [gapplication-example-cmdline3.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-cmdline3.c)
4048 * SECTION:gasyncinitable
4049 * @short_description: Asynchronously failable object initialization interface
4050 * @include: gio/gio.h
4051 * @see_also: #GInitable
4053 * This is the asynchronous version of #GInitable; it behaves the same
4054 * in all ways except that initialization is asynchronous. For more details
4055 * see the descriptions on #GInitable.
4057 * A class may implement both the #GInitable and #GAsyncInitable interfaces.
4059 * Users of objects implementing this are not intended to use the interface
4060 * method directly; instead it will be used automatically in various ways.
4061 * For C applications you generally just call g_async_initable_new_async()
4062 * directly, or indirectly via a foo_thing_new_async() wrapper. This will call
4063 * g_async_initable_init_async() under the cover, calling back with %NULL and
4064 * a set %GError on failure.
4066 * A typical implementation might look something like this:
4068 * |[<!-- language="C" -->
4076 * _foo_ready_cb (Foo *self)
4080 * self->priv->state = INITIALIZED;
4082 * for (l = self->priv->init_results; l != NULL; l = l->next)
4084 * GTask *task = l->data;
4086 * if (self->priv->success)
4087 * g_task_return_boolean (task, TRUE);
4089 * g_task_return_new_error (task, ...);
4090 * g_object_unref (task);
4093 * g_list_free (self->priv->init_results);
4094 * self->priv->init_results = NULL;
4098 * foo_init_async (GAsyncInitable *initable,
4100 * GCancellable *cancellable,
4101 * GAsyncReadyCallback callback,
4102 * gpointer user_data)
4104 * Foo *self = FOO (initable);
4107 * task = g_task_new (initable, cancellable, callback, user_data);
4109 * switch (self->priv->state)
4111 * case NOT_INITIALIZED:
4112 * _foo_get_ready (self);
4113 * self->priv->init_results = g_list_append (self->priv->init_results,
4115 * self->priv->state = INITIALIZING;
4117 * case INITIALIZING:
4118 * self->priv->init_results = g_list_append (self->priv->init_results,
4122 * if (!self->priv->success)
4123 * g_task_return_new_error (task, ...);
4125 * g_task_return_boolean (task, TRUE);
4126 * g_object_unref (task);
4132 * foo_init_finish (GAsyncInitable *initable,
4133 * GAsyncResult *result,
4136 * g_return_val_if_fail (g_task_is_valid (result, initable), FALSE);
4138 * return g_task_propagate_boolean (G_TASK (result), error);
4142 * foo_async_initable_iface_init (gpointer g_iface,
4145 * GAsyncInitableIface *iface = g_iface;
4147 * iface->init_async = foo_init_async;
4148 * iface->init_finish = foo_init_finish;
4155 * SECTION:gasyncresult
4156 * @short_description: Asynchronous Function Results
4157 * @include: gio/gio.h
4160 * Provides a base class for implementing asynchronous function results.
4162 * Asynchronous operations are broken up into two separate operations
4163 * which are chained together by a #GAsyncReadyCallback. To begin
4164 * an asynchronous operation, provide a #GAsyncReadyCallback to the
4165 * asynchronous function. This callback will be triggered when the
4166 * operation has completed, and will be passed a #GAsyncResult instance
4167 * filled with the details of the operation's success or failure, the
4168 * object the asynchronous function was started for and any error codes
4169 * returned. The asynchronous callback function is then expected to call
4170 * the corresponding "_finish()" function, passing the object the
4171 * function was called for, the #GAsyncResult instance, and (optionally)
4172 * an @error to grab any error conditions that may have occurred.
4174 * The "_finish()" function for an operation takes the generic result
4175 * (of type #GAsyncResult) and returns the specific result that the
4176 * operation in question yields (e.g. a #GFileEnumerator for a
4177 * "enumerate children" operation). If the result or error status of the
4178 * operation is not needed, there is no need to call the "_finish()"
4179 * function; GIO will take care of cleaning up the result and error
4180 * information after the #GAsyncReadyCallback returns. You can pass
4181 * %NULL for the #GAsyncReadyCallback if you don't need to take any
4182 * action at all after the operation completes. Applications may also
4183 * take a reference to the #GAsyncResult and call "_finish()" later;
4184 * however, the "_finish()" function may be called at most once.
4186 * Example of a typical asynchronous operation flow:
4187 * |[<!-- language="C" -->
4188 * void _theoretical_frobnitz_async (Theoretical *t,
4190 * GAsyncReadyCallback cb,
4193 * gboolean _theoretical_frobnitz_finish (Theoretical *t,
4194 * GAsyncResult *res,
4198 * frobnitz_result_func (GObject *source_object,
4199 * GAsyncResult *res,
4200 * gpointer user_data)
4202 * gboolean success = FALSE;
4204 * success = _theoretical_frobnitz_finish (source_object, res, NULL);
4207 * g_printf ("Hurray!\n");
4209 * g_printf ("Uh oh!\n");
4215 * int main (int argc, void *argv[])
4219 * _theoretical_frobnitz_async (theoretical_data,
4221 * frobnitz_result_func,
4228 * The callback for an asynchronous operation is called only once, and is
4229 * always called, even in the case of a cancelled operation. On cancellation
4230 * the result is a %G_IO_ERROR_CANCELLED error.
4232 * ## I/O Priority # {#io-priority}
4234 * Many I/O-related asynchronous operations have a priority parameter,
4235 * which is used in certain cases to determine the order in which
4236 * operations are executed. They are not used to determine system-wide
4237 * I/O scheduling. Priorities are integers, with lower numbers indicating
4238 * higher priority. It is recommended to choose priorities between
4239 * %G_PRIORITY_LOW and %G_PRIORITY_HIGH, with %G_PRIORITY_DEFAULT
4245 * SECTION:gbufferedinputstream
4246 * @short_description: Buffered Input Stream
4247 * @include: gio/gio.h
4248 * @see_also: #GFilterInputStream, #GInputStream
4250 * Buffered input stream implements #GFilterInputStream and provides
4251 * for buffered reads.
4253 * By default, #GBufferedInputStream's buffer size is set at 4 kilobytes.
4255 * To create a buffered input stream, use g_buffered_input_stream_new(),
4256 * or g_buffered_input_stream_new_sized() to specify the buffer's size at
4259 * To get the size of a buffer within a buffered input stream, use
4260 * g_buffered_input_stream_get_buffer_size(). To change the size of a
4261 * buffered input stream's buffer, use
4262 * g_buffered_input_stream_set_buffer_size(). Note that the buffer's size
4263 * cannot be reduced below the size of the data within the buffer.
4268 * SECTION:gbufferedoutputstream
4269 * @short_description: Buffered Output Stream
4270 * @include: gio/gio.h
4271 * @see_also: #GFilterOutputStream, #GOutputStream
4273 * Buffered output stream implements #GFilterOutputStream and provides
4274 * for buffered writes.
4276 * By default, #GBufferedOutputStream's buffer size is set at 4 kilobytes.
4278 * To create a buffered output stream, use g_buffered_output_stream_new(),
4279 * or g_buffered_output_stream_new_sized() to specify the buffer's size
4282 * To get the size of a buffer within a buffered input stream, use
4283 * g_buffered_output_stream_get_buffer_size(). To change the size of a
4284 * buffered output stream's buffer, use
4285 * g_buffered_output_stream_set_buffer_size(). Note that the buffer's
4286 * size cannot be reduced below the size of the data within the buffer.
4291 * SECTION:gbytesicon
4292 * @short_description: An icon stored in memory as a GBytes
4293 * @include: gio/gio.h
4294 * @see_also: #GIcon, #GLoadableIcon, #GBytes
4296 * #GBytesIcon specifies an image held in memory in a common format (usually
4297 * png) to be used as icon.
4304 * SECTION:gcancellable
4305 * @short_description: Thread-safe Operation Cancellation Stack
4306 * @include: gio/gio.h
4308 * GCancellable is a thread-safe operation cancellation stack used
4309 * throughout GIO to allow for cancellation of synchronous and
4310 * asynchronous operations.
4315 * SECTION:gcharsetconverter
4316 * @short_description: Convert between charsets
4317 * @include: gio/gio.h
4319 * #GCharsetConverter is an implementation of #GConverter based on
4325 * SECTION:gcontenttype
4326 * @short_description: Platform-specific content typing
4327 * @include: gio/gio.h
4329 * A content type is a platform specific string that defines the type
4330 * of a file. On UNIX it is a
4331 * [mime type](http://www.wikipedia.org/wiki/Internet_media_type)
4332 * like "text/plain" or "image/png".
4333 * On Win32 it is an extension string like ".doc", ".txt" or a perceived
4334 * string like "audio". Such strings can be looked up in the registry at
4335 * HKEY_CLASSES_ROOT.
4340 * SECTION:gconverter
4341 * @short_description: Data conversion interface
4342 * @include: gio/gio.h
4343 * @see_also: #GInputStream, #GOutputStream
4345 * #GConverter is implemented by objects that convert
4346 * binary data in various ways. The conversion can be
4347 * stateful and may fail at any place.
4349 * Some example conversions are: character set conversion,
4350 * compression, decompression and regular expression
4358 * SECTION:gconverterinputstream
4359 * @short_description: Converter Input Stream
4360 * @include: gio/gio.h
4361 * @see_also: #GInputStream, #GConverter
4363 * Converter input stream implements #GInputStream and allows
4364 * conversion of data of various types during reading.
4366 * As of GLib 2.34, #GConverterInputStream implements
4367 * #GPollableInputStream.
4372 * SECTION:gconverteroutputstream
4373 * @short_description: Converter Output Stream
4374 * @include: gio/gio.h
4375 * @see_also: #GOutputStream, #GConverter
4377 * Converter output stream implements #GOutputStream and allows
4378 * conversion of data of various types during reading.
4380 * As of GLib 2.34, #GConverterOutputStream implements
4381 * #GPollableOutputStream.
4386 * SECTION:gcredentials
4387 * @short_description: An object containing credentials
4388 * @include: gio/gio.h
4390 * The #GCredentials type is a reference-counted wrapper for native
4391 * credentials. This information is typically used for identifying,
4392 * authenticating and authorizing other processes.
4394 * Some operating systems supports looking up the credentials of the
4395 * remote peer of a communication endpoint - see e.g.
4396 * g_socket_get_credentials().
4398 * Some operating systems supports securely sending and receiving
4399 * credentials over a Unix Domain Socket, see
4400 * #GUnixCredentialsMessage, g_unix_connection_send_credentials() and
4401 * g_unix_connection_receive_credentials() for details.
4403 * On Linux, the native credential type is a struct ucred - see the
4404 * unix(7) man page for details. This corresponds to
4405 * %G_CREDENTIALS_TYPE_LINUX_UCRED.
4407 * On FreeBSD, Debian GNU/kFreeBSD, and GNU/Hurd, the native
4408 * credential type is a struct cmsgcred. This corresponds
4409 * to %G_CREDENTIALS_TYPE_FREEBSD_CMSGCRED.
4411 * On NetBSD, the native credential type is a struct unpcbid.
4412 * This corresponds to %G_CREDENTIALS_TYPE_NETBSD_UNPCBID.
4414 * On OpenBSD, the native credential type is a struct sockpeercred.
4415 * This corresponds to %G_CREDENTIALS_TYPE_OPENBSD_SOCKPEERCRED.
4417 * On Solaris (including OpenSolaris and its derivatives), the native
4418 * credential type is a ucred_t. This corresponds to
4419 * %G_CREDENTIALS_TYPE_SOLARIS_UCRED.
4424 * SECTION:gdatainputstream
4425 * @short_description: Data Input Stream
4426 * @include: gio/gio.h
4427 * @see_also: #GInputStream
4429 * Data input stream implements #GInputStream and includes functions for
4430 * reading structured data directly from a binary input stream.
4435 * SECTION:gdataoutputstream
4436 * @short_description: Data Output Stream
4437 * @include: gio/gio.h
4438 * @see_also: #GOutputStream
4440 * Data output stream implements #GOutputStream and includes functions for
4441 * writing data directly to an output stream.
4446 * SECTION:gdbusactiongroup
4447 * @title: GDBusActionGroup
4448 * @short_description: A D-Bus GActionGroup implementation
4449 * @include: gio/gio.h
4450 * @see_also: [GActionGroup exporter][gio-GActionGroup-exporter]
4452 * #GDBusActionGroup is an implementation of the #GActionGroup
4453 * interface that can be used as a proxy for an action group
4454 * that is exported over D-Bus with g_dbus_connection_export_action_group().
4459 * SECTION:gdbusaddress
4460 * @title: D-Bus Addresses
4461 * @short_description: D-Bus connection endpoints
4462 * @include: gio/gio.h
4464 * Routines for working with D-Bus addresses. A D-Bus address is a string
4465 * like "unix:tmpdir=/tmp/my-app-name". The exact format of addresses
4466 * is explained in detail in the [D-Bus specification](http://dbus.freedesktop.org/doc/dbus-specification.html\#addresses).
4471 * SECTION:gdbusauthobserver
4472 * @short_description: Object used for authenticating connections
4473 * @include: gio/gio.h
4475 * The #GDBusAuthObserver type provides a mechanism for participating
4476 * in how a #GDBusServer (or a #GDBusConnection) authenticates remote
4477 * peers. Simply instantiate a #GDBusAuthObserver and connect to the
4478 * signals you are interested in. Note that new signals may be added
4481 * ## Controlling Authentication # {#auth-observer}
4483 * For example, if you only want to allow D-Bus connections from
4484 * processes owned by the same uid as the server, you would use a
4485 * signal handler like the following:
4487 * |[<!-- language="C" -->
4489 * on_authorize_authenticated_peer (GDBusAuthObserver *observer,
4490 * GIOStream *stream,
4491 * GCredentials *credentials,
4492 * gpointer user_data)
4494 * gboolean authorized;
4496 * authorized = FALSE;
4497 * if (credentials != NULL)
4499 * GCredentials *own_credentials;
4500 * own_credentials = g_credentials_new ();
4501 * if (g_credentials_is_same_user (credentials, own_credentials, NULL))
4502 * authorized = TRUE;
4503 * g_object_unref (own_credentials);
4506 * return authorized;
4513 * SECTION:gdbusconnection
4514 * @short_description: D-Bus Connections
4515 * @include: gio/gio.h
4517 * The #GDBusConnection type is used for D-Bus connections to remote
4518 * peers such as a message buses. It is a low-level API that offers a
4519 * lot of flexibility. For instance, it lets you establish a connection
4520 * over any transport that can by represented as an #GIOStream.
4522 * This class is rarely used directly in D-Bus clients. If you are writing
4523 * a D-Bus client, it is often easier to use the g_bus_own_name(),
4524 * g_bus_watch_name() or g_dbus_proxy_new_for_bus() APIs.
4526 * As an exception to the usual GLib rule that a particular object must not
4527 * be used by two threads at the same time, #GDBusConnection's methods may be
4528 * called from any thread. This is so that g_bus_get() and g_bus_get_sync()
4529 * can safely return the same #GDBusConnection when called from any thread.
4531 * Most of the ways to obtain a #GDBusConnection automatically initialize it
4532 * (i.e. connect to D-Bus): for instance, g_dbus_connection_new() and
4533 * g_bus_get(), and the synchronous versions of those methods, give you an
4534 * initialized connection. Language bindings for GIO should use
4535 * g_initable_new() or g_async_initable_new_async(), which also initialize the
4538 * If you construct an uninitialized #GDBusConnection, such as via
4539 * g_object_new(), you must initialize it via g_initable_init() or
4540 * g_async_initable_init_async() before using its methods or properties.
4541 * Calling methods or accessing properties on a #GDBusConnection that has not
4542 * completed initialization successfully is considered to be invalid, and leads
4543 * to undefined behaviour. In particular, if initialization fails with a
4544 * #GError, the only valid thing you can do with that #GDBusConnection is to
4545 * free it with g_object_unref().
4547 * ## An example D-Bus server # {#gdbus-server}
4549 * Here is an example for a D-Bus server:
4550 * [gdbus-example-server.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-server.c)
4552 * ## An example for exporting a subtree # {#gdbus-subtree-server}
4554 * Here is an example for exporting a subtree:
4555 * [gdbus-example-subtree.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-subtree.c)
4557 * ## An example for file descriptor passing # {#gdbus-unix-fd-client}
4559 * Here is an example for passing UNIX file descriptors:
4560 * [gdbus-unix-fd-client.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-unix-fd-client.c)
4562 * ## An example for exporting a GObject # {#gdbus-export}
4564 * Here is an example for exporting a #GObject:
4565 * [gdbus-example-export.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-export.c)
4570 * SECTION:gdbuserror
4571 * @title: GDBusError
4572 * @short_description: Mapping D-Bus errors to and from GError
4573 * @include: gio/gio.h
4575 * All facilities that return errors from remote methods (such as
4576 * g_dbus_connection_call_sync()) use #GError to represent both D-Bus
4577 * errors (e.g. errors returned from the other peer) and locally
4578 * in-process generated errors.
4580 * To check if a returned #GError is an error from a remote peer, use
4581 * g_dbus_error_is_remote_error(). To get the actual D-Bus error name,
4582 * use g_dbus_error_get_remote_error(). Before presenting an error,
4583 * always use g_dbus_error_strip_remote_error().
4585 * In addition, facilities used to return errors to a remote peer also
4586 * use #GError. See g_dbus_method_invocation_return_error() for
4587 * discussion about how the D-Bus error name is set.
4589 * Applications can associate a #GError error domain with a set of D-Bus errors in order to
4590 * automatically map from D-Bus errors to #GError and back. This
4591 * is typically done in the function returning the #GQuark for the
4593 * |[<!-- language="C" -->
4594 * // foo-bar-error.h:
4596 * #define FOO_BAR_ERROR (foo_bar_error_quark ())
4597 * GQuark foo_bar_error_quark (void);
4601 * FOO_BAR_ERROR_FAILED,
4602 * FOO_BAR_ERROR_ANOTHER_ERROR,
4603 * FOO_BAR_ERROR_SOME_THIRD_ERROR,
4604 * FOO_BAR_N_ERRORS / *< skip >* /
4607 * // foo-bar-error.c:
4609 * static const GDBusErrorEntry foo_bar_error_entries[] =
4611 * {FOO_BAR_ERROR_FAILED, "org.project.Foo.Bar.Error.Failed"},
4612 * {FOO_BAR_ERROR_ANOTHER_ERROR, "org.project.Foo.Bar.Error.AnotherError"},
4613 * {FOO_BAR_ERROR_SOME_THIRD_ERROR, "org.project.Foo.Bar.Error.SomeThirdError"},
4616 * // Ensure that every error code has an associated D-Bus error name
4617 * G_STATIC_ASSERT (G_N_ELEMENTS (foo_bar_error_entries) == FOO_BAR_N_ERRORS);
4620 * foo_bar_error_quark (void)
4622 * static volatile gsize quark_volatile = 0;
4623 * g_dbus_error_register_error_domain ("foo-bar-error-quark",
4625 * foo_bar_error_entries,
4626 * G_N_ELEMENTS (foo_bar_error_entries));
4627 * return (GQuark) quark_volatile;
4630 * With this setup, a D-Bus peer can transparently pass e.g. %FOO_BAR_ERROR_ANOTHER_ERROR and
4631 * other peers will see the D-Bus error name org.project.Foo.Bar.Error.AnotherError.
4633 * If the other peer is using GDBus, and has registered the association with
4634 * g_dbus_error_register_error_domain() in advance (e.g. by invoking the %FOO_BAR_ERROR quark
4635 * generation itself in the previous example) the peer will see also %FOO_BAR_ERROR_ANOTHER_ERROR instead
4636 * of %G_IO_ERROR_DBUS_ERROR. Note that GDBus clients can still recover
4637 * org.project.Foo.Bar.Error.AnotherError using g_dbus_error_get_remote_error().
4639 * Note that errors in the %G_DBUS_ERROR error domain is intended only
4640 * for returning errors from a remote message bus process. Errors
4641 * generated locally in-process by e.g. #GDBusConnection is from the
4642 * %G_IO_ERROR domain.
4647 * SECTION:gdbusinterface
4648 * @short_description: Base type for D-Bus interfaces
4649 * @include: gio/gio.h
4651 * The #GDBusInterface type is the base type for D-Bus interfaces both
4652 * on the service side (see #GDBusInterfaceSkeleton) and client side
4653 * (see #GDBusProxy).
4658 * SECTION:gdbusinterfaceskeleton
4659 * @short_description: Service-side D-Bus interface
4660 * @include: gio/gio.h
4662 * Abstract base class for D-Bus interfaces on the service side.
4667 * SECTION:gdbusintrospection
4668 * @title: D-Bus Introspection Data
4669 * @short_description: Node and interface description data structures
4670 * @include: gio/gio.h
4672 * Various data structures and convenience routines to parse and
4673 * generate D-Bus introspection XML. Introspection information is
4674 * used when registering objects with g_dbus_connection_register_object().
4676 * The format of D-Bus introspection XML is specified in the
4677 * [D-Bus specification](http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format)
4682 * SECTION:gdbusmenumodel
4683 * @title: GDBusMenuModel
4684 * @short_description: A D-Bus GMenuModel implementation
4685 * @include: gio/gio.h
4686 * @see_also: [GMenuModel Exporter][gio-GMenuModel-exporter]
4688 * #GDBusMenuModel is an implementation of #GMenuModel that can be used
4689 * as a proxy for a menu model that is exported over D-Bus with
4690 * g_dbus_connection_export_menu_model().
4695 * SECTION:gdbusmessage
4696 * @short_description: D-Bus Message
4697 * @include: gio/gio.h
4699 * A type for representing D-Bus messages that can be sent or received
4700 * on a #GDBusConnection.
4705 * SECTION:gdbusmethodinvocation
4706 * @short_description: Object for handling remote calls
4707 * @include: gio/gio.h
4709 * Instances of the #GDBusMethodInvocation class are used when
4710 * handling D-Bus method calls. It provides a way to asynchronously
4711 * return results and errors.
4713 * The normal way to obtain a #GDBusMethodInvocation object is to receive
4714 * it as an argument to the handle_method_call() function in a
4715 * #GDBusInterfaceVTable that was passed to g_dbus_connection_register_object().
4720 * SECTION:gdbusnameowning
4721 * @title: Owning Bus Names
4722 * @short_description: Simple API for owning bus names
4723 * @include: gio/gio.h
4725 * Convenience API for owning bus names.
4727 * A simple example for owning a name can be found in
4728 * [gdbus-example-own-name.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-own-name.c)
4733 * SECTION:gdbusnamewatching
4734 * @title: Watching Bus Names
4735 * @short_description: Simple API for watching bus names
4736 * @include: gio/gio.h
4738 * Convenience API for watching bus names.
4740 * A simple example for watching a name can be found in
4741 * [gdbus-example-watch-name.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-watch-name.c)
4746 * SECTION:gdbusobject
4747 * @short_description: Base type for D-Bus objects
4748 * @include: gio/gio.h
4750 * The #GDBusObject type is the base type for D-Bus objects on both
4751 * the service side (see #GDBusObjectSkeleton) and the client side
4752 * (see #GDBusObjectProxy). It is essentially just a container of
4758 * SECTION:gdbusobjectmanager
4759 * @short_description: Base type for D-Bus object managers
4760 * @include: gio/gio.h
4762 * The #GDBusObjectManager type is the base type for service- and
4763 * client-side implementations of the standardized
4764 * [org.freedesktop.DBus.ObjectManager](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager)
4767 * See #GDBusObjectManagerClient for the client-side implementation
4768 * and #GDBusObjectManagerServer for the service-side implementation.
4773 * SECTION:gdbusobjectmanagerclient
4774 * @short_description: Client-side object manager
4775 * @include: gio/gio.h
4777 * #GDBusObjectManagerClient is used to create, monitor and delete object
4778 * proxies for remote objects exported by a #GDBusObjectManagerServer (or any
4779 * code implementing the
4780 * [org.freedesktop.DBus.ObjectManager](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager)
4783 * Once an instance of this type has been created, you can connect to
4784 * the #GDBusObjectManager::object-added and
4785 * #GDBusObjectManager::object-removed signals and inspect the
4786 * #GDBusObjectProxy objects returned by
4787 * g_dbus_object_manager_get_objects().
4789 * If the name for a #GDBusObjectManagerClient is not owned by anyone at
4790 * object construction time, the default behavior is to request the
4791 * message bus to launch an owner for the name. This behavior can be
4792 * disabled using the %G_DBUS_OBJECT_MANAGER_CLIENT_FLAGS_DO_NOT_AUTO_START
4793 * flag. It's also worth noting that this only works if the name of
4794 * interest is activatable in the first place. E.g. in some cases it
4795 * is not possible to launch an owner for the requested name. In this
4796 * case, #GDBusObjectManagerClient object construction still succeeds but
4797 * there will be no object proxies
4798 * (e.g. g_dbus_object_manager_get_objects() returns the empty list) and
4799 * the #GDBusObjectManagerClient:name-owner property is %NULL.
4801 * The owner of the requested name can come and go (for example
4802 * consider a system service being restarted) – #GDBusObjectManagerClient
4803 * handles this case too; simply connect to the #GObject::notify
4804 * signal to watch for changes on the #GDBusObjectManagerClient:name-owner
4805 * property. When the name owner vanishes, the behavior is that
4806 * #GDBusObjectManagerClient:name-owner is set to %NULL (this includes
4807 * emission of the #GObject::notify signal) and then
4808 * #GDBusObjectManager::object-removed signals are synthesized
4809 * for all currently existing object proxies. Since
4810 * #GDBusObjectManagerClient:name-owner is %NULL when this happens, you can
4811 * use this information to disambiguate a synthesized signal from a
4812 * genuine signal caused by object removal on the remote
4813 * #GDBusObjectManager. Similarly, when a new name owner appears,
4814 * #GDBusObjectManager::object-added signals are synthesized
4815 * while #GDBusObjectManagerClient:name-owner is still %NULL. Only when all
4816 * object proxies have been added, the #GDBusObjectManagerClient:name-owner
4817 * is set to the new name owner (this includes emission of the
4818 * #GObject::notify signal). Furthermore, you are guaranteed that
4819 * #GDBusObjectManagerClient:name-owner will alternate between a name owner
4820 * (e.g. `:1.42`) and %NULL even in the case where
4821 * the name of interest is atomically replaced
4823 * Ultimately, #GDBusObjectManagerClient is used to obtain #GDBusProxy
4824 * instances. All signals (including the
4825 * org.freedesktop.DBus.Properties::PropertiesChanged signal)
4826 * delivered to #GDBusProxy instances are guaranteed to originate
4827 * from the name owner. This guarantee along with the behavior
4828 * described above, means that certain race conditions including the
4829 * "half the proxy is from the old owner and the other half is from
4830 * the new owner" problem cannot happen.
4832 * To avoid having the application connect to signals on the returned
4833 * #GDBusObjectProxy and #GDBusProxy objects, the
4834 * #GDBusObject::interface-added,
4835 * #GDBusObject::interface-removed,
4836 * #GDBusProxy::g-properties-changed and
4837 * #GDBusProxy::g-signal signals
4838 * are also emitted on the #GDBusObjectManagerClient instance managing these
4839 * objects. The signals emitted are
4840 * #GDBusObjectManager::interface-added,
4841 * #GDBusObjectManager::interface-removed,
4842 * #GDBusObjectManagerClient::interface-proxy-properties-changed and
4843 * #GDBusObjectManagerClient::interface-proxy-signal.
4845 * Note that all callbacks and signals are emitted in the
4846 * [thread-default main context][g-main-context-push-thread-default]
4847 * that the #GDBusObjectManagerClient object was constructed
4848 * in. Additionally, the #GDBusObjectProxy and #GDBusProxy objects
4849 * originating from the #GDBusObjectManagerClient object will be created in
4850 * the same context and, consequently, will deliver signals in the
4856 * SECTION:gdbusobjectmanagerserver
4857 * @short_description: Service-side object manager
4858 * @include: gio/gio.h
4860 * #GDBusObjectManagerServer is used to export #GDBusObject instances using
4862 * [org.freedesktop.DBus.ObjectManager](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager)
4863 * interface. For example, remote D-Bus clients can get all objects
4864 * and properties in a single call. Additionally, any change in the
4865 * object hierarchy is broadcast using signals. This means that D-Bus
4866 * clients can keep caches up to date by only listening to D-Bus
4869 * See #GDBusObjectManagerClient for the client-side code that is
4870 * intended to be used with #GDBusObjectManagerServer or any D-Bus
4871 * object implementing the org.freedesktop.DBus.ObjectManager
4877 * SECTION:gdbusobjectproxy
4878 * @short_description: Client-side D-Bus object
4879 * @include: gio/gio.h
4881 * A #GDBusObjectProxy is an object used to represent a remote object
4882 * with one or more D-Bus interfaces. Normally, you don't instantiate
4883 * a #GDBusObjectProxy yourself - typically #GDBusObjectManagerClient
4884 * is used to obtain it.
4891 * SECTION:gdbusobjectskeleton
4892 * @short_description: Service-side D-Bus object
4893 * @include: gio/gio.h
4895 * A #GDBusObjectSkeleton instance is essentially a group of D-Bus
4896 * interfaces. The set of exported interfaces on the object may be
4897 * dynamic and change at runtime.
4899 * This type is intended to be used with #GDBusObjectManager.
4904 * SECTION:gdbusproxy
4905 * @short_description: Client-side D-Bus interface proxy
4906 * @include: gio/gio.h
4908 * #GDBusProxy is a base class used for proxies to access a D-Bus
4909 * interface on a remote object. A #GDBusProxy can be constructed for
4910 * both well-known and unique names.
4912 * By default, #GDBusProxy will cache all properties (and listen to
4913 * changes) of the remote object, and proxy all signals that gets
4914 * emitted. This behaviour can be changed by passing suitable
4915 * #GDBusProxyFlags when the proxy is created. If the proxy is for a
4916 * well-known name, the property cache is flushed when the name owner
4917 * vanishes and reloaded when a name owner appears.
4919 * If a #GDBusProxy is used for a well-known name, the owner of the
4920 * name is tracked and can be read from
4921 * #GDBusProxy:g-name-owner. Connect to the #GObject::notify signal to
4922 * get notified of changes. Additionally, only signals and property
4923 * changes emitted from the current name owner are considered and
4924 * calls are always sent to the current name owner. This avoids a
4925 * number of race conditions when the name is lost by one owner and
4926 * claimed by another. However, if no name owner currently exists,
4927 * then calls will be sent to the well-known name which may result in
4928 * the message bus launching an owner (unless
4929 * %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START is set).
4931 * The generic #GDBusProxy::g-properties-changed and
4932 * #GDBusProxy::g-signal signals are not very convenient to work with.
4933 * Therefore, the recommended way of working with proxies is to subclass
4934 * #GDBusProxy, and have more natural properties and signals in your derived
4935 * class. This [example][gdbus-example-gdbus-codegen] shows how this can
4936 * easily be done using the [gdbus-codegen][gdbus-codegen] tool.
4938 * A #GDBusProxy instance can be used from multiple threads but note
4939 * that all signals (e.g. #GDBusProxy::g-signal, #GDBusProxy::g-properties-changed
4940 * and #GObject::notify) are emitted in the
4941 * [thread-default main context][g-main-context-push-thread-default]
4942 * of the thread where the instance was constructed.
4944 * An example using a proxy for a well-known name can be found in
4945 * [gdbus-example-watch-proxy.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-watch-proxy.c)
4950 * SECTION:gdbusserver
4951 * @short_description: Helper for accepting connections
4952 * @include: gio/gio.h
4954 * #GDBusServer is a helper for listening to and accepting D-Bus
4955 * connections. This can be used to create a new D-Bus server, allowing two
4956 * peers to use the D-Bus protocol for their own specialized communication.
4957 * A server instance provided in this way will not perform message routing or
4958 * implement the org.freedesktop.DBus interface.
4960 * To just export an object on a well-known name on a message bus, such as the
4961 * session or system bus, you should instead use g_bus_own_name().
4963 * An example of peer-to-peer communication with G-DBus can be found
4964 * in [gdbus-example-peer.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-peer.c).
4969 * SECTION:gdbusutils
4970 * @title: D-Bus Utilities
4971 * @short_description: Various utilities related to D-Bus
4972 * @include: gio/gio.h
4974 * Various utility routines related to D-Bus.
4979 * SECTION:gdesktopappinfo
4980 * @title: GDesktopAppInfo
4981 * @short_description: Application information from desktop files
4982 * @include: gio/gdesktopappinfo.h
4984 * #GDesktopAppInfo is an implementation of #GAppInfo based on
4987 * Note that `<gio/gdesktopappinfo.h>` belongs to the UNIX-specific
4988 * GIO interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config
4989 * file when using it.
4995 * @short_description: Drive management
4996 * @include: gio/gio.h
4998 * #GDrive - this represent a piece of hardware connected to the machine.
4999 * It's generally only created for removable hardware or hardware with
5002 * #GDrive is a container class for #GVolume objects that stem from
5003 * the same piece of media. As such, #GDrive abstracts a drive with
5004 * (or without) removable media and provides operations for querying
5005 * whether media is available, determining whether media change is
5006 * automatically detected and ejecting the media.
5008 * If the #GDrive reports that media isn't automatically detected, one
5009 * can poll for media; typically one should not do this periodically
5010 * as a poll for media operation is potententially expensive and may
5011 * spin up the drive creating noise.
5013 * #GDrive supports starting and stopping drives with authentication
5014 * support for the former. This can be used to support a diverse set
5015 * of use cases including connecting/disconnecting iSCSI devices,
5016 * powering down external disk enclosures and starting/stopping
5017 * multi-disk devices such as RAID devices. Note that the actual
5018 * semantics and side-effects of starting/stopping a #GDrive may vary
5019 * according to implementation. To choose the correct verbs in e.g. a
5020 * file manager, use g_drive_get_start_stop_type().
5022 * For porting from GnomeVFS note that there is no equivalent of
5023 * #GDrive in that API.
5029 * @short_description: An object for emblems
5030 * @include: gio/gio.h
5031 * @see_also: #GIcon, #GEmblemedIcon, #GLoadableIcon, #GThemedIcon
5033 * #GEmblem is an implementation of #GIcon that supports
5034 * having an emblem, which is an icon with additional properties.
5035 * It can than be added to a #GEmblemedIcon.
5037 * Currently, only metainformation about the emblem's origin is
5038 * supported. More may be added in the future.
5043 * SECTION:gemblemedicon
5044 * @short_description: Icon with emblems
5045 * @include: gio/gio.h
5046 * @see_also: #GIcon, #GLoadableIcon, #GThemedIcon, #GEmblem
5048 * #GEmblemedIcon is an implementation of #GIcon that supports
5049 * adding an emblem to an icon. Adding multiple emblems to an
5050 * icon is ensured via g_emblemed_icon_add_emblem().
5052 * Note that #GEmblemedIcon allows no control over the position
5053 * of the emblems. See also #GEmblem for more information.
5059 * @short_description: File and Directory Handling
5060 * @include: gio/gio.h
5061 * @see_also: #GFileInfo, #GFileEnumerator
5063 * #GFile is a high level abstraction for manipulating files on a
5064 * virtual file system. #GFiles are lightweight, immutable objects
5065 * that do no I/O upon creation. It is necessary to understand that
5066 * #GFile objects do not represent files, merely an identifier for a
5067 * file. All file content I/O is implemented as streaming operations
5068 * (see #GInputStream and #GOutputStream).
5070 * To construct a #GFile, you can use:
5071 * - g_file_new_for_path() if you have a path.
5072 * - g_file_new_for_uri() if you have a URI.
5073 * - g_file_new_for_commandline_arg() for a command line argument.
5074 * - g_file_new_tmp() to create a temporary file from a template.
5075 * - g_file_parse_name() from a UTF-8 string gotten from g_file_get_parse_name().
5077 * One way to think of a #GFile is as an abstraction of a pathname. For
5078 * normal files the system pathname is what is stored internally, but as
5079 * #GFiles are extensible it could also be something else that corresponds
5080 * to a pathname in a userspace implementation of a filesystem.
5082 * #GFiles make up hierarchies of directories and files that correspond to
5083 * the files on a filesystem. You can move through the file system with
5084 * #GFile using g_file_get_parent() to get an identifier for the parent
5085 * directory, g_file_get_child() to get a child within a directory,
5086 * g_file_resolve_relative_path() to resolve a relative path between two
5087 * #GFiles. There can be multiple hierarchies, so you may not end up at
5088 * the same root if you repeatedly call g_file_get_parent() on two different
5091 * All #GFiles have a basename (get with g_file_get_basename()). These names
5092 * are byte strings that are used to identify the file on the filesystem
5093 * (relative to its parent directory) and there is no guarantees that they
5094 * have any particular charset encoding or even make any sense at all. If
5095 * you want to use filenames in a user interface you should use the display
5096 * name that you can get by requesting the
5097 * %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME attribute with g_file_query_info().
5098 * This is guaranteed to be in UTF-8 and can be used in a user interface.
5099 * But always store the real basename or the #GFile to use to actually
5100 * access the file, because there is no way to go from a display name to
5103 * Using #GFile as an identifier has the same weaknesses as using a path
5104 * in that there may be multiple aliases for the same file. For instance,
5105 * hard or soft links may cause two different #GFiles to refer to the same
5106 * file. Other possible causes for aliases are: case insensitive filesystems,
5107 * short and long names on FAT/NTFS, or bind mounts in Linux. If you want to
5108 * check if two #GFiles point to the same file you can query for the
5109 * %G_FILE_ATTRIBUTE_ID_FILE attribute. Note that #GFile does some trivial
5110 * canonicalization of pathnames passed in, so that trivial differences in
5111 * the path string used at creation (duplicated slashes, slash at end of
5112 * path, "." or ".." path segments, etc) does not create different #GFiles.
5114 * Many #GFile operations have both synchronous and asynchronous versions
5115 * to suit your application. Asynchronous versions of synchronous functions
5116 * simply have _async() appended to their function names. The asynchronous
5117 * I/O functions call a #GAsyncReadyCallback which is then used to finalize
5118 * the operation, producing a GAsyncResult which is then passed to the
5119 * function's matching _finish() operation.
5121 * Some #GFile operations do not have synchronous analogs, as they may
5122 * take a very long time to finish, and blocking may leave an application
5123 * unusable. Notable cases include:
5124 * - g_file_mount_mountable() to mount a mountable file.
5125 * - g_file_unmount_mountable_with_operation() to unmount a mountable file.
5126 * - g_file_eject_mountable_with_operation() to eject a mountable file.
5128 * ## Entity Tags # {#gfile-etag}
5130 * One notable feature of #GFiles are entity tags, or "etags" for
5131 * short. Entity tags are somewhat like a more abstract version of the
5132 * traditional mtime, and can be used to quickly determine if the file
5133 * has been modified from the version on the file system. See the
5135 * [specification](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html)
5136 * for HTTP Etag headers, which are a very similar concept.
5141 * SECTION:gfileattribute
5142 * @short_description: Key-Value Paired File Attributes
5143 * @include: gio/gio.h
5144 * @see_also: #GFile, #GFileInfo
5146 * File attributes in GIO consist of a list of key-value pairs.
5148 * Keys are strings that contain a key namespace and a key name, separated
5149 * by a colon, e.g. "namespace::keyname". Namespaces are included to sort
5150 * key-value pairs by namespaces for relevance. Keys can be retrived
5151 * using wildcards, e.g. "standard::*" will return all of the keys in the
5152 * "standard" namespace.
5154 * The list of possible attributes for a filesystem (pointed to by a #GFile) is
5155 * available as a #GFileAttributeInfoList. This list is queryable by key names
5156 * as indicated earlier.
5158 * Information is stored within the list in #GFileAttributeInfo structures.
5159 * The info structure can store different types, listed in the enum
5160 * #GFileAttributeType. Upon creation of a #GFileAttributeInfo, the type will
5161 * be set to %G_FILE_ATTRIBUTE_TYPE_INVALID.
5163 * Classes that implement #GFileIface will create a #GFileAttributeInfoList and
5164 * install default keys and values for their given file system, architecture,
5165 * and other possible implementation details (e.g., on a UNIX system, a file
5166 * attribute key will be registered for the user id for a given file).
5168 * ## Default Namespaces
5170 * - `"standard"`: The "Standard" namespace. General file information that
5171 * any application may need should be put in this namespace. Examples
5172 * include the file's name, type, and size.
5173 * - `"etag`: The [Entity Tag][gfile-etag] namespace. Currently, the only key
5174 * in this namespace is "value", which contains the value of the current
5176 * - `"id"`: The "Identification" namespace. This namespace is used by file
5177 * managers and applications that list directories to check for loops and
5178 * to uniquely identify files.
5179 * - `"access"`: The "Access" namespace. Used to check if a user has the
5180 * proper privileges to access files and perform file operations. Keys in
5181 * this namespace are made to be generic and easily understood, e.g. the
5182 * "can_read" key is %TRUE if the current user has permission to read the
5183 * file. UNIX permissions and NTFS ACLs in Windows should be mapped to
5185 * - `"mountable"`: The "Mountable" namespace. Includes simple boolean keys
5186 * for checking if a file or path supports mount operations, e.g. mount,
5187 * unmount, eject. These are used for files of type %G_FILE_TYPE_MOUNTABLE.
5188 * - `"time"`: The "Time" namespace. Includes file access, changed, created
5190 * - `"unix"`: The "Unix" namespace. Includes UNIX-specific information and
5191 * may not be available for all files. Examples include the UNIX "UID",
5193 * - `"dos"`: The "DOS" namespace. Includes DOS-specific information and may
5194 * not be available for all files. Examples include "is_system" for checking
5195 * if a file is marked as a system file, and "is_archive" for checking if a
5196 * file is marked as an archive file.
5197 * - `"owner"`: The "Owner" namespace. Includes information about who owns a
5198 * file. May not be available for all file systems. Examples include "user"
5199 * for getting the user name of the file owner. This information is often
5200 * mapped from some backend specific data such as a UNIX UID.
5201 * - `"thumbnail"`: The "Thumbnail" namespace. Includes information about file
5202 * thumbnails and their location within the file system. Examples of keys in
5203 * this namespace include "path" to get the location of a thumbnail, "failed"
5204 * to check if thumbnailing of the file failed, and "is-valid" to check if
5205 * the thumbnail is outdated.
5206 * - `"filesystem"`: The "Filesystem" namespace. Gets information about the
5207 * file system where a file is located, such as its type, how much space is
5208 * left available, and the overall size of the file system.
5209 * - `"gvfs"`: The "GVFS" namespace. Keys in this namespace contain information
5210 * about the current GVFS backend in use.
5211 * - `"xattr"`: The "xattr" namespace. Gets information about extended
5212 * user attributes. See attr(5). The "user." prefix of the extended user
5213 * attribute name is stripped away when constructing keys in this namespace,
5214 * e.g. "xattr::mime_type" for the extended attribute with the name
5215 * "user.mime_type". Note that this information is only available if
5216 * GLib has been built with extended attribute support.
5217 * - `"xattr-sys"`: The "xattr-sys" namespace. Gets information about
5218 * extended attributes which are not user-specific. See attr(5). Note
5219 * that this information is only available if GLib has been built with
5220 * extended attribute support.
5221 * - `"selinux"`: The "SELinux" namespace. Includes information about the
5222 * SELinux context of files. Note that this information is only available
5223 * if GLib has been built with SELinux support.
5225 * Please note that these are not all of the possible namespaces.
5226 * More namespaces can be added from GIO modules or by individual applications.
5227 * For more information about writing GIO modules, see #GIOModule.
5229 * <!-- TODO: Implementation note about using extended attributes on supported
5234 * For a list of the built-in keys and their types, see the
5235 * [GFileInfo][GFileInfo] documentation.
5237 * Note that there are no predefined keys in the "xattr" and "xattr-sys"
5238 * namespaces. Keys for the "xattr" namespace are constructed by stripping
5239 * away the "user." prefix from the extended user attribute, and prepending
5240 * "xattr::". Keys for the "xattr-sys" namespace are constructed by
5241 * concatenating "xattr-sys::" with the extended attribute name. All extended
5242 * attribute values are returned as hex-encoded strings in which bytes outside
5243 * the ASCII range are encoded as escape sequences of the form \x`nn`
5244 * where `nn` is a 2-digit hexadecimal number.
5249 * SECTION:gfiledescriptorbased
5250 * @short_description: Interface for file descriptor based IO
5251 * @include: gio/gfiledescriptorbased.h
5252 * @see_also: #GInputStream, #GOutputStream
5254 * #GFileDescriptorBased is implemented by streams (implementations of
5255 * #GInputStream or #GOutputStream) that are based on file descriptors.
5257 * Note that `<gio/gfiledescriptorbased.h>` belongs to the UNIX-specific
5258 * GIO interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config
5259 * file when using it.
5266 * SECTION:gfileenumerator
5267 * @short_description: Enumerated Files Routines
5268 * @include: gio/gio.h
5270 * #GFileEnumerator allows you to operate on a set of #GFiles,
5271 * returning a #GFileInfo structure for each file enumerated (e.g.
5272 * g_file_enumerate_children() will return a #GFileEnumerator for each
5273 * of the children within a directory).
5275 * To get the next file's information from a #GFileEnumerator, use
5276 * g_file_enumerator_next_file() or its asynchronous version,
5277 * g_file_enumerator_next_files_async(). Note that the asynchronous
5278 * version will return a list of #GFileInfos, whereas the
5279 * synchronous will only return the next file in the enumerator.
5281 * The ordering of returned files is unspecified for non-Unix
5282 * platforms; for more information, see g_dir_read_name(). On Unix,
5283 * when operating on local files, returned files will be sorted by
5284 * inode number. Effectively you can assume that the ordering of
5285 * returned files will be stable between successive calls (and
5286 * applications) assuming the directory is unchanged.
5288 * If your application needs a specific ordering, such as by name or
5289 * modification time, you will have to implement that in your
5292 * To close a #GFileEnumerator, use g_file_enumerator_close(), or
5293 * its asynchronous version, g_file_enumerator_close_async(). Once
5294 * a #GFileEnumerator is closed, no further actions may be performed
5295 * on it, and it should be freed with g_object_unref().
5301 * @short_description: Icons pointing to an image file
5302 * @include: gio/gio.h
5303 * @see_also: #GIcon, #GLoadableIcon
5305 * #GFileIcon specifies an icon by pointing to an image file
5306 * to be used as icon.
5312 * @short_description: File Information and Attributes
5313 * @include: gio/gio.h
5314 * @see_also: #GFile, [GFileAttribute][gio-GFileAttribute]
5316 * Functionality for manipulating basic metadata for files. #GFileInfo
5317 * implements methods for getting information that all files should
5318 * contain, and allows for manipulation of extended attributes.
5320 * See [GFileAttribute][gio-GFileAttribute for more information on how
5321 * GIO handles file attributes.
5323 * To obtain a #GFileInfo for a #GFile, use g_file_query_info() (or its
5324 * async variant). To obtain a #GFileInfo for a file input or output
5325 * stream, use g_file_input_stream_query_info() or
5326 * g_file_output_stream_query_info() (or their async variants).
5328 * To change the actual attributes of a file, you should then set the
5329 * attribute in the #GFileInfo and call g_file_set_attributes_from_info()
5330 * or g_file_set_attributes_async() on a GFile.
5332 * However, not all attributes can be changed in the file. For instance,
5333 * the actual size of a file cannot be changed via g_file_info_set_size().
5334 * You may call g_file_query_settable_attributes() and
5335 * g_file_query_writable_namespaces() to discover the settable attributes
5336 * of a particular file at runtime.
5338 * #GFileAttributeMatcher allows for searching through a #GFileInfo for
5344 * SECTION:gfileinputstream
5345 * @short_description: File input streaming operations
5346 * @include: gio/gio.h
5347 * @see_also: #GInputStream, #GDataInputStream, #GSeekable
5349 * GFileInputStream provides input streams that take their
5350 * content from a file.
5352 * GFileInputStream implements #GSeekable, which allows the input
5353 * stream to jump to arbitrary positions in the file, provided the
5354 * filesystem of the file allows it. To find the position of a file
5355 * input stream, use g_seekable_tell(). To find out if a file input
5356 * stream supports seeking, use g_seekable_can_seek().
5357 * To position a file input stream, use g_seekable_seek().
5362 * SECTION:gfileiostream
5363 * @short_description: File read and write streaming operations
5364 * @include: gio/gio.h
5365 * @see_also: #GIOStream, #GFileInputStream, #GFileOutputStream, #GSeekable
5367 * GFileIOStream provides io streams that both read and write to the same
5370 * GFileIOStream implements #GSeekable, which allows the io
5371 * stream to jump to arbitrary positions in the file and to truncate
5372 * the file, provided the filesystem of the file supports these
5375 * To find the position of a file io stream, use
5376 * g_seekable_tell().
5378 * To find out if a file io stream supports seeking, use g_seekable_can_seek().
5379 * To position a file io stream, use g_seekable_seek().
5380 * To find out if a file io stream supports truncating, use
5381 * g_seekable_can_truncate(). To truncate a file io
5382 * stream, use g_seekable_truncate().
5384 * The default implementation of all the #GFileIOStream operations
5385 * and the implementation of #GSeekable just call into the same operations
5386 * on the output stream.
5393 * SECTION:gfilemonitor
5394 * @short_description: File Monitor
5395 * @include: gio/gio.h
5397 * Monitors a file or directory for changes.
5399 * To obtain a #GFileMonitor for a file or directory, use
5400 * g_file_monitor(), g_file_monitor_file(), or
5401 * g_file_monitor_directory().
5403 * To get informed about changes to the file or directory you are
5404 * monitoring, connect to the #GFileMonitor::changed signal. The
5405 * signal will be emitted in the
5406 * [thread-default main context][g-main-context-push-thread-default]
5407 * of the thread that the monitor was created in
5408 * (though if the global default main context is blocked, this may
5409 * cause notifications to be blocked even if the thread-default
5410 * context is still running).
5415 * SECTION:gfilenamecompleter
5416 * @short_description: Filename Completer
5417 * @include: gio/gio.h
5419 * Completes partial file and directory names given a partial string by
5420 * looking in the file system for clues. Can return a list of possible
5421 * completion strings for widget implementations.
5426 * SECTION:gfileoutputstream
5427 * @short_description: File output streaming operations
5428 * @include: gio/gio.h
5429 * @see_also: #GOutputStream, #GDataOutputStream, #GSeekable
5431 * GFileOutputStream provides output streams that write their
5432 * content to a file.
5434 * GFileOutputStream implements #GSeekable, which allows the output
5435 * stream to jump to arbitrary positions in the file and to truncate
5436 * the file, provided the filesystem of the file supports these
5439 * To find the position of a file output stream, use g_seekable_tell().
5440 * To find out if a file output stream supports seeking, use
5441 * g_seekable_can_seek().To position a file output stream, use
5442 * g_seekable_seek(). To find out if a file output stream supports
5443 * truncating, use g_seekable_can_truncate(). To truncate a file output
5444 * stream, use g_seekable_truncate().
5449 * SECTION:gfilterinputstream
5450 * @short_description: Filter Input Stream
5451 * @include: gio/gio.h
5453 * Base class for input stream implementations that perform some
5454 * kind of filtering operation on a base stream. Typical examples
5455 * of filtering operations are character set conversion, compression
5456 * and byte order flipping.
5461 * SECTION:gfilteroutputstream
5462 * @short_description: Filter Output Stream
5463 * @include: gio/gio.h
5465 * Base class for output stream implementations that perform some
5466 * kind of filtering operation on a base stream. Typical examples
5467 * of filtering operations are character set conversion, compression
5468 * and byte order flipping.
5474 * @short_description: Interface for icons
5475 * @include: gio/gio.h
5477 * #GIcon is a very minimal interface for icons. It provides functions
5478 * for checking the equality of two icons, hashing of icons and
5479 * serializing an icon to and from strings.
5481 * #GIcon does not provide the actual pixmap for the icon as this is out
5482 * of GIO's scope, however implementations of #GIcon may contain the name
5483 * of an icon (see #GThemedIcon), or the path to an icon (see #GLoadableIcon).
5485 * To obtain a hash of a #GIcon, see g_icon_hash().
5487 * To check if two #GIcons are equal, see g_icon_equal().
5489 * For serializing a #GIcon, use g_icon_serialize() and
5490 * g_icon_deserialize().
5492 * If you want to consume #GIcon (for example, in a toolkit) you must
5493 * be prepared to handle at least the three following cases:
5494 * #GLoadableIcon, #GThemedIcon and #GEmblemedIcon. It may also make
5495 * sense to have fast-paths for other cases (like handling #GdkPixbuf
5496 * directly, for example) but all compliant #GIcon implementations
5497 * outside of GIO must implement #GLoadableIcon.
5499 * If your application or library provides one or more #GIcon
5500 * implementations you need to ensure that your new implementation also
5501 * implements #GLoadableIcon. Additionally, you must provide an
5502 * implementation of g_icon_serialize() that gives a result that is
5503 * understood by g_icon_deserialize(), yielding one of the built-in icon
5509 * SECTION:ginetaddress
5510 * @short_description: An IPv4/IPv6 address
5511 * @include: gio/gio.h
5513 * #GInetAddress represents an IPv4 or IPv6 internet address. Use
5514 * g_resolver_lookup_by_name() or g_resolver_lookup_by_name_async() to
5515 * look up the #GInetAddress for a hostname. Use
5516 * g_resolver_lookup_by_address() or
5517 * g_resolver_lookup_by_address_async() to look up the hostname for a
5520 * To actually connect to a remote host, you will need a
5521 * #GInetSocketAddress (which includes a #GInetAddress as well as a
5527 * SECTION:ginetaddressmask
5528 * @short_description: An IPv4/IPv6 address mask
5529 * @include: gio/gio.h
5531 * #GInetAddressMask represents a range of IPv4 or IPv6 addresses
5532 * described by a base address and a length indicating how many bits
5533 * of the base address are relevant for matching purposes. These are
5534 * often given in string form. Eg, "10.0.0.0/8", or "fe80::/10".
5539 * SECTION:ginetsocketaddress
5540 * @short_description: Internet GSocketAddress
5541 * @include: gio/gio.h
5543 * An IPv4 or IPv6 socket address; that is, the combination of a
5544 * #GInetAddress and a port number.
5550 * @short_description: Failable object initialization interface
5551 * @include: gio/gio.h
5552 * @see_also: #GAsyncInitable
5554 * #GInitable is implemented by objects that can fail during
5555 * initialization. If an object implements this interface then
5556 * it must be initialized as the first thing after construction,
5557 * either via g_initable_init() or g_async_initable_init_async()
5558 * (the latter is only available if it also implements #GAsyncInitable).
5560 * If the object is not initialized, or initialization returns with an
5561 * error, then all operations on the object except g_object_ref() and
5562 * g_object_unref() are considered to be invalid, and have undefined
5563 * behaviour. They will often fail with g_critical() or g_warning(), but
5564 * this must not be relied on.
5566 * Users of objects implementing this are not intended to use
5567 * the interface method directly, instead it will be used automatically
5568 * in various ways. For C applications you generally just call
5569 * g_initable_new() directly, or indirectly via a foo_thing_new() wrapper.
5570 * This will call g_initable_init() under the cover, returning %NULL and
5571 * setting a #GError on failure (at which point the instance is
5574 * For bindings in languages where the native constructor supports
5575 * exceptions the binding could check for objects implemention %GInitable
5576 * during normal construction and automatically initialize them, throwing
5577 * an exception on failure.
5582 * SECTION:ginputstream
5583 * @short_description: Base class for implementing streaming input
5584 * @include: gio/gio.h
5586 * #GInputStream has functions to read from a stream (g_input_stream_read()),
5587 * to close a stream (g_input_stream_close()) and to skip some content
5588 * (g_input_stream_skip()).
5590 * To copy the content of an input stream to an output stream without
5591 * manually handling the reads and writes, use g_output_stream_splice().
5593 * All of these functions have async variants too.
5599 * @short_description: Error helper functions
5600 * @include: gio/gio.h
5602 * Contains helper functions for reporting errors to the user.
5608 * @short_description: Loadable GIO Modules
5609 * @include: gio/gio.h
5611 * Provides an interface and default functions for loading and unloading
5612 * modules. This is used internally to make GIO extensible, but can also
5613 * be used by others to implement module loading.
5618 * SECTION:gioscheduler
5619 * @short_description: I/O Scheduler
5620 * @include: gio/gio.h
5622 * As of GLib 2.36, #GIOScheduler is deprecated in favor of
5623 * #GThreadPool and #GTask.
5625 * Schedules asynchronous I/O operations. #GIOScheduler integrates
5626 * into the main event loop (#GMainLoop) and uses threads.
5632 * @short_description: Base class for implementing read/write streams
5633 * @include: gio/gio.h
5634 * @see_also: #GInputStream, #GOutputStream
5636 * GIOStream represents an object that has both read and write streams.
5637 * Generally the two streams acts as separate input and output streams,
5638 * but they share some common resources and state. For instance, for
5639 * seekable streams they may use the same position in both streams.
5641 * Examples of #GIOStream objects are #GSocketConnection which represents
5642 * a two-way network connection, and #GFileIOStream which represent a
5643 * file handle opened in read-write mode.
5645 * To do the actual reading and writing you need to get the substreams
5646 * with g_io_stream_get_input_stream() and g_io_stream_get_output_stream().
5648 * The #GIOStream object owns the input and the output streams, not the other
5649 * way around, so keeping the substreams alive will not keep the #GIOStream
5650 * object alive. If the #GIOStream object is freed it will be closed, thus
5651 * closing the substream, so even if the substreams stay alive they will
5652 * always just return a %G_IO_ERROR_CLOSED for all operations.
5654 * To close a stream use g_io_stream_close() which will close the common
5655 * stream object and also the individual substreams. You can also close
5656 * the substreams themselves. In most cases this only marks the
5657 * substream as closed, so further I/O on it fails but common state in the
5658 * #GIOStream may still be open. However, some streams may support
5659 * "half-closed" states where one direction of the stream is actually shut down.
5666 * SECTION:gloadableicon
5667 * @short_description: Loadable Icons
5668 * @include: gio/gio.h
5669 * @see_also: #GIcon, #GThemedIcon
5671 * Extends the #GIcon interface and adds the ability to
5672 * load icons from streams.
5677 * SECTION:gmemoryinputstream
5678 * @short_description: Streaming input operations on memory chunks
5679 * @include: gio/gio.h
5680 * @see_also: #GMemoryOutputStream
5682 * #GMemoryInputStream is a class for using arbitrary
5683 * memory chunks as input for GIO streaming input operations.
5685 * As of GLib 2.34, #GMemoryInputStream implements
5686 * #GPollableInputStream.
5691 * SECTION:gmemoryoutputstream
5692 * @short_description: Streaming output operations on memory chunks
5693 * @include: gio/gio.h
5694 * @see_also: #GMemoryInputStream
5696 * #GMemoryOutputStream is a class for using arbitrary
5697 * memory chunks as output for GIO streaming output operations.
5699 * As of GLib 2.34, #GMemoryOutputStream trivially implements
5700 * #GPollableOutputStream: it always polls as ready.
5707 * @short_description: A simple implementation of GMenuModel
5708 * @include: gio/gio.h
5710 * #GMenu is a simple implementation of #GMenuModel.
5711 * You populate a #GMenu by adding #GMenuItem instances to it.
5713 * There are some convenience functions to allow you to directly
5714 * add items (avoiding #GMenuItem) for the common cases. To add
5715 * a regular item, use g_menu_insert(). To add a section, use
5716 * g_menu_insert_section(). To add a submenu, use
5717 * g_menu_insert_submenu().
5722 * SECTION:gmenuexporter
5723 * @title: GMenuModel exporter
5724 * @short_description: Export GMenuModels on D-Bus
5725 * @include: gio/gio.h
5726 * @see_also: #GMenuModel, #GDBusMenuModel
5728 * These functions support exporting a #GMenuModel on D-Bus.
5729 * The D-Bus interface that is used is a private implementation
5732 * To access an exported #GMenuModel remotely, use
5733 * g_dbus_menu_model_get() to obtain a #GDBusMenuModel.
5738 * SECTION:gmenumodel
5739 * @title: GMenuModel
5740 * @short_description: An abstract class representing the contents of a menu
5741 * @include: gio/gio.h
5742 * @see_also: #GActionGroup
5744 * #GMenuModel represents the contents of a menu -- an ordered list of
5745 * menu items. The items are associated with actions, which can be
5746 * activated through them. Items can be grouped in sections, and may
5747 * have submenus associated with them. Both items and sections usually
5748 * have some representation data, such as labels or icons. The type of
5749 * the associated action (ie whether it is stateful, and what kind of
5750 * state it has) can influence the representation of the item.
5752 * The conceptual model of menus in #GMenuModel is hierarchical:
5753 * sections and submenus are again represented by #GMenuModels.
5754 * Menus themselves do not define their own roles. Rather, the role
5755 * of a particular #GMenuModel is defined by the item that references
5756 * it (or, in the case of the 'root' menu, is defined by the context
5757 * in which it is used).
5759 * As an example, consider the visible portions of this menu:
5761 * ## An example menu # {#menu-example}
5763 * ![](menu-example.png)
5765 * There are 8 "menus" visible in the screenshot: one menubar, two
5766 * submenus and 5 sections:
5768 * - the toplevel menubar (containing 4 items)
5769 * - the View submenu (containing 3 sections)
5770 * - the first section of the View submenu (containing 2 items)
5771 * - the second section of the View submenu (containing 1 item)
5772 * - the final section of the View submenu (containing 1 item)
5773 * - the Highlight Mode submenu (containing 2 sections)
5774 * - the Sources section (containing 2 items)
5775 * - the Markup section (containing 2 items)
5777 * The [example][menu-model] illustrates the conceptual connection between
5778 * these 8 menus. Each large block in the figure represents a menu and the
5779 * smaller blocks within the large block represent items in that menu. Some
5780 * items contain references to other menus.
5782 * ## A menu example # {#menu-model}
5784 * ![](menu-model.png)
5786 * Notice that the separators visible in the [example][menu-example]
5787 * appear nowhere in the [menu model][menu-model]. This is because
5788 * separators are not explicitly represented in the menu model. Instead,
5789 * a separator is inserted between any two non-empty sections of a menu.
5790 * Section items can have labels just like any other item. In that case,
5791 * a display system may show a section header instead of a separator.
5793 * The motivation for this abstract model of application controls is
5794 * that modern user interfaces tend to make these controls available
5795 * outside the application. Examples include global menus, jumplists,
5796 * dash boards, etc. To support such uses, it is necessary to 'export'
5797 * information about actions and their representation in menus, which
5798 * is exactly what the [GActionGroup exporter][gio-GActionGroup-exporter]
5799 * and the [GMenuModel exporter][gio-GMenuModel-exporter] do for
5800 * #GActionGroup and #GMenuModel. The client-side counterparts to
5801 * make use of the exported information are #GDBusActionGroup and
5804 * The API of #GMenuModel is very generic, with iterators for the
5805 * attributes and links of an item, see g_menu_model_iterate_item_attributes()
5806 * and g_menu_model_iterate_item_links(). The 'standard' attributes and
5807 * link types have predefined names: %G_MENU_ATTRIBUTE_LABEL,
5808 * %G_MENU_ATTRIBUTE_ACTION, %G_MENU_ATTRIBUTE_TARGET, %G_MENU_LINK_SECTION
5809 * and %G_MENU_LINK_SUBMENU.
5811 * Items in a #GMenuModel represent active controls if they refer to
5812 * an action that can get activated when the user interacts with the
5813 * menu item. The reference to the action is encoded by the string id
5814 * in the %G_MENU_ATTRIBUTE_ACTION attribute. An action id uniquely
5815 * identifies an action in an action group. Which action group(s) provide
5816 * actions depends on the context in which the menu model is used.
5817 * E.g. when the model is exported as the application menu of a
5818 * #GtkApplication, actions can be application-wide or window-specific
5819 * (and thus come from two different action groups). By convention, the
5820 * application-wide actions have names that start with "app.", while the
5821 * names of window-specific actions start with "win.".
5823 * While a wide variety of stateful actions is possible, the following
5824 * is the minimum that is expected to be supported by all users of exported
5826 * - an action with no parameter type and no state
5827 * - an action with no parameter type and boolean state
5828 * - an action with string parameter type and string state
5832 * A stateless action typically corresponds to an ordinary menu item.
5834 * Selecting such a menu item will activate the action (with no parameter).
5838 * An action with a boolean state will most typically be used with a "toggle"
5839 * or "switch" menu item. The state can be set directly, but activating the
5840 * action (with no parameter) results in the state being toggled.
5842 * Selecting a toggle menu item will activate the action. The menu item should
5843 * be rendered as "checked" when the state is true.
5845 * ## String Parameter and State
5847 * Actions with string parameters and state will most typically be used to
5848 * represent an enumerated choice over the items available for a group of
5849 * radio menu items. Activating the action with a string parameter is
5850 * equivalent to setting that parameter as the state.
5852 * Radio menu items, in addition to being associated with the action, will
5853 * have a target value. Selecting that menu item will result in activation
5854 * of the action with the target value as the parameter. The menu item should
5855 * be rendered as "selected" when the state of the action is equal to the
5856 * target value of the menu item.
5862 * @short_description: Mount management
5863 * @include: gio/gio.h
5864 * @see_also: GVolume, GUnixMountEntry, GUnixMountPoint
5866 * The #GMount interface represents user-visible mounts. Note, when
5867 * porting from GnomeVFS, #GMount is the moral equivalent of #GnomeVFSVolume.
5869 * #GMount is a "mounted" filesystem that you can access. Mounted is in
5870 * quotes because it's not the same as a unix mount, it might be a gvfs
5871 * mount, but you can still access the files on it if you use GIO. Might or
5872 * might not be related to a volume object.
5874 * Unmounting a #GMount instance is an asynchronous operation. For
5875 * more information about asynchronous operations, see #GAsyncResult
5876 * and #GTask. To unmount a #GMount instance, first call
5877 * g_mount_unmount_with_operation() with (at least) the #GMount instance and a
5878 * #GAsyncReadyCallback. The callback will be fired when the
5879 * operation has resolved (either with success or failure), and a
5880 * #GAsyncReady structure will be passed to the callback. That
5881 * callback should then call g_mount_unmount_with_operation_finish() with the #GMount
5882 * and the #GAsyncReady data to see if the operation was completed
5883 * successfully. If an @error is present when g_mount_unmount_with_operation_finish()
5884 * is called, then it will be filled with any error information.
5889 * SECTION:gmountoperation
5890 * @short_description: Object used for authentication and user interaction
5891 * @include: gio/gio.h
5893 * #GMountOperation provides a mechanism for interacting with the user.
5894 * It can be used for authenticating mountable operations, such as loop
5895 * mounting files, hard drive partitions or server locations. It can
5896 * also be used to ask the user questions or show a list of applications
5897 * preventing unmount or eject operations from completing.
5899 * Note that #GMountOperation is used for more than just #GMount
5900 * objects – for example it is also used in g_drive_start() and
5903 * Users should instantiate a subclass of this that implements all the
5904 * various callbacks to show the required dialogs, such as
5905 * #GtkMountOperation. If no user interaction is desired (for example
5906 * when automounting filesystems at login time), usually %NULL can be
5907 * passed, see each method taking a #GMountOperation for details.
5912 * SECTION:gnetworkaddress
5913 * @short_description: A GSocketConnectable for resolving hostnames
5914 * @include: gio/gio.h
5916 * #GNetworkAddress provides an easy way to resolve a hostname and
5917 * then attempt to connect to that host, handling the possibility of
5918 * multiple IP addresses and multiple address families.
5920 * See #GSocketConnectable for and example of using the connectable
5926 * SECTION:gnetworking
5927 * @title: gnetworking.h
5928 * @short_description: System networking includes
5929 * @include: gio/gnetworking.h
5931 * The `<gio/gnetworking.h>` header can be included to get
5932 * various low-level networking-related system headers, automatically
5933 * taking care of certain portability issues for you.
5935 * This can be used, for example, if you want to call setsockopt()
5938 * Note that while WinSock has many of the same APIs as the
5939 * traditional UNIX socket API, most of them behave at least slightly
5940 * differently (particularly with respect to error handling). If you
5941 * want your code to work under both UNIX and Windows, you will need
5942 * to take these differences into account.
5944 * Also, under GNU libc, certain non-portable functions are only visible
5945 * in the headers if you define %_GNU_SOURCE before including them. Note
5946 * that this symbol must be defined before including any headers, or it
5947 * may not take effect.
5952 * SECTION:gnetworkmonitor
5953 * @title: GNetworkMonitor
5954 * @short_description: Network status monitor
5955 * @include: gio/gio.h
5957 * #GNetworkMonitor provides an easy-to-use cross-platform API
5958 * for monitoring network connectivity. On Linux, the implementation
5959 * is based on the kernel's netlink interface.
5964 * SECTION:gnetworkservice
5965 * @short_description: A GSocketConnectable for resolving SRV records
5966 * @include: gio/gio.h
5968 * Like #GNetworkAddress does with hostnames, #GNetworkService
5969 * provides an easy way to resolve a SRV record, and then attempt to
5970 * connect to one of the hosts that implements that service, handling
5971 * service priority/weighting, multiple IP addresses, and multiple
5974 * See #GSrvTarget for more information about SRV records, and see
5975 * #GSocketConnectable for and example of using the connectable
5981 * SECTION:gnotification
5982 * @short_description: User Notifications (pop up messages)
5983 * @include: gio/gio.h
5985 * #GNotification is a mechanism for creating a notification to be shown
5986 * to the user -- typically as a pop-up notification presented by the
5987 * desktop environment shell.
5989 * The key difference between #GNotification and other similar APIs is
5990 * that, if supported by the desktop environment, notifications sent
5991 * with #GNotification will persist after the application has exited,
5992 * and even across system reboots.
5994 * Since the user may click on a notification while the application is
5995 * not running, applications using #GNotification should be able to be
5996 * started as a D-Bus service, using #GApplication.
5998 * User interaction with a notification (either the default action, or
5999 * buttons) must be associated with actions on the application (ie:
6000 * "app." actions). It is not possible to route user interaction
6001 * through the notification itself, because the object will not exist if
6002 * the application is autostarted as a result of a notification being
6005 * A notification can be sent with g_application_send_notification().
6012 * SECTION:goutputstream
6013 * @short_description: Base class for implementing streaming output
6014 * @include: gio/gio.h
6016 * #GOutputStream has functions to write to a stream (g_output_stream_write()),
6017 * to close a stream (g_output_stream_close()) and to flush pending writes
6018 * (g_output_stream_flush()).
6020 * To copy the content of an input stream to an output stream without
6021 * manually handling the reads and writes, use g_output_stream_splice().
6023 * All of these functions have async variants too.
6028 * SECTION:gpermission
6029 * @title: GPermission
6030 * @short_description: An object representing the permission
6031 * to perform a certain action
6032 * @include: gio/gio.h
6034 * A #GPermission represents the status of the caller's permission to
6035 * perform a certain action.
6037 * You can query if the action is currently allowed and if it is
6038 * possible to acquire the permission so that the action will be allowed
6041 * There is also an API to actually acquire the permission and one to
6044 * As an example, a #GPermission might represent the ability for the
6045 * user to write to a #GSettings object. This #GPermission object could
6046 * then be used to decide if it is appropriate to show a "Click here to
6047 * unlock" button in a dialog and to provide the mechanism to invoke
6048 * when that button is clicked.
6053 * SECTION:gpollableinputstream
6054 * @short_description: Interface for pollable input streams
6055 * @include: gio/gio.h
6056 * @see_also: #GInputStream, #GPollableOutputStream, #GFileDescriptorBased
6058 * #GPollableInputStream is implemented by #GInputStreams that
6059 * can be polled for readiness to read. This can be used when
6060 * interfacing with a non-GIO API that expects
6061 * UNIX-file-descriptor-style asynchronous I/O rather than GIO-style.
6068 * SECTION:gpollableoutputstream
6069 * @short_description: Interface for pollable output streams
6070 * @include: gio/gio.h
6071 * @see_also: #GOutputStream, #GFileDescriptorBased, #GPollableInputStream
6073 * #GPollableOutputStream is implemented by #GOutputStreams that
6074 * can be polled for readiness to write. This can be used when
6075 * interfacing with a non-GIO API that expects
6076 * UNIX-file-descriptor-style asynchronous I/O rather than GIO-style.
6083 * SECTION:gpollableutils
6084 * @short_description: Utilities for pollable streams
6085 * @include: gio/gio.h
6087 * Utility functions for #GPollableInputStream and
6088 * #GPollableOutputStream implementations.
6093 * SECTION:gpropertyaction
6094 * @title: GPropertyAction
6095 * @short_description: A GAction reflecting a GObject property
6096 * @include: gio/gio.h
6098 * A #GPropertyAction is a way to get a #GAction with a state value
6099 * reflecting and controlling the value of a #GObject property.
6101 * The state of the action will correspond to the value of the property.
6102 * Changing it will change the property (assuming the requested value
6103 * matches the requirements as specified in the #GParamSpec).
6105 * Only the most common types are presently supported. Booleans are
6106 * mapped to booleans, strings to strings, signed/unsigned integers to
6107 * int32/uint32 and floats and doubles to doubles.
6109 * If the property is an enum then the state will be string-typed and
6110 * conversion will automatically be performed between the enum value and
6111 * "nick" string as per the #GEnumValue table.
6113 * Flags types are not currently supported.
6115 * Properties of object types, boxed types and pointer types are not
6116 * supported and probably never will be.
6118 * Properties of #GVariant types are not currently supported.
6120 * If the property is boolean-valued then the action will have a NULL
6121 * parameter type, and activating the action (with no parameter) will
6122 * toggle the value of the property.
6124 * In all other cases, the parameter type will correspond to the type of
6127 * The general idea here is to reduce the number of locations where a
6128 * particular piece of state is kept (and therefore has to be synchronised
6129 * between). #GPropertyAction does not have a separate state that is kept
6130 * in sync with the property value -- its state is the property value.
6132 * For example, it might be useful to create a #GAction corresponding to
6133 * the "visible-child-name" property of a #GtkStack so that the current
6134 * page can be switched from a menu. The active radio indication in the
6135 * menu is then directly determined from the active page of the
6138 * An anti-example would be binding the "active-id" property on a
6139 * #GtkComboBox. This is because the state of the combobox itself is
6140 * probably uninteresting and is actually being used to control
6143 * Another anti-example would be to bind to the "visible-child-name"
6144 * property of a #GtkStack if this value is actually stored in
6145 * #GSettings. In that case, the real source of the value is
6146 * #GSettings. If you want a #GAction to control a setting stored in
6147 * #GSettings, see g_settings_create_action() instead, and possibly
6148 * combine its use with g_settings_bind().
6156 * @short_description: Interface for proxy handling
6157 * @include: gio/gio.h
6159 * A #GProxy handles connecting to a remote host via a given type of
6160 * proxy server. It is implemented by the 'gio-proxy' extension point.
6161 * The extensions are named after their proxy protocol name. As an
6162 * example, a SOCKS5 proxy implementation can be retrieved with the
6163 * name 'socks5' using the function
6164 * g_io_extension_point_get_extension_by_name().
6171 * SECTION:gproxyaddress
6172 * @short_description: An internet address with proxy information
6173 * @include: gio/gio.h
6175 * Support for proxied #GInetSocketAddress.
6180 * SECTION:gproxyresolver
6181 * @short_description: Asynchronous and cancellable network proxy resolver
6182 * @include: gio/gio.h
6184 * #GProxyResolver provides synchronous and asynchronous network proxy
6185 * resolution. #GProxyResolver is used within #GSocketClient through
6186 * the method g_socket_connectable_proxy_enumerate().
6191 * SECTION:gremoteactiongroup
6192 * @title: GRemoteActionGroup
6193 * @short_description: A GActionGroup that interacts with other processes
6194 * @include: gio/gio.h
6196 * The GRemoteActionGroup interface is implemented by #GActionGroup
6197 * instances that either transmit action invocations to other processes
6198 * or receive action invocations in the local process from other
6201 * The interface has `_full` variants of the two
6202 * methods on #GActionGroup used to activate actions:
6203 * g_action_group_activate_action() and
6204 * g_action_group_change_action_state(). These variants allow a
6205 * "platform data" #GVariant to be specified: a dictionary providing
6206 * context for the action invocation (for example: timestamps, startup
6207 * notification IDs, etc).
6209 * #GDBusActionGroup implements #GRemoteActionGroup. This provides a
6210 * mechanism to send platform data for action invocations over D-Bus.
6212 * Additionally, g_dbus_connection_export_action_group() will check if
6213 * the exported #GActionGroup implements #GRemoteActionGroup and use the
6214 * `_full` variants of the calls if available. This
6215 * provides a mechanism by which to receive platform data for action
6216 * invocations that arrive by way of D-Bus.
6224 * @short_description: Asynchronous and cancellable DNS resolver
6225 * @include: gio/gio.h
6227 * #GResolver provides cancellable synchronous and asynchronous DNS
6228 * resolution, for hostnames (g_resolver_lookup_by_address(),
6229 * g_resolver_lookup_by_name() and their async variants) and SRV
6230 * (service) records (g_resolver_lookup_service()).
6232 * #GNetworkAddress and #GNetworkService provide wrappers around
6233 * #GResolver functionality that also implement #GSocketConnectable,
6234 * making it easy to connect to a remote host/service.
6240 * @short_description: Resource framework
6241 * @include: gio/gio.h
6243 * Applications and libraries often contain binary or textual data that is
6244 * really part of the application, rather than user data. For instance
6245 * #GtkBuilder .ui files, splashscreen images, GMenu markup xml, CSS files,
6246 * icons, etc. These are often shipped as files in `$datadir/appname`, or
6247 * manually included as literal strings in the code.
6249 * The #GResource API and the [glib-compile-resources][glib-compile-resources] program
6250 * provide a convenient and efficient alternative to this which has some nice properties. You
6251 * maintain the files as normal files, so its easy to edit them, but during the build the files
6252 * are combined into a binary bundle that is linked into the executable. This means that loading
6253 * the resource files are efficient (as they are already in memory, shared with other instances) and
6254 * simple (no need to check for things like I/O errors or locate the files in the filesystem). It
6255 * also makes it easier to create relocatable applications.
6257 * Resource files can also be marked as compressed. Such files will be included in the resource bundle
6258 * in a compressed form, but will be automatically uncompressed when the resource is used. This
6259 * is very useful e.g. for larger text files that are parsed once (or rarely) and then thrown away.
6261 * Resource files can also be marked to be preprocessed, by setting the value of the
6262 * `preprocess` attribute to a comma-separated list of preprocessing options.
6263 * The only options currently supported are:
6265 * `xml-stripblanks` which will use the xmllint command
6266 * to strip ignorable whitespace from the xml file. For this to work,
6267 * the `XMLLINT` environment variable must be set to the full path to
6268 * the xmllint executable, or xmllint must be in the `PATH`; otherwise
6269 * the preprocessing step is skipped.
6271 * `to-pixdata` which will use the gdk-pixbuf-pixdata command to convert
6272 * images to the GdkPixdata format, which allows you to create pixbufs directly using the data inside
6273 * the resource file, rather than an (uncompressed) copy if it. For this, the gdk-pixbuf-pixdata
6274 * program must be in the PATH, or the `GDK_PIXBUF_PIXDATA` environment variable must be
6275 * set to the full path to the gdk-pixbuf-pixdata executable; otherwise the resource compiler will
6278 * Resource bundles are created by the [glib-compile-resources][glib-compile-resources] program
6279 * which takes an xml file that describes the bundle, and a set of files that the xml references. These
6280 * are combined into a binary resource bundle.
6282 * An example resource description:
6284 * <?xml version="1.0" encoding="UTF-8"?>
6286 * <gresource prefix="/org/gtk/Example">
6287 * <file>data/splashscreen.png</file>
6288 * <file compressed="true">dialog.ui</file>
6289 * <file preprocess="xml-stripblanks">menumarkup.xml</file>
6294 * This will create a resource bundle with the following files:
6296 * /org/gtk/Example/data/splashscreen.png
6297 * /org/gtk/Example/dialog.ui
6298 * /org/gtk/Example/menumarkup.xml
6301 * Note that all resources in the process share the same namespace, so use java-style
6302 * path prefixes (like in the above example) to avoid conflicts.
6304 * You can then use [glib-compile-resources][glib-compile-resources] to compile the xml to a
6305 * binary bundle that you can load with g_resource_load(). However, its more common to use the --generate-source and
6306 * --generate-header arguments to create a source file and header to link directly into your application.
6308 * Once a #GResource has been created and registered all the data in it can be accessed globally in the process by
6309 * using API calls like g_resources_open_stream() to stream the data or g_resources_lookup_data() to get a direct pointer
6310 * to the data. You can also use uris like "resource:///org/gtk/Example/data/splashscreen.png" with #GFile to access
6311 * the resource data.
6313 * There are two forms of the generated source, the default version uses the compiler support for constructor
6314 * and destructor functions (where available) to automatically create and register the #GResource on startup
6315 * or library load time. If you pass --manual-register two functions to register/unregister the resource is instead
6316 * created. This requires an explicit initialization call in your application/library, but it works on all platforms,
6317 * even on the minor ones where this is not available. (Constructor support is available for at least Win32, MacOS and Linux.)
6319 * Note that resource data can point directly into the data segment of e.g. a library, so if you are unloading libraries
6320 * during runtime you need to be very careful with keeping around pointers to data from a resource, as this goes away
6321 * when the library is unloaded. However, in practice this is not generally a problem, since most resource accesses
6322 * is for your own resources, and resource data is often used once, during parsing, and then released.
6330 * @short_description: Stream seeking interface
6331 * @include: gio/gio.h
6332 * @see_also: #GInputStream, #GOutputStream
6334 * #GSeekable is implemented by streams (implementations of
6335 * #GInputStream or #GOutputStream) that support seeking.
6337 * Seekable streams largely fall into two categories: resizable and
6340 * #GSeekable on fixed-sized streams is approximately the same as POSIX
6341 * lseek() on a block device (for example: attmepting to seek past the
6342 * end of the device is an error). Fixed streams typically cannot be
6345 * #GSeekable on resizable streams is approximately the same as POSIX
6346 * lseek() on a normal file. Seeking past the end and writing data will
6347 * usually cause the stream to resize by introducing zero bytes.
6353 * @short_description: High-level API for application settings
6354 * @include: gio/gio.h
6356 * The #GSettings class provides a convenient API for storing and retrieving
6357 * application settings.
6359 * Reads and writes can be considered to be non-blocking. Reading
6360 * settings with #GSettings is typically extremely fast: on
6361 * approximately the same order of magnitude (but slower than) a
6362 * #GHashTable lookup. Writing settings is also extremely fast in terms
6363 * of time to return to your application, but can be extremely expensive
6364 * for other threads and other processes. Many settings backends
6365 * (including dconf) have lazy initialisation which means in the common
6366 * case of the user using their computer without modifying any settings
6367 * a lot of work can be avoided. For dconf, the D-Bus service doesn't
6368 * even need to be started in this case. For this reason, you should
6369 * only ever modify #GSettings keys in response to explicit user action.
6370 * Particular care should be paid to ensure that modifications are not
6371 * made during startup -- for example, when setting the initial value
6372 * of preferences widgets. The built-in g_settings_bind() functionality
6373 * is careful not to write settings in response to notify signals as a
6374 * result of modifications that it makes to widgets.
6376 * When creating a GSettings instance, you have to specify a schema
6377 * that describes the keys in your settings and their types and default
6378 * values, as well as some other information.
6380 * Normally, a schema has as fixed path that determines where the settings
6381 * are stored in the conceptual global tree of settings. However, schemas
6382 * can also be 'relocatable', i.e. not equipped with a fixed path. This is
6383 * useful e.g. when the schema describes an 'account', and you want to be
6384 * able to store a arbitrary number of accounts.
6386 * Paths must start with and end with a forward slash character ('/')
6387 * and must not contain two sequential slash characters. Paths should
6388 * be chosen based on a domain name associated with the program or
6389 * library to which the settings belong. Examples of paths are
6390 * "/org/gtk/settings/file-chooser/" and "/ca/desrt/dconf-editor/".
6391 * Paths should not start with "/apps/", "/desktop/" or "/system/" as
6392 * they often did in GConf.
6394 * Unlike other configuration systems (like GConf), GSettings does not
6395 * restrict keys to basic types like strings and numbers. GSettings stores
6396 * values as #GVariant, and allows any #GVariantType for keys. Key names
6397 * are restricted to lowercase characters, numbers and '-'. Furthermore,
6398 * the names must begin with a lowercase character, must not end
6399 * with a '-', and must not contain consecutive dashes.
6401 * Similar to GConf, the default values in GSettings schemas can be
6402 * localized, but the localized values are stored in gettext catalogs
6403 * and looked up with the domain that is specified in the
6404 * gettext-domain attribute of the <schemalist> or <schema>
6405 * elements and the category that is specified in the l10n attribute of
6406 * the <key> element.
6408 * GSettings uses schemas in a compact binary form that is created
6409 * by the [glib-compile-schemas][glib-compile-schemas]
6410 * utility. The input is a schema description in an XML format.
6412 * A DTD for the gschema XML format can be found here:
6413 * [gschema.dtd](https://git.gnome.org/browse/glib/tree/gio/gschema.dtd)
6415 * The [glib-compile-schemas][glib-compile-schemas] tool expects schema
6416 * files to have the extension `.gschema.xml`.
6418 * At runtime, schemas are identified by their id (as specified in the
6419 * id attribute of the <schema> element). The convention for schema
6420 * ids is to use a dotted name, similar in style to a D-Bus bus name,
6421 * e.g. "org.gnome.SessionManager". In particular, if the settings are
6422 * for a specific service that owns a D-Bus bus name, the D-Bus bus name
6423 * and schema id should match. For schemas which deal with settings not
6424 * associated with one named application, the id should not use
6425 * StudlyCaps, e.g. "org.gnome.font-rendering".
6427 * In addition to #GVariant types, keys can have types that have
6428 * enumerated types. These can be described by a <choice>,
6429 * <enum> or <flags> element, as seen in the
6430 * [example][schema-enumerated]. The underlying type of such a key
6431 * is string, but you can use g_settings_get_enum(), g_settings_set_enum(),
6432 * g_settings_get_flags(), g_settings_set_flags() access the numeric values
6433 * corresponding to the string value of enum and flags keys.
6435 * An example for default value:
6438 * <schema id="org.gtk.Test" path="/org/gtk/Test/" gettext-domain="test">
6440 * <key name="greeting" type="s">
6441 * <default l10n="messages">"Hello, earthlings"</default>
6442 * <summary>A greeting</summary>
6444 * Greeting of the invading martians
6448 * <key name="box" type="(ii)">
6449 * <default>(20,30)</default>
6456 * An example for ranges, choices and enumerated types:
6460 * <enum id="org.gtk.Test.myenum">
6461 * <value nick="first" value="1"/>
6462 * <value nick="second" value="2"/>
6465 * <flags id="org.gtk.Test.myflags">
6466 * <value nick="flag1" value="1"/>
6467 * <value nick="flag2" value="2"/>
6468 * <value nick="flag3" value="4"/>
6471 * <schema id="org.gtk.Test">
6473 * <key name="key-with-range" type="i">
6474 * <range min="1" max="100"/>
6475 * <default>10</default>
6478 * <key name="key-with-choices" type="s">
6480 * <choice value='Elisabeth'/>
6481 * <choice value='Annabeth'/>
6482 * <choice value='Joe'/>
6485 * <alias value='Anna' target='Annabeth'/>
6486 * <alias value='Beth' target='Elisabeth'/>
6488 * <default>'Joe'</default>
6491 * <key name='enumerated-key' enum='org.gtk.Test.myenum'>
6492 * <default>'first'</default>
6495 * <key name='flags-key' flags='org.gtk.Test.myflags'>
6496 * <default>["flag1",flag2"]</default>
6502 * ## Vendor overrides
6504 * Default values are defined in the schemas that get installed by
6505 * an application. Sometimes, it is necessary for a vendor or distributor
6506 * to adjust these defaults. Since patching the XML source for the schema
6507 * is inconvenient and error-prone,
6508 * [glib-compile-schemas][glib-compile-schemas] reads so-called vendor
6509 * override' files. These are keyfiles in the same directory as the XML
6510 * schema sources which can override default values. The schema id serves
6511 * as the group name in the key file, and the values are expected in
6512 * serialized GVariant form, as in the following example:
6519 * glib-compile-schemas expects schema files to have the extension
6520 * `.gschema.override`.
6524 * A very convenient feature of GSettings lets you bind #GObject properties
6525 * directly to settings, using g_settings_bind(). Once a GObject property
6526 * has been bound to a setting, changes on either side are automatically
6527 * propagated to the other side. GSettings handles details like mapping
6528 * between GObject and GVariant types, and preventing infinite cycles.
6530 * This makes it very easy to hook up a preferences dialog to the
6531 * underlying settings. To make this even more convenient, GSettings
6532 * looks for a boolean property with the name "sensitivity" and
6533 * automatically binds it to the writability of the bound setting.
6534 * If this 'magic' gets in the way, it can be suppressed with the
6535 * #G_SETTINGS_BIND_NO_SENSITIVITY flag.
6540 * SECTION:gsettingsbackend
6541 * @title: GSettingsBackend
6542 * @short_description: Interface for settings backend implementations
6543 * @include: gio/gsettingsbackend.h
6544 * @see_also: #GSettings, #GIOExtensionPoint
6546 * The #GSettingsBackend interface defines a generic interface for
6547 * non-strictly-typed data that is stored in a hierarchy. To implement
6548 * an alternative storage backend for #GSettings, you need to implement
6549 * the #GSettingsBackend interface and then make it implement the
6550 * extension point #G_SETTINGS_BACKEND_EXTENSION_POINT_NAME.
6552 * The interface defines methods for reading and writing values, a
6553 * method for determining if writing of certain values will fail
6554 * (lockdown) and a change notification mechanism.
6556 * The semantics of the interface are very precisely defined and
6557 * implementations must carefully adhere to the expectations of
6558 * callers that are documented on each of the interface methods.
6560 * Some of the GSettingsBackend functions accept or return a #GTree.
6561 * These trees always have strings as keys and #GVariant as values.
6562 * g_settings_backend_create_tree() is a convenience function to create
6565 * The GSettingsBackend API is exported to allow third-party
6566 * implementations, but does not carry the same stability guarantees
6567 * as the public GIO API. For this reason, you have to define the
6568 * C preprocessor symbol %G_SETTINGS_ENABLE_BACKEND before including
6569 * `gio/gsettingsbackend.h`.
6574 * SECTION:gsettingsschema
6575 * @short_description: Introspecting and controlling the loading
6576 * of GSettings schemas
6577 * @include: gio/gio.h
6579 * The #GSettingsSchemaSource and #GSettingsSchema APIs provide a
6580 * mechanism for advanced control over the loading of schemas and a
6581 * mechanism for introspecting their content.
6583 * Plugin loading systems that wish to provide plugins a way to access
6584 * settings face the problem of how to make the schemas for these
6585 * settings visible to GSettings. Typically, a plugin will want to ship
6586 * the schema along with itself and it won't be installed into the
6587 * standard system directories for schemas.
6589 * #GSettingsSchemaSource provides a mechanism for dealing with this by
6590 * allowing the creation of a new 'schema source' from which schemas can
6591 * be acquired. This schema source can then become part of the metadata
6592 * associated with the plugin and queried whenever the plugin requires
6593 * access to some settings.
6595 * Consider the following example:
6597 * |[<!-- language="C" -->
6601 * GSettingsSchemaSource *schema_source;
6606 * initialise_plugin (const gchar *dir)
6612 * plugin->schema_source =
6613 * g_settings_new_schema_source_from_directory (dir,
6614 * g_settings_schema_source_get_default (), FALSE, NULL);
6624 * plugin_get_settings (Plugin *plugin,
6625 * const gchar *schema_id)
6627 * GSettingsSchema *schema;
6629 * if (schema_id == NULL)
6630 * schema_id = plugin->identifier;
6632 * schema = g_settings_schema_source_lookup (plugin->schema_source,
6633 * schema_id, FALSE);
6635 * if (schema == NULL)
6637 * ... disable the plugin or abort, etc ...
6640 * return g_settings_new_full (schema, NULL, NULL);
6644 * The code above shows how hooks should be added to the code that
6645 * initialises (or enables) the plugin to create the schema source and
6646 * how an API can be added to the plugin system to provide a convenient
6647 * way for the plugin to access its settings, using the schemas that it
6650 * From the standpoint of the plugin, it would need to ensure that it
6651 * ships a gschemas.compiled file as part of itself, and then simply do
6654 * |[<!-- language="C" -->
6656 * GSettings *settings;
6659 * settings = plugin_get_settings (self, NULL);
6660 * some_value = g_settings_get_int (settings, "some-value");
6665 * It's also possible that the plugin system expects the schema source
6666 * files (ie: .gschema.xml files) instead of a gschemas.compiled file.
6667 * In that case, the plugin loading system must compile the schemas for
6668 * itself before attempting to create the settings source.
6675 * SECTION:gsimpleaction
6676 * @title: GSimpleAction
6677 * @short_description: A simple GAction implementation
6678 * @include: gio/gio.h
6680 * A #GSimpleAction is the obvious simple implementation of the #GAction
6681 * interface. This is the easiest way to create an action for purposes of
6682 * adding it to a #GSimpleActionGroup.
6684 * See also #GtkAction.
6689 * SECTION:gsimpleactiongroup
6690 * @title: GSimpleActionGroup
6691 * @short_description: A simple GActionGroup implementation
6692 * @include: gio/gio.h
6694 * #GSimpleActionGroup is a hash table filled with #GAction objects,
6695 * implementing the #GActionGroup and #GActionMap interfaces.
6700 * SECTION:gsimpleasyncresult
6701 * @short_description: Simple asynchronous results implementation
6702 * @include: gio/gio.h
6703 * @see_also: #GAsyncResult, #GTask
6705 * As of GLib 2.36, #GSimpleAsyncResult is deprecated in favor of
6706 * #GTask, which provides a simpler API.
6708 * #GSimpleAsyncResult implements #GAsyncResult.
6710 * GSimpleAsyncResult handles #GAsyncReadyCallbacks, error
6711 * reporting, operation cancellation and the final state of an operation,
6712 * completely transparent to the application. Results can be returned
6713 * as a pointer e.g. for functions that return data that is collected
6714 * asynchronously, a boolean value for checking the success or failure
6715 * of an operation, or a #gssize for operations which return the number
6716 * of bytes modified by the operation; all of the simple return cases
6719 * Most of the time, an application will not need to know of the details
6720 * of this API; it is handled transparently, and any necessary operations
6721 * are handled by #GAsyncResult's interface. However, if implementing a
6722 * new GIO module, for writing language bindings, or for complex
6723 * applications that need better control of how asynchronous operations
6724 * are completed, it is important to understand this functionality.
6726 * GSimpleAsyncResults are tagged with the calling function to ensure
6727 * that asynchronous functions and their finishing functions are used
6728 * together correctly.
6730 * To create a new #GSimpleAsyncResult, call g_simple_async_result_new().
6731 * If the result needs to be created for a #GError, use
6732 * g_simple_async_result_new_from_error() or
6733 * g_simple_async_result_new_take_error(). If a #GError is not available
6734 * (e.g. the asynchronous operation's doesn't take a #GError argument),
6735 * but the result still needs to be created for an error condition, use
6736 * g_simple_async_result_new_error() (or g_simple_async_result_set_error_va()
6737 * if your application or binding requires passing a variable argument list
6738 * directly), and the error can then be propagated through the use of
6739 * g_simple_async_result_propagate_error().
6741 * An asynchronous operation can be made to ignore a cancellation event by
6742 * calling g_simple_async_result_set_handle_cancellation() with a
6743 * #GSimpleAsyncResult for the operation and %FALSE. This is useful for
6744 * operations that are dangerous to cancel, such as close (which would
6745 * cause a leak if cancelled before being run).
6747 * GSimpleAsyncResult can integrate into GLib's event loop, #GMainLoop,
6748 * or it can use #GThreads.
6749 * g_simple_async_result_complete() will finish an I/O task directly
6750 * from the point where it is called. g_simple_async_result_complete_in_idle()
6751 * will finish it from an idle handler in the
6752 * [thread-default main context][g-main-context-push-thread-default]
6753 * . g_simple_async_result_run_in_thread() will run the
6754 * job in a separate thread and then deliver the result to the
6755 * thread-default main context.
6757 * To set the results of an asynchronous function,
6758 * g_simple_async_result_set_op_res_gpointer(),
6759 * g_simple_async_result_set_op_res_gboolean(), and
6760 * g_simple_async_result_set_op_res_gssize()
6761 * are provided, setting the operation's result to a gpointer, gboolean, or
6762 * gssize, respectively.
6764 * Likewise, to get the result of an asynchronous function,
6765 * g_simple_async_result_get_op_res_gpointer(),
6766 * g_simple_async_result_get_op_res_gboolean(), and
6767 * g_simple_async_result_get_op_res_gssize() are
6768 * provided, getting the operation's result as a gpointer, gboolean, and
6769 * gssize, respectively.
6771 * For the details of the requirements implementations must respect, see
6772 * #GAsyncResult. A typical implementation of an asynchronous operation
6773 * using GSimpleAsyncResult looks something like this:
6775 * |[<!-- language="C" -->
6777 * baked_cb (Cake *cake,
6778 * gpointer user_data)
6780 * // In this example, this callback is not given a reference to the cake,
6781 * // so the GSimpleAsyncResult has to take a reference to it.
6782 * GSimpleAsyncResult *result = user_data;
6785 * g_simple_async_result_set_error (result,
6787 * BAKER_ERROR_NO_FLOUR,
6788 * "Go to the supermarket");
6790 * g_simple_async_result_set_op_res_gpointer (result,
6791 * g_object_ref (cake),
6795 * // In this example, we assume that baked_cb is called as a callback from
6796 * // the mainloop, so it's safe to complete the operation synchronously here.
6797 * // If, however, _baker_prepare_cake () might call its callback without
6798 * // first returning to the mainloop — inadvisable, but some APIs do so —
6799 * // we would need to use g_simple_async_result_complete_in_idle().
6800 * g_simple_async_result_complete (result);
6801 * g_object_unref (result);
6805 * baker_bake_cake_async (Baker *self,
6807 * GAsyncReadyCallback callback,
6808 * gpointer user_data)
6810 * GSimpleAsyncResult *simple;
6815 * g_simple_async_report_error_in_idle (G_OBJECT (self),
6819 * BAKER_ERROR_TOO_SMALL,
6820 * "%ucm radius cakes are silly",
6825 * simple = g_simple_async_result_new (G_OBJECT (self),
6828 * baker_bake_cake_async);
6829 * cake = _baker_get_cached_cake (self, radius);
6833 * g_simple_async_result_set_op_res_gpointer (simple,
6834 * g_object_ref (cake),
6836 * g_simple_async_result_complete_in_idle (simple);
6837 * g_object_unref (simple);
6838 * // Drop the reference returned by _baker_get_cached_cake();
6839 * // the GSimpleAsyncResult has taken its own reference.
6840 * g_object_unref (cake);
6844 * _baker_prepare_cake (self, radius, baked_cb, simple);
6848 * baker_bake_cake_finish (Baker *self,
6849 * GAsyncResult *result,
6852 * GSimpleAsyncResult *simple;
6855 * g_return_val_if_fail (g_simple_async_result_is_valid (result,
6857 * baker_bake_cake_async),
6860 * simple = (GSimpleAsyncResult *) result;
6862 * if (g_simple_async_result_propagate_error (simple, error))
6865 * cake = CAKE (g_simple_async_result_get_op_res_gpointer (simple));
6866 * return g_object_ref (cake);
6873 * SECTION:gsimplepermission
6874 * @title: GSimplePermission
6875 * @short_description: A GPermission that doesn't change value
6876 * @include: gio/gio.h
6878 * #GSimplePermission is a trivial implementation of #GPermission that
6879 * represents a permission that is either always or never allowed. The
6880 * value is given at construction and doesn't change.
6882 * Calling request or release will result in errors.
6887 * SECTION:gsimpleproxyresolver
6888 * @short_description: Simple proxy resolver implementation
6889 * @include: gio/gio.h
6890 * @see_also: g_socket_client_set_proxy_resolver()
6892 * #GSimpleProxyResolver is a simple #GProxyResolver implementation
6893 * that handles a single default proxy, multiple URI-scheme-specific
6894 * proxies, and a list of hosts that proxies should not be used for.
6896 * #GSimpleProxyResolver is never the default proxy resolver, but it
6897 * can be used as the base class for another proxy resolver
6898 * implementation, or it can be created and used manually, such as
6899 * with g_socket_client_set_proxy_resolver().
6907 * @short_description: Low-level socket object
6908 * @include: gio/gio.h
6909 * @see_also: #GInitable, [<gnetworking.h>][gio-gnetworking.h]
6911 * A #GSocket is a low-level networking primitive. It is a more or less
6912 * direct mapping of the BSD socket API in a portable GObject based API.
6913 * It supports both the UNIX socket implementations and winsock2 on Windows.
6915 * #GSocket is the platform independent base upon which the higher level
6916 * network primitives are based. Applications are not typically meant to
6917 * use it directly, but rather through classes like #GSocketClient,
6918 * #GSocketService and #GSocketConnection. However there may be cases where
6919 * direct use of #GSocket is useful.
6921 * #GSocket implements the #GInitable interface, so if it is manually constructed
6922 * by e.g. g_object_new() you must call g_initable_init() and check the
6923 * results before using the object. This is done automatically in
6924 * g_socket_new() and g_socket_new_from_fd(), so these functions can return
6927 * Sockets operate in two general modes, blocking or non-blocking. When
6928 * in blocking mode all operations block until the requested operation
6929 * is finished or there is an error. In non-blocking mode all calls that
6930 * would block return immediately with a %G_IO_ERROR_WOULD_BLOCK error.
6931 * To know when a call would successfully run you can call g_socket_condition_check(),
6932 * or g_socket_condition_wait(). You can also use g_socket_create_source() and
6933 * attach it to a #GMainContext to get callbacks when I/O is possible.
6934 * Note that all sockets are always set to non blocking mode in the system, and
6935 * blocking mode is emulated in GSocket.
6937 * When working in non-blocking mode applications should always be able to
6938 * handle getting a %G_IO_ERROR_WOULD_BLOCK error even when some other
6939 * function said that I/O was possible. This can easily happen in case
6940 * of a race condition in the application, but it can also happen for other
6941 * reasons. For instance, on Windows a socket is always seen as writable
6942 * until a write returns %G_IO_ERROR_WOULD_BLOCK.
6944 * #GSockets can be either connection oriented or datagram based.
6945 * For connection oriented types you must first establish a connection by
6946 * either connecting to an address or accepting a connection from another
6947 * address. For connectionless socket types the target/source address is
6948 * specified or received in each I/O operation.
6950 * All socket file descriptors are set to be close-on-exec.
6952 * Note that creating a #GSocket causes the signal %SIGPIPE to be
6953 * ignored for the remainder of the program. If you are writing a
6954 * command-line utility that uses #GSocket, you may need to take into
6955 * account the fact that your program will not automatically be killed
6956 * if it tries to write to %stdout after it has been closed.
6958 * Like most other APIs in GLib, #GSocket is not inherently thread safe. To use
6959 * a #GSocket concurrently from multiple threads, you must implement your own
6967 * SECTION:gsocketaddress
6968 * @short_description: Abstract base class representing endpoints
6969 * for socket communication
6970 * @include: gio/gio.h
6972 * #GSocketAddress is the equivalent of struct sockaddr in the BSD
6973 * sockets API. This is an abstract class; use #GInetSocketAddress
6974 * for internet sockets, or #GUnixSocketAddress for UNIX domain sockets.
6979 * SECTION:gsocketclient
6980 * @short_description: Helper for connecting to a network service
6981 * @include: gio/gio.h
6982 * @see_also: #GSocketConnection, #GSocketListener
6984 * #GSocketClient is a lightweight high-level utility class for connecting to
6985 * a network host using a connection oriented socket type.
6987 * You create a #GSocketClient object, set any options you want, and then
6988 * call a sync or async connect operation, which returns a #GSocketConnection
6989 * subclass on success.
6991 * The type of the #GSocketConnection object returned depends on the type of
6992 * the underlying socket that is in use. For instance, for a TCP/IP connection
6993 * it will be a #GTcpConnection.
6995 * As #GSocketClient is a lightweight object, you don't need to cache it. You
6996 * can just create a new one any time you need one.
7003 * SECTION:gsocketconnectable
7004 * @short_description: Interface for potential socket endpoints
7005 * @include: gio/gio.h
7007 * Objects that describe one or more potential socket endpoints
7008 * implement #GSocketConnectable. Callers can then use
7009 * g_socket_connectable_enumerate() to get a #GSocketAddressEnumerator
7010 * to try out each socket address in turn until one succeeds, as shown
7011 * in the sample code below.
7013 * |[<!-- language="C" -->
7014 * MyConnectionType *
7015 * connect_to_host (const char *hostname,
7017 * GCancellable *cancellable,
7020 * MyConnection *conn = NULL;
7021 * GSocketConnectable *addr;
7022 * GSocketAddressEnumerator *enumerator;
7023 * GSocketAddress *sockaddr;
7024 * GError *conn_error = NULL;
7026 * addr = g_network_address_new (hostname, port);
7027 * enumerator = g_socket_connectable_enumerate (addr);
7028 * g_object_unref (addr);
7030 * // Try each sockaddr until we succeed. Record the first connection error,
7031 * // but not any further ones (since they'll probably be basically the same
7033 * while (!conn && (sockaddr = g_socket_address_enumerator_next (enumerator, cancellable, error))
7035 * conn = connect_to_sockaddr (sockaddr, conn_error ? NULL : &conn_error);
7036 * g_object_unref (sockaddr);
7038 * g_object_unref (enumerator);
7044 * // We couldn't connect to the first address, but we succeeded
7045 * // in connecting to a later address.
7046 * g_error_free (conn_error);
7052 * /// Either initial lookup failed, or else the caller cancelled us.
7054 * g_error_free (conn_error);
7059 * g_error_propagate (error, conn_error);
7068 * SECTION:gsocketconnection
7069 * @short_description: A socket connection
7070 * @include: gio/gio.h
7071 * @see_also: #GIOStream, #GSocketClient, #GSocketListener
7073 * #GSocketConnection is a #GIOStream for a connected socket. They
7074 * can be created either by #GSocketClient when connecting to a host,
7075 * or by #GSocketListener when accepting a new client.
7077 * The type of the #GSocketConnection object returned from these calls
7078 * depends on the type of the underlying socket that is in use. For
7079 * instance, for a TCP/IP connection it will be a #GTcpConnection.
7081 * Choosing what type of object to construct is done with the socket
7082 * connection factory, and it is possible for 3rd parties to register
7083 * custom socket connection types for specific combination of socket
7084 * family/type/protocol using g_socket_connection_factory_register_type().
7086 * To close a #GSocketConnection, use g_io_stream_close(). Closing both
7087 * substreams of the #GIOStream separately will not close the underlying
7095 * SECTION:gsocketcontrolmessage
7096 * @title: GSocketControlMessage
7097 * @short_description: A GSocket control message
7098 * @include: gio/gio.h
7099 * @see_also: #GSocket.
7101 * A #GSocketControlMessage is a special-purpose utility message that
7102 * can be sent to or received from a #GSocket. These types of
7103 * messages are often called "ancillary data".
7105 * The message can represent some sort of special instruction to or
7106 * information from the socket or can represent a special kind of
7107 * transfer to the peer (for example, sending a file descriptor over
7110 * These messages are sent with g_socket_send_message() and received
7111 * with g_socket_receive_message().
7113 * To extend the set of control message that can be sent, subclass this
7114 * class and override the get_size, get_level, get_type and serialize
7117 * To extend the set of control messages that can be received, subclass
7118 * this class and implement the deserialize method. Also, make sure your
7119 * class is registered with the GType typesystem before calling
7120 * g_socket_receive_message() to read such a message.
7127 * SECTION:gsocketlistener
7128 * @title: GSocketListener
7129 * @short_description: Helper for accepting network client connections
7130 * @include: gio/gio.h
7131 * @see_also: #GThreadedSocketService, #GSocketService.
7133 * A #GSocketListener is an object that keeps track of a set
7134 * of server sockets and helps you accept sockets from any of the
7135 * socket, either sync or async.
7137 * If you want to implement a network server, also look at #GSocketService
7138 * and #GThreadedSocketService which are subclass of #GSocketListener
7139 * that makes this even easier.
7146 * SECTION:gsocketservice
7147 * @title: GSocketService
7148 * @short_description: Make it easy to implement a network service
7149 * @include: gio/gio.h
7150 * @see_also: #GThreadedSocketService, #GSocketListener.
7152 * A #GSocketService is an object that represents a service that
7153 * is provided to the network or over local sockets. When a new
7154 * connection is made to the service the #GSocketService::incoming
7155 * signal is emitted.
7157 * A #GSocketService is a subclass of #GSocketListener and you need
7158 * to add the addresses you want to accept connections on with the
7159 * #GSocketListener APIs.
7161 * There are two options for implementing a network service based on
7162 * #GSocketService. The first is to create the service using
7163 * g_socket_service_new() and to connect to the #GSocketService::incoming
7164 * signal. The second is to subclass #GSocketService and override the
7165 * default signal handler implementation.
7167 * In either case, the handler must immediately return, or else it
7168 * will block additional incoming connections from being serviced.
7169 * If you are interested in writing connection handlers that contain
7170 * blocking code then see #GThreadedSocketService.
7172 * The socket service runs on the main loop of the
7173 * [thread-default context][g-main-context-push-thread-default-context]
7174 * of the thread it is created in, and is not
7175 * threadsafe in general. However, the calls to start and stop the
7176 * service are thread-safe so these can be used from threads that
7177 * handle incoming clients.
7184 * SECTION:gsrvtarget
7185 * @short_description: DNS SRV record target
7186 * @include: gio/gio.h
7188 * SRV (service) records are used by some network protocols to provide
7189 * service-specific aliasing and load-balancing. For example, XMPP
7190 * (Jabber) uses SRV records to locate the XMPP server for a domain;
7191 * rather than connecting directly to "example.com" or assuming a
7192 * specific server hostname like "xmpp.example.com", an XMPP client
7193 * would look up the "xmpp-client" SRV record for "example.com", and
7194 * then connect to whatever host was pointed to by that record.
7196 * You can use g_resolver_lookup_service() or
7197 * g_resolver_lookup_service_async() to find the #GSrvTargets
7198 * for a given service. However, if you are simply planning to connect
7199 * to the remote service, you can use #GNetworkService's
7200 * #GSocketConnectable interface and not need to worry about
7201 * #GSrvTarget at all.
7206 * SECTION:gsubprocess
7207 * @title: GSubprocess
7208 * @short_description: Child processes
7209 * @include: gio/gio.h
7210 * @see_also: #GSubprocessLauncher
7212 * #GSubprocess allows the creation of and interaction with child
7215 * Processes can be communicated with using standard GIO-style APIs (ie:
7216 * #GInputStream, #GOutputStream). There are GIO-style APIs to wait for
7217 * process termination (ie: cancellable and with an asynchronous
7220 * There is an API to force a process to terminate, as well as a
7221 * race-free API for sending UNIX signals to a subprocess.
7223 * One major advantage that GIO brings over the core GLib library is
7224 * comprehensive API for asynchronous I/O, such
7225 * g_output_stream_splice_async(). This makes GSubprocess
7226 * significantly more powerful and flexible than equivalent APIs in
7227 * some other languages such as the `subprocess.py`
7228 * included with Python. For example, using #GSubprocess one could
7229 * create two child processes, reading standard output from the first,
7230 * processing it, and writing to the input stream of the second, all
7231 * without blocking the main loop.
7233 * A powerful g_subprocess_communicate() API is provided similar to the
7234 * `communicate()` method of `subprocess.py`. This enables very easy
7235 * interaction with a subprocess that has been opened with pipes.
7237 * #GSubprocess defaults to tight control over the file descriptors open
7238 * in the child process, avoiding dangling-fd issues that are caused by
7239 * a simple fork()/exec(). The only open file descriptors in the
7240 * spawned process are ones that were explicitly specified by the
7241 * #GSubprocess API (unless %G_SUBPROCESS_FLAGS_INHERIT_FDS was
7244 * #GSubprocess will quickly reap all child processes as they exit,
7245 * avoiding "zombie processes" remaining around for long periods of
7246 * time. g_subprocess_wait() can be used to wait for this to happen,
7247 * but it will happen even without the call being explicitly made.
7249 * As a matter of principle, #GSubprocess has no API that accepts
7250 * shell-style space-separated strings. It will, however, match the
7251 * typical shell behaviour of searching the PATH for executables that do
7252 * not contain a directory separator in their name.
7254 * #GSubprocess attempts to have a very simple API for most uses (ie:
7255 * spawning a subprocess with arguments and support for most typical
7256 * kinds of input and output redirection). See g_subprocess_new(). The
7257 * #GSubprocessLauncher API is provided for more complicated cases
7258 * (advanced types of redirection, environment variable manipulation,
7259 * change of working directory, child setup functions, etc).
7261 * A typical use of #GSubprocess will involve calling
7262 * g_subprocess_new(), followed by g_subprocess_wait_async() or
7263 * g_subprocess_wait(). After the process exits, the status can be
7264 * checked using functions such as g_subprocess_get_if_exited() (which
7265 * are similar to the familiar WIFEXITED-style POSIX macros).
7272 * SECTION:gsubprocesslauncher
7273 * @title: GSubprocess Launcher
7274 * @short_description: Environment options for launching a child process
7275 * @include: gio/gio.h
7277 * This class contains a set of options for launching child processes,
7278 * such as where its standard input and output will be directed, the
7279 * argument list, the environment, and more.
7281 * While the #GSubprocess class has high level functions covering
7282 * popular cases, use of this class allows access to more advanced
7283 * options. It can also be used to launch multiple subprocesses with
7284 * a similar configuration.
7292 * @short_description: Cancellable synchronous or asynchronous task
7294 * @include: gio/gio.h
7295 * @see_also: #GAsyncResult
7297 * A #GTask represents and manages a cancellable "task".
7299 * ## Asynchronous operations
7301 * The most common usage of #GTask is as a #GAsyncResult, to
7302 * manage data during an asynchronous operation. You call
7303 * g_task_new() in the "start" method, followed by
7304 * g_task_set_task_data() and the like if you need to keep some
7305 * additional data associated with the task, and then pass the
7306 * task object around through your asynchronous operation.
7307 * Eventually, you will call a method such as
7308 * g_task_return_pointer() or g_task_return_error(), which will
7309 * save the value you give it and then invoke the task's callback
7310 * function (waiting until the next iteration of the main
7311 * loop first, if necessary). The caller will pass the #GTask back
7312 * to the operation's finish function (as a #GAsyncResult), and
7313 * you can use g_task_propagate_pointer() or the like to extract
7316 * Here is an example for using GTask as a GAsyncResult:
7317 * |[<!-- language="C" -->
7319 * CakeFrostingType frosting;
7324 * decoration_data_free (DecorationData *decoration)
7326 * g_free (decoration->message);
7327 * g_slice_free (DecorationData, decoration);
7331 * baked_cb (Cake *cake,
7332 * gpointer user_data)
7334 * GTask *task = user_data;
7335 * DecorationData *decoration = g_task_get_task_data (task);
7336 * GError *error = NULL;
7340 * g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_NO_FLOUR,
7341 * "Go to the supermarket");
7342 * g_object_unref (task);
7346 * if (!cake_decorate (cake, decoration->frosting, decoration->message, &error))
7348 * g_object_unref (cake);
7349 * // g_task_return_error() takes ownership of error
7350 * g_task_return_error (task, error);
7351 * g_object_unref (task);
7355 * g_task_return_pointer (task, cake, g_object_unref);
7356 * g_object_unref (task);
7360 * baker_bake_cake_async (Baker *self,
7362 * CakeFlavor flavor,
7363 * CakeFrostingType frosting,
7364 * const char *message,
7365 * GCancellable *cancellable,
7366 * GAsyncReadyCallback callback,
7367 * gpointer user_data)
7370 * DecorationData *decoration;
7373 * task = g_task_new (self, cancellable, callback, user_data);
7376 * g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_TOO_SMALL,
7377 * "%ucm radius cakes are silly",
7379 * g_object_unref (task);
7383 * cake = _baker_get_cached_cake (self, radius, flavor, frosting, message);
7386 * // _baker_get_cached_cake() returns a reffed cake
7387 * g_task_return_pointer (task, cake, g_object_unref);
7388 * g_object_unref (task);
7392 * decoration = g_slice_new (DecorationData);
7393 * decoration->frosting = frosting;
7394 * decoration->message = g_strdup (message);
7395 * g_task_set_task_data (task, decoration, (GDestroyNotify) decoration_data_free);
7397 * _baker_begin_cake (self, radius, flavor, cancellable, baked_cb, task);
7401 * baker_bake_cake_finish (Baker *self,
7402 * GAsyncResult *result,
7405 * g_return_val_if_fail (g_task_is_valid (result, self), NULL);
7407 * return g_task_propagate_pointer (G_TASK (result), error);
7411 * ## Chained asynchronous operations
7413 * #GTask also tries to simplify asynchronous operations that
7414 * internally chain together several smaller asynchronous
7415 * operations. g_task_get_cancellable(), g_task_get_context(),
7416 * and g_task_get_priority() allow you to get back the task's
7417 * #GCancellable, #GMainContext, and [I/O priority][io-priority]
7418 * when starting a new subtask, so you don't have to keep track
7419 * of them yourself. g_task_attach_source() simplifies the case
7420 * of waiting for a source to fire (automatically using the correct
7421 * #GMainContext and priority).
7423 * Here is an example for chained asynchronous operations:
7424 * |[<!-- language="C" -->
7427 * CakeFrostingType frosting;
7432 * decoration_data_free (BakingData *bd)
7435 * g_object_unref (bd->cake);
7436 * g_free (bd->message);
7437 * g_slice_free (BakingData, bd);
7441 * decorated_cb (Cake *cake,
7442 * GAsyncResult *result,
7443 * gpointer user_data)
7445 * GTask *task = user_data;
7446 * GError *error = NULL;
7448 * if (!cake_decorate_finish (cake, result, &error))
7450 * g_object_unref (cake);
7451 * g_task_return_error (task, error);
7452 * g_object_unref (task);
7456 * // baking_data_free() will drop its ref on the cake, so we have to
7457 * // take another here to give to the caller.
7458 * g_task_return_pointer (result, g_object_ref (cake), g_object_unref);
7459 * g_object_unref (task);
7463 * decorator_ready (gpointer user_data)
7465 * GTask *task = user_data;
7466 * BakingData *bd = g_task_get_task_data (task);
7468 * cake_decorate_async (bd->cake, bd->frosting, bd->message,
7469 * g_task_get_cancellable (task),
7470 * decorated_cb, task);
7474 * baked_cb (Cake *cake,
7475 * gpointer user_data)
7477 * GTask *task = user_data;
7478 * BakingData *bd = g_task_get_task_data (task);
7479 * GError *error = NULL;
7483 * g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_NO_FLOUR,
7484 * "Go to the supermarket");
7485 * g_object_unref (task);
7491 * // Bail out now if the user has already cancelled
7492 * if (g_task_return_error_if_cancelled (task))
7494 * g_object_unref (task);
7498 * if (cake_decorator_available (cake))
7499 * decorator_ready (task);
7504 * source = cake_decorator_wait_source_new (cake);
7505 * // Attach @source to @task's GMainContext and have it call
7506 * // decorator_ready() when it is ready.
7507 * g_task_attach_source (task, source,
7508 * G_CALLBACK (decorator_ready));
7509 * g_source_unref (source);
7514 * baker_bake_cake_async (Baker *self,
7516 * CakeFlavor flavor,
7517 * CakeFrostingType frosting,
7518 * const char *message,
7520 * GCancellable *cancellable,
7521 * GAsyncReadyCallback callback,
7522 * gpointer user_data)
7527 * task = g_task_new (self, cancellable, callback, user_data);
7528 * g_task_set_priority (task, priority);
7530 * bd = g_slice_new0 (BakingData);
7531 * bd->frosting = frosting;
7532 * bd->message = g_strdup (message);
7533 * g_task_set_task_data (task, bd, (GDestroyNotify) baking_data_free);
7535 * _baker_begin_cake (self, radius, flavor, cancellable, baked_cb, task);
7539 * baker_bake_cake_finish (Baker *self,
7540 * GAsyncResult *result,
7543 * g_return_val_if_fail (g_task_is_valid (result, self), NULL);
7545 * return g_task_propagate_pointer (G_TASK (result), error);
7549 * ## Asynchronous operations from synchronous ones
7551 * You can use g_task_run_in_thread() to turn a synchronous
7552 * operation into an asynchronous one, by running it in a thread
7553 * which will then dispatch the result back to the caller's
7554 * #GMainContext when it completes.
7556 * Running a task in a thread:
7557 * |[<!-- language="C" -->
7560 * CakeFlavor flavor;
7561 * CakeFrostingType frosting;
7566 * cake_data_free (CakeData *cake_data)
7568 * g_free (cake_data->message);
7569 * g_slice_free (CakeData, cake_data);
7573 * bake_cake_thread (GTask *task,
7574 * gpointer source_object,
7575 * gpointer task_data,
7576 * GCancellable *cancellable)
7578 * Baker *self = source_object;
7579 * CakeData *cake_data = task_data;
7581 * GError *error = NULL;
7583 * cake = bake_cake (baker, cake_data->radius, cake_data->flavor,
7584 * cake_data->frosting, cake_data->message,
7585 * cancellable, &error);
7587 * g_task_return_pointer (task, cake, g_object_unref);
7589 * g_task_return_error (task, error);
7593 * baker_bake_cake_async (Baker *self,
7595 * CakeFlavor flavor,
7596 * CakeFrostingType frosting,
7597 * const char *message,
7598 * GCancellable *cancellable,
7599 * GAsyncReadyCallback callback,
7600 * gpointer user_data)
7602 * CakeData *cake_data;
7605 * cake_data = g_slice_new (CakeData);
7606 * cake_data->radius = radius;
7607 * cake_data->flavor = flavor;
7608 * cake_data->frosting = frosting;
7609 * cake_data->message = g_strdup (message);
7610 * task = g_task_new (self, cancellable, callback, user_data);
7611 * g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free);
7612 * g_task_run_in_thread (task, bake_cake_thread);
7613 * g_object_unref (task);
7617 * baker_bake_cake_finish (Baker *self,
7618 * GAsyncResult *result,
7621 * g_return_val_if_fail (g_task_is_valid (result, self), NULL);
7623 * return g_task_propagate_pointer (G_TASK (result), error);
7627 * ## Adding cancellability to uncancellable tasks
7629 * Finally, g_task_run_in_thread() and g_task_run_in_thread_sync()
7630 * can be used to turn an uncancellable operation into a
7631 * cancellable one. If you call g_task_set_return_on_cancel(),
7632 * passing %TRUE, then if the task's #GCancellable is cancelled,
7633 * it will return control back to the caller immediately, while
7634 * allowing the task thread to continue running in the background
7635 * (and simply discarding its result when it finally does finish).
7636 * Provided that the task thread is careful about how it uses
7637 * locks and other externally-visible resources, this allows you
7638 * to make "GLib-friendly" asynchronous and cancellable
7639 * synchronous variants of blocking APIs.
7641 * Cancelling a task:
7642 * |[<!-- language="C" -->
7644 * bake_cake_thread (GTask *task,
7645 * gpointer source_object,
7646 * gpointer task_data,
7647 * GCancellable *cancellable)
7649 * Baker *self = source_object;
7650 * CakeData *cake_data = task_data;
7652 * GError *error = NULL;
7654 * cake = bake_cake (baker, cake_data->radius, cake_data->flavor,
7655 * cake_data->frosting, cake_data->message,
7659 * g_task_return_error (task, error);
7663 * // If the task has already been cancelled, then we don't want to add
7664 * // the cake to the cake cache. Likewise, we don't want to have the
7665 * // task get cancelled in the middle of updating the cache.
7666 * // g_task_set_return_on_cancel() will return %TRUE here if it managed
7667 * // to disable return-on-cancel, or %FALSE if the task was cancelled
7668 * // before it could.
7669 * if (g_task_set_return_on_cancel (task, FALSE))
7671 * // If the caller cancels at this point, their
7672 * // GAsyncReadyCallback won't be invoked until we return,
7673 * // so we don't have to worry that this code will run at
7674 * // the same time as that code does. But if there were
7675 * // other functions that might look at the cake cache,
7676 * // then we'd probably need a GMutex here as well.
7677 * baker_add_cake_to_cache (baker, cake);
7678 * g_task_return_pointer (task, cake, g_object_unref);
7683 * baker_bake_cake_async (Baker *self,
7685 * CakeFlavor flavor,
7686 * CakeFrostingType frosting,
7687 * const char *message,
7688 * GCancellable *cancellable,
7689 * GAsyncReadyCallback callback,
7690 * gpointer user_data)
7692 * CakeData *cake_data;
7695 * cake_data = g_slice_new (CakeData);
7699 * task = g_task_new (self, cancellable, callback, user_data);
7700 * g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free);
7701 * g_task_set_return_on_cancel (task, TRUE);
7702 * g_task_run_in_thread (task, bake_cake_thread);
7706 * baker_bake_cake_sync (Baker *self,
7708 * CakeFlavor flavor,
7709 * CakeFrostingType frosting,
7710 * const char *message,
7711 * GCancellable *cancellable,
7714 * CakeData *cake_data;
7718 * cake_data = g_slice_new (CakeData);
7722 * task = g_task_new (self, cancellable, NULL, NULL);
7723 * g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free);
7724 * g_task_set_return_on_cancel (task, TRUE);
7725 * g_task_run_in_thread_sync (task, bake_cake_thread);
7727 * cake = g_task_propagate_pointer (task, error);
7728 * g_object_unref (task);
7733 * ## Porting from GSimpleAsyncResult
7735 * #GTask's API attempts to be simpler than #GSimpleAsyncResult's
7737 * - You can save task-specific data with g_task_set_task_data(), and
7738 * retrieve it later with g_task_get_task_data(). This replaces the
7739 * abuse of g_simple_async_result_set_op_res_gpointer() for the same
7740 * purpose with #GSimpleAsyncResult.
7741 * - In addition to the task data, #GTask also keeps track of the
7742 * [priority][io-priority], #GCancellable, and
7743 * #GMainContext associated with the task, so tasks that consist of
7744 * a chain of simpler asynchronous operations will have easy access
7745 * to those values when starting each sub-task.
7746 * - g_task_return_error_if_cancelled() provides simplified
7747 * handling for cancellation. In addition, cancellation
7748 * overrides any other #GTask return value by default, like
7749 * #GSimpleAsyncResult does when
7750 * g_simple_async_result_set_check_cancellable() is called.
7751 * (You can use g_task_set_check_cancellable() to turn off that
7752 * behavior.) On the other hand, g_task_run_in_thread()
7753 * guarantees that it will always run your
7754 * `task_func`, even if the task's #GCancellable
7755 * is already cancelled before the task gets a chance to run;
7756 * you can start your `task_func` with a
7757 * g_task_return_error_if_cancelled() check if you need the
7759 * - The "return" methods (eg, g_task_return_pointer())
7760 * automatically cause the task to be "completed" as well, and
7761 * there is no need to worry about the "complete" vs "complete
7762 * in idle" distinction. (#GTask automatically figures out
7763 * whether the task's callback can be invoked directly, or
7764 * if it needs to be sent to another #GMainContext, or delayed
7765 * until the next iteration of the current #GMainContext.)
7766 * - The "finish" functions for #GTask-based operations are generally
7767 * much simpler than #GSimpleAsyncResult ones, normally consisting
7768 * of only a single call to g_task_propagate_pointer() or the like.
7769 * Since g_task_propagate_pointer() "steals" the return value from
7770 * the #GTask, it is not necessary to juggle pointers around to
7771 * prevent it from being freed twice.
7772 * - With #GSimpleAsyncResult, it was common to call
7773 * g_simple_async_result_propagate_error() from the
7774 * `_finish()` wrapper function, and have
7775 * virtual method implementations only deal with successful
7776 * returns. This behavior is deprecated, because it makes it
7777 * difficult for a subclass to chain to a parent class's async
7778 * methods. Instead, the wrapper function should just be a
7779 * simple wrapper, and the virtual method should call an
7780 * appropriate `g_task_propagate_` function.
7781 * Note that wrapper methods can now use
7782 * g_async_result_legacy_propagate_error() to do old-style
7783 * #GSimpleAsyncResult error-returning behavior, and
7784 * g_async_result_is_tagged() to check if a result is tagged as
7785 * having come from the `_async()` wrapper
7786 * function (for "short-circuit" results, such as when passing
7787 * 0 to g_input_stream_read_async()).
7792 * SECTION:gtcpconnection
7793 * @title: GTcpConnection
7794 * @short_description: A TCP GSocketConnection
7795 * @include: gio/gio.h
7796 * @see_also: #GSocketConnection.
7798 * This is the subclass of #GSocketConnection that is created
7799 * for TCP/IP sockets.
7806 * SECTION:gtcpwrapperconnection
7807 * @title: GTcpWrapperConnection
7808 * @short_description: Wrapper for non-GSocketConnection-based,
7809 * GSocket-based GIOStreams
7810 * @include: gio/gio.h
7811 * @see_also: #GSocketConnection.
7813 * A #GTcpWrapperConnection can be used to wrap a #GIOStream that is
7814 * based on a #GSocket, but which is not actually a
7815 * #GSocketConnection. This is used by #GSocketClient so that it can
7816 * always return a #GSocketConnection, even when the connection it has
7817 * actually created is not directly a #GSocketConnection.
7825 * @short_description: D-Bus testing helper
7826 * @include: gio/gio.h
7828 * A helper class for testing code which uses D-Bus without touching the user's
7831 * Note that #GTestDBus modifies the user’s environment, calling setenv().
7832 * This is not thread-safe, so all #GTestDBus calls should be completed before
7833 * threads are spawned, or should have appropriate locking to ensure no access
7834 * conflicts to environment variables shared between #GTestDBus and other
7837 * ## Creating unit tests using GTestDBus
7839 * Testing of D-Bus services can be tricky because normally we only ever run
7840 * D-Bus services over an existing instance of the D-Bus daemon thus we
7841 * usually don't activate D-Bus services that are not yet installed into the
7842 * target system. The #GTestDBus object makes this easier for us by taking care
7843 * of the lower level tasks such as running a private D-Bus daemon and looking
7844 * up uninstalled services in customizable locations, typically in your source
7847 * The first thing you will need is a separate service description file for the
7848 * D-Bus daemon. Typically a `services` subdirectory of your `tests` directory
7849 * is a good place to put this file.
7851 * The service file should list your service along with an absolute path to the
7852 * uninstalled service executable in your source tree. Using autotools we would
7853 * achieve this by adding a file such as `my-server.service.in` in the services
7854 * directory and have it processed by configure.
7857 * Name=org.gtk.GDBus.Examples.ObjectManager
7858 * Exec=@abs_top_builddir@/gio/tests/gdbus-example-objectmanager-server
7860 * You will also need to indicate this service directory in your test
7861 * fixtures, so you will need to pass the path while compiling your
7862 * test cases. Typically this is done with autotools with an added
7863 * preprocessor flag specified to compile your tests such as:
7865 * -DTEST_SERVICES=\""$(abs_top_builddir)/tests/services"\"
7867 * Once you have a service definition file which is local to your source tree,
7868 * you can proceed to set up a GTest fixture using the #GTestDBus scaffolding.
7870 * An example of a test fixture for D-Bus services can be found
7872 * [gdbus-test-fixture.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-test-fixture.c)
7874 * Note that these examples only deal with isolating the D-Bus aspect of your
7875 * service. To successfully run isolated unit tests on your service you may need
7876 * some additional modifications to your test case fixture. For example; if your
7877 * service uses GSettings and installs a schema then it is important that your test service
7878 * not load the schema in the ordinary installed location (chances are that your service
7879 * and schema files are not yet installed, or worse; there is an older version of the
7880 * schema file sitting in the install location).
7882 * Most of the time we can work around these obstacles using the
7883 * environment. Since the environment is inherited by the D-Bus daemon
7884 * created by #GTestDBus and then in turn inherited by any services the
7885 * D-Bus daemon activates, using the setup routine for your fixture is
7886 * a practical place to help sandbox your runtime environment. For the
7887 * rather typical GSettings case we can work around this by setting
7888 * `GSETTINGS_SCHEMA_DIR` to the in tree directory holding your schemas
7889 * in the above fixture_setup() routine.
7891 * The GSettings schemas need to be locally pre-compiled for this to work. This can be achieved
7892 * by compiling the schemas locally as a step before running test cases, an autotools setup might
7893 * do the following in the directory holding schemas:
7896 * $(GLIB_COMPILE_SCHEMAS) .
7898 * CLEANFILES += gschemas.compiled
7904 * SECTION:gthemedicon
7905 * @short_description: Icon theming support
7906 * @include: gio/gio.h
7907 * @see_also: #GIcon, #GLoadableIcon
7909 * #GThemedIcon is an implementation of #GIcon that supports icon themes.
7910 * #GThemedIcon contains a list of all of the icons present in an icon
7911 * theme, so that icons can be looked up quickly. #GThemedIcon does
7912 * not provide actual pixmaps for icons, just the icon names.
7913 * Ideally something like gtk_icon_theme_choose_icon() should be used to
7914 * resolve the list of names so that fallback icons work nicely with
7915 * themes that inherit other themes.
7920 * SECTION:gthreadedsocketservice
7921 * @title: GThreadedSocketService
7922 * @short_description: A threaded GSocketService
7923 * @include: gio/gio.h
7924 * @see_also: #GSocketService.
7926 * A #GThreadedSocketService is a simple subclass of #GSocketService
7927 * that handles incoming connections by creating a worker thread and
7928 * dispatching the connection to it by emitting the
7929 * #GThreadedSocketService::run signal in the new thread.
7931 * The signal handler may perform blocking IO and need not return
7932 * until the connection is closed.
7934 * The service is implemented using a thread pool, so there is a
7935 * limited amount of threads available to serve incoming requests.
7936 * The service automatically stops the #GSocketService from accepting
7937 * new connections when all threads are busy.
7939 * As with #GSocketService, you may connect to #GThreadedSocketService::run,
7940 * or subclass and override the default handler.
7946 * @title: TLS Overview
7947 * @short_description: TLS (aka SSL) support for GSocketConnection
7948 * @include: gio/gio.h
7950 * #GTlsConnection and related classes provide TLS (Transport Layer
7951 * Security, previously known as SSL, Secure Sockets Layer) support for
7952 * gio-based network streams.
7954 * In the simplest case, for a client connection, you can just set the
7955 * #GSocketClient:tls flag on a #GSocketClient, and then any
7956 * connections created by that client will have TLS negotiated
7957 * automatically, using appropriate default settings, and rejecting
7958 * any invalid or self-signed certificates (unless you change that
7959 * default by setting the #GSocketClient:tls-validation-flags
7960 * property). The returned object will be a #GTcpWrapperConnection,
7961 * which wraps the underlying #GTlsClientConnection.
7963 * For greater control, you can create your own #GTlsClientConnection,
7964 * wrapping a #GSocketConnection (or an arbitrary #GIOStream with
7965 * pollable input and output streams) and then connect to its signals,
7966 * such as #GTlsConnection::accept-certificate, before starting the
7969 * Server-side TLS is similar, using #GTlsServerConnection. At the
7970 * moment, there is no support for automatically wrapping server-side
7971 * connections in the way #GSocketClient does for client-side
7977 * SECTION:gtlsbackend
7978 * @title: GTlsBackend
7979 * @short_description: TLS backend implementation
7980 * @include: gio/gio.h
7985 * SECTION:gtlscertificate
7986 * @title: GTlsCertificate
7987 * @short_description: TLS certificate
7988 * @include: gio/gio.h
7989 * @see_also: #GTlsConnection
7991 * A certificate used for TLS authentication and encryption.
7992 * This can represent either a certificate only (eg, the certificate
7993 * received by a client from a server), or the combination of
7994 * a certificate and a private key (which is needed when acting as a
7995 * #GTlsServerConnection).
8002 * SECTION:gtlsclientconnection
8003 * @short_description: TLS client-side connection
8004 * @include: gio/gio.h
8006 * #GTlsClientConnection is the client-side subclass of
8007 * #GTlsConnection, representing a client-side TLS connection.
8012 * SECTION:gtlsconnection
8013 * @short_description: TLS connection type
8014 * @include: gio/gio.h
8016 * #GTlsConnection is the base TLS connection class type, which wraps
8017 * a #GIOStream and provides TLS encryption on top of it. Its
8018 * subclasses, #GTlsClientConnection and #GTlsServerConnection,
8019 * implement client-side and server-side TLS, respectively.
8026 * SECTION:gtlsdatabase
8027 * @short_description: TLS database type
8028 * @include: gio/gio.h
8030 * #GTlsDatabase is used to lookup certificates and other information
8031 * from a certificate or key store. It is an abstract base class which
8032 * TLS library specific subtypes override.
8034 * Most common client applications will not directly interact with
8035 * #GTlsDatabase. It is used internally by #GTlsConnection.
8042 * SECTION:gtlsfiledatabase
8043 * @short_description: TLS file based database type
8044 * @include: gio/gio.h
8046 * #GTlsFileDatabase is implemented by #GTlsDatabase objects which load
8047 * their certificate information from a file. It is an interface which
8048 * TLS library specific subtypes implement.
8055 * SECTION:gtlsinteraction
8056 * @short_description: Interaction with the user during TLS operations.
8057 * @include: gio/gio.h
8059 * #GTlsInteraction provides a mechanism for the TLS connection and database
8060 * code to interact with the user. It can be used to ask the user for passwords.
8062 * To use a #GTlsInteraction with a TLS connection use
8063 * g_tls_connection_set_interaction().
8065 * Callers should instantiate a derived class that implements the various
8066 * interaction methods to show the required dialogs.
8068 * Callers should use the 'invoke' functions like
8069 * g_tls_interaction_invoke_ask_password() to run interaction methods. These
8070 * functions make sure that the interaction is invoked in the main loop
8071 * and not in the current thread, if the current thread is not running the
8074 * Derived classes can choose to implement whichever interactions methods they'd
8075 * like to support by overriding those virtual methods in their class
8076 * initialization function. Any interactions not implemented will return
8077 * %G_TLS_INTERACTION_UNHANDLED. If a derived class implements an async method,
8078 * it must also implement the corresponding finish method.
8083 * SECTION:gtlspassword
8084 * @title: GTlsPassword
8085 * @short_description: TLS Passwords for prompting
8086 * @include: gio/gio.h
8088 * Holds a password used in TLS.
8093 * SECTION:gtlsserverconnection
8094 * @short_description: TLS server-side connection
8095 * @include: gio/gio.h
8097 * #GTlsServerConnection is the server-side subclass of #GTlsConnection,
8098 * representing a server-side TLS connection.
8105 * SECTION:gunixconnection
8106 * @title: GUnixConnection
8107 * @short_description: A UNIX domain GSocketConnection
8108 * @include: gio/gunixconnection.h
8109 * @see_also: #GSocketConnection.
8111 * This is the subclass of #GSocketConnection that is created
8112 * for UNIX domain sockets.
8114 * It contains functions to do some of the UNIX socket specific
8115 * functionality like passing file descriptors.
8117 * Note that `<gio/gunixconnection.h>` belongs to the UNIX-specific
8118 * GIO interfaces, thus you have to use the `gio-unix-2.0.pc`
8119 * pkg-config file when using it.
8126 * SECTION:gunixcredentialsmessage
8127 * @title: GUnixCredentialsMessage
8128 * @short_description: A GSocketControlMessage containing credentials
8129 * @include: gio/gunixcredentialsmessage.h
8130 * @see_also: #GUnixConnection, #GSocketControlMessage
8132 * This #GSocketControlMessage contains a #GCredentials instance. It
8133 * may be sent using g_socket_send_message() and received using
8134 * g_socket_receive_message() over UNIX sockets (ie: sockets in the
8135 * %G_SOCKET_FAMILY_UNIX family).
8137 * For an easier way to send and receive credentials over
8138 * stream-oriented UNIX sockets, see
8139 * g_unix_connection_send_credentials() and
8140 * g_unix_connection_receive_credentials(). To receive credentials of
8141 * a foreign process connected to a socket, use
8142 * g_socket_get_credentials().
8147 * SECTION:gunixfdlist
8148 * @title: GUnixFDList
8149 * @short_description: An object containing a set of UNIX file descriptors
8150 * @include: gio/gunixfdlist.h
8151 * @see_also: #GUnixFDMessage
8153 * A #GUnixFDList contains a list of file descriptors. It owns the file
8154 * descriptors that it contains, closing them when finalized.
8156 * It may be wrapped in a #GUnixFDMessage and sent over a #GSocket in
8157 * the %G_SOCKET_ADDRESS_UNIX family by using g_socket_send_message()
8158 * and received using g_socket_receive_message().
8160 * Note that `<gio/gunixfdlist.h>` belongs to the UNIX-specific GIO
8161 * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config
8162 * file when using it.
8167 * SECTION:gunixfdmessage
8168 * @title: GUnixFDMessage
8169 * @short_description: A GSocketControlMessage containing a GUnixFDList
8170 * @include: gio/gunixfdmessage.h
8171 * @see_also: #GUnixConnection, #GUnixFDList, #GSocketControlMessage
8173 * This #GSocketControlMessage contains a #GUnixFDList.
8174 * It may be sent using g_socket_send_message() and received using
8175 * g_socket_receive_message() over UNIX sockets (ie: sockets in the
8176 * %G_SOCKET_ADDRESS_UNIX family). The file descriptors are copied
8177 * between processes by the kernel.
8179 * For an easier way to send and receive file descriptors over
8180 * stream-oriented UNIX sockets, see g_unix_connection_send_fd() and
8181 * g_unix_connection_receive_fd().
8183 * Note that `<gio/gunixfdmessage.h>` belongs to the UNIX-specific GIO
8184 * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config
8185 * file when using it.
8190 * SECTION:gunixinputstream
8191 * @short_description: Streaming input operations for UNIX file descriptors
8192 * @include: gio/gunixinputstream.h
8193 * @see_also: #GInputStream
8195 * #GUnixInputStream implements #GInputStream for reading from a UNIX
8196 * file descriptor, including asynchronous operations. (If the file
8197 * descriptor refers to a socket or pipe, this will use poll() to do
8198 * asynchronous I/O. If it refers to a regular file, it will fall back
8199 * to doing asynchronous I/O in another thread.)
8201 * Note that `<gio/gunixinputstream.h>` belongs to the UNIX-specific GIO
8202 * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config
8203 * file when using it.
8208 * SECTION:gunixmounts
8209 * @include: gio/gunixmounts.h
8210 * @short_description: UNIX mounts
8212 * Routines for managing mounted UNIX mount points and paths.
8214 * Note that `<gio/gunixmounts.h>` belongs to the UNIX-specific GIO
8215 * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config
8216 * file when using it.
8221 * SECTION:gunixoutputstream
8222 * @short_description: Streaming output operations for UNIX file descriptors
8223 * @include: gio/gunixoutputstream.h
8224 * @see_also: #GOutputStream
8226 * #GUnixOutputStream implements #GOutputStream for writing to a UNIX
8227 * file descriptor, including asynchronous operations. (If the file
8228 * descriptor refers to a socket or pipe, this will use poll() to do
8229 * asynchronous I/O. If it refers to a regular file, it will fall back
8230 * to doing asynchronous I/O in another thread.)
8232 * Note that `<gio/gunixoutputstream.h>` belongs to the UNIX-specific GIO
8233 * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config file
8239 * SECTION:gunixsocketaddress
8240 * @short_description: UNIX GSocketAddress
8241 * @include: gio/gunixsocketaddress.h
8243 * Support for UNIX-domain (also known as local) sockets.
8245 * UNIX domain sockets are generally visible in the filesystem.
8246 * However, some systems support abstract socket names which are not
8247 * visible in the filesystem and not affected by the filesystem
8248 * permissions, visibility, etc. Currently this is only supported
8249 * under Linux. If you attempt to use abstract sockets on other
8250 * systems, function calls may return %G_IO_ERROR_NOT_SUPPORTED
8251 * errors. You can use g_unix_socket_address_abstract_names_supported()
8252 * to see if abstract names are supported.
8254 * Note that `<gio/gunixsocketaddress.h>` belongs to the UNIX-specific GIO
8255 * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config file
8262 * @short_description: Virtual File System
8263 * @include: gio/gio.h
8265 * Entry point for using GIO functionality.
8271 * @short_description: Volume management
8272 * @include: gio/gio.h
8274 * The #GVolume interface represents user-visible objects that can be
8275 * mounted. Note, when porting from GnomeVFS, #GVolume is the moral
8276 * equivalent of #GnomeVFSDrive.
8278 * Mounting a #GVolume instance is an asynchronous operation. For more
8279 * information about asynchronous operations, see #GAsyncResult and
8280 * #GTask. To mount a #GVolume, first call g_volume_mount() with (at
8281 * least) the #GVolume instance, optionally a #GMountOperation object
8282 * and a #GAsyncReadyCallback.
8284 * Typically, one will only want to pass %NULL for the
8285 * #GMountOperation if automounting all volumes when a desktop session
8286 * starts since it's not desirable to put up a lot of dialogs asking
8289 * The callback will be fired when the operation has resolved (either
8290 * with success or failure), and a #GAsyncReady structure will be
8291 * passed to the callback. That callback should then call
8292 * g_volume_mount_finish() with the #GVolume instance and the
8293 * #GAsyncReady data to see if the operation was completed
8294 * successfully. If an @error is present when g_volume_mount_finish()
8295 * is called, then it will be filled with any error information.
8297 * ## Volume Identifiers # {#volume-identifier}
8299 * It is sometimes necessary to directly access the underlying
8300 * operating system object behind a volume (e.g. for passing a volume
8301 * to an application via the commandline). For this purpose, GIO
8302 * allows to obtain an 'identifier' for the volume. There can be
8303 * different kinds of identifiers, such as Hal UDIs, filesystem labels,
8304 * traditional Unix devices (e.g. `/dev/sda2`), UUIDs. GIO uses predefined
8305 * strings as names for the different kinds of identifiers:
8306 * #G_VOLUME_IDENTIFIER_KIND_HAL_UDI, #G_VOLUME_IDENTIFIER_KIND_LABEL, etc.
8307 * Use g_volume_get_identifier() to obtain an identifier for a volume.
8310 * Note that #G_VOLUME_IDENTIFIER_KIND_HAL_UDI will only be available
8311 * when the gvfs hal volume monitor is in use. Other volume monitors
8312 * will generally be able to provide the #G_VOLUME_IDENTIFIER_KIND_UNIX_DEVICE
8313 * identifier, which can be used to obtain a hal device by means of
8314 * libhal_manager_find_device_string_match().
8319 * SECTION:gvolumemonitor
8320 * @short_description: Volume Monitor
8321 * @include: gio/gio.h
8322 * @see_also: #GFileMonitor
8324 * #GVolumeMonitor is for listing the user interesting devices and volumes
8325 * on the computer. In other words, what a file selector or file manager
8326 * would show in a sidebar.
8328 * #GVolumeMonitor is not
8329 * [thread-default-context aware][g-main-context-push-thread-default],
8330 * and so should not be used other than from the main thread, with no
8331 * thread-default-context active.
8336 * SECTION:gwin32inputstream
8337 * @short_description: Streaming input operations for Windows file handles
8338 * @include: gio/gwin32inputstream.h
8339 * @see_also: #GInputStream
8341 * #GWin32InputStream implements #GInputStream for reading from a
8342 * Windows file handle.
8344 * Note that `<gio/gwin32inputstream.h>` belongs to the Windows-specific GIO
8345 * interfaces, thus you have to use the `gio-windows-2.0.pc` pkg-config file
8351 * SECTION:gwin32outputstream
8352 * @short_description: Streaming output operations for Windows file handles
8353 * @include: gio/gwin32outputstream.h
8354 * @see_also: #GOutputStream
8356 * #GWin32OutputStream implements #GOutputStream for writing to a
8357 * Windows file handle.
8359 * Note that `<gio/gwin32outputstream.h>` belongs to the Windows-specific GIO
8360 * interfaces, thus you have to use the `gio-windows-2.0.pc` pkg-config file
8366 * SECTION:gzcompressor
8367 * @short_description: Zlib compressor
8368 * @include: gio/gio.h
8370 * #GZlibCompressor is an implementation of #GConverter that
8371 * compresses data using zlib.
8376 * SECTION:gzdecompressor
8377 * @short_description: Zlib decompressor
8378 * @include: gio/gio.h
8380 * #GZlibDecompressor is an implementation of #GConverter that
8381 * decompresses data compressed with zlib.
8386 * _GFreedesktopDBus:
8388 * Abstract interface type for the D-Bus interface <link linkend="gdbus-interface-org-freedesktop-DBus.top_of_page">org.freedesktop.DBus</link>.
8393 * _GFreedesktopDBus::handle-add-match:
8394 * @object: A #_GFreedesktopDBus.
8395 * @invocation: A #GDBusMethodInvocation.
8396 * @arg_rule: Argument passed by remote caller.
8398 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.AddMatch">AddMatch()</link> D-Bus method.
8400 * 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.
8402 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
8407 * _GFreedesktopDBus::handle-get-connection-selinux-security-context:
8408 * @object: A #_GFreedesktopDBus.
8409 * @invocation: A #GDBusMethodInvocation.
8410 * @arg_name: Argument passed by remote caller.
8412 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionSELinuxSecurityContext">GetConnectionSELinuxSecurityContext()</link> D-Bus method.
8414 * 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.
8416 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
8421 * _GFreedesktopDBus::handle-get-connection-unix-process-id:
8422 * @object: A #_GFreedesktopDBus.
8423 * @invocation: A #GDBusMethodInvocation.
8424 * @arg_name: Argument passed by remote caller.
8426 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionUnixProcessID">GetConnectionUnixProcessID()</link> D-Bus method.
8428 * 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.
8430 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
8435 * _GFreedesktopDBus::handle-get-connection-unix-user:
8436 * @object: A #_GFreedesktopDBus.
8437 * @invocation: A #GDBusMethodInvocation.
8438 * @arg_name: Argument passed by remote caller.
8440 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionUnixUser">GetConnectionUnixUser()</link> D-Bus method.
8442 * 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.
8444 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
8449 * _GFreedesktopDBus::handle-get-id:
8450 * @object: A #_GFreedesktopDBus.
8451 * @invocation: A #GDBusMethodInvocation.
8453 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.GetId">GetId()</link> D-Bus method.
8455 * 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.
8457 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
8462 * _GFreedesktopDBus::handle-get-name-owner:
8463 * @object: A #_GFreedesktopDBus.
8464 * @invocation: A #GDBusMethodInvocation.
8465 * @arg_name: Argument passed by remote caller.
8467 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.GetNameOwner">GetNameOwner()</link> D-Bus method.
8469 * 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.
8471 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
8476 * _GFreedesktopDBus::handle-hello:
8477 * @object: A #_GFreedesktopDBus.
8478 * @invocation: A #GDBusMethodInvocation.
8480 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.Hello">Hello()</link> D-Bus method.
8482 * 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.
8484 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
8489 * _GFreedesktopDBus::handle-list-activatable-names:
8490 * @object: A #_GFreedesktopDBus.
8491 * @invocation: A #GDBusMethodInvocation.
8493 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.ListActivatableNames">ListActivatableNames()</link> D-Bus method.
8495 * 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.
8497 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
8502 * _GFreedesktopDBus::handle-list-names:
8503 * @object: A #_GFreedesktopDBus.
8504 * @invocation: A #GDBusMethodInvocation.
8506 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.ListNames">ListNames()</link> D-Bus method.
8508 * 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.
8510 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
8515 * _GFreedesktopDBus::handle-list-queued-owners:
8516 * @object: A #_GFreedesktopDBus.
8517 * @invocation: A #GDBusMethodInvocation.
8518 * @arg_name: Argument passed by remote caller.
8520 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.ListQueuedOwners">ListQueuedOwners()</link> D-Bus method.
8522 * 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.
8524 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
8529 * _GFreedesktopDBus::handle-name-has-owner:
8530 * @object: A #_GFreedesktopDBus.
8531 * @invocation: A #GDBusMethodInvocation.
8532 * @arg_name: Argument passed by remote caller.
8534 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.NameHasOwner">NameHasOwner()</link> D-Bus method.
8536 * 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.
8538 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
8543 * _GFreedesktopDBus::handle-release-name:
8544 * @object: A #_GFreedesktopDBus.
8545 * @invocation: A #GDBusMethodInvocation.
8546 * @arg_name: Argument passed by remote caller.
8548 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.ReleaseName">ReleaseName()</link> D-Bus method.
8550 * 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.
8552 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
8557 * _GFreedesktopDBus::handle-reload-config:
8558 * @object: A #_GFreedesktopDBus.
8559 * @invocation: A #GDBusMethodInvocation.
8561 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.ReloadConfig">ReloadConfig()</link> D-Bus method.
8563 * 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.
8565 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
8570 * _GFreedesktopDBus::handle-remove-match:
8571 * @object: A #_GFreedesktopDBus.
8572 * @invocation: A #GDBusMethodInvocation.
8573 * @arg_rule: Argument passed by remote caller.
8575 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.RemoveMatch">RemoveMatch()</link> D-Bus method.
8577 * 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.
8579 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
8584 * _GFreedesktopDBus::handle-request-name:
8585 * @object: A #_GFreedesktopDBus.
8586 * @invocation: A #GDBusMethodInvocation.
8587 * @arg_name: Argument passed by remote caller.
8588 * @arg_flags: Argument passed by remote caller.
8590 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.RequestName">RequestName()</link> D-Bus method.
8592 * 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.
8594 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
8599 * _GFreedesktopDBus::handle-start-service-by-name:
8600 * @object: A #_GFreedesktopDBus.
8601 * @invocation: A #GDBusMethodInvocation.
8602 * @arg_name: Argument passed by remote caller.
8603 * @arg_flags: Argument passed by remote caller.
8605 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.StartServiceByName">StartServiceByName()</link> D-Bus method.
8607 * 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.
8609 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
8614 * _GFreedesktopDBus::handle-update-activation-environment:
8615 * @object: A #_GFreedesktopDBus.
8616 * @invocation: A #GDBusMethodInvocation.
8617 * @arg_environment: Argument passed by remote caller.
8619 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.UpdateActivationEnvironment">UpdateActivationEnvironment()</link> D-Bus method.
8621 * 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.
8623 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
8628 * _GFreedesktopDBus::name-acquired:
8629 * @object: A #_GFreedesktopDBus.
8630 * @arg_name: Argument.
8632 * 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.
8634 * 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.
8639 * _GFreedesktopDBus::name-lost:
8640 * @object: A #_GFreedesktopDBus.
8641 * @arg_name: Argument.
8643 * 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.
8645 * 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.
8650 * _GFreedesktopDBus::name-owner-changed:
8651 * @object: A #_GFreedesktopDBus.
8652 * @arg_name: Argument.
8653 * @arg_old_owner: Argument.
8654 * @arg_new_owner: Argument.
8656 * 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.
8658 * 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.
8663 * _GFreedesktopDBusIface:
8664 * @parent_iface: The parent interface.
8665 * @handle_add_match: Handler for the #_GFreedesktopDBus::handle-add-match signal.
8666 * @handle_get_connection_selinux_security_context: Handler for the #_GFreedesktopDBus::handle-get-connection-selinux-security-context signal.
8667 * @handle_get_connection_unix_process_id: Handler for the #_GFreedesktopDBus::handle-get-connection-unix-process-id signal.
8668 * @handle_get_connection_unix_user: Handler for the #_GFreedesktopDBus::handle-get-connection-unix-user signal.
8669 * @handle_get_id: Handler for the #_GFreedesktopDBus::handle-get-id signal.
8670 * @handle_get_name_owner: Handler for the #_GFreedesktopDBus::handle-get-name-owner signal.
8671 * @handle_hello: Handler for the #_GFreedesktopDBus::handle-hello signal.
8672 * @handle_list_activatable_names: Handler for the #_GFreedesktopDBus::handle-list-activatable-names signal.
8673 * @handle_list_names: Handler for the #_GFreedesktopDBus::handle-list-names signal.
8674 * @handle_list_queued_owners: Handler for the #_GFreedesktopDBus::handle-list-queued-owners signal.
8675 * @handle_name_has_owner: Handler for the #_GFreedesktopDBus::handle-name-has-owner signal.
8676 * @handle_release_name: Handler for the #_GFreedesktopDBus::handle-release-name signal.
8677 * @handle_reload_config: Handler for the #_GFreedesktopDBus::handle-reload-config signal.
8678 * @handle_remove_match: Handler for the #_GFreedesktopDBus::handle-remove-match signal.
8679 * @handle_request_name: Handler for the #_GFreedesktopDBus::handle-request-name signal.
8680 * @handle_start_service_by_name: Handler for the #_GFreedesktopDBus::handle-start-service-by-name signal.
8681 * @handle_update_activation_environment: Handler for the #_GFreedesktopDBus::handle-update-activation-environment signal.
8682 * @name_acquired: Handler for the #_GFreedesktopDBus::name-acquired signal.
8683 * @name_lost: Handler for the #_GFreedesktopDBus::name-lost signal.
8684 * @name_owner_changed: Handler for the #_GFreedesktopDBus::name-owner-changed signal.
8686 * Virtual table for the D-Bus interface <link linkend="gdbus-interface-org-freedesktop-DBus.top_of_page">org.freedesktop.DBus</link>.
8691 * _GFreedesktopDBusProxy:
8693 * The #_GFreedesktopDBusProxy structure contains only private data and should only be accessed using the provided API.
8698 * _GFreedesktopDBusProxyClass:
8699 * @parent_class: The parent class.
8701 * Class structure for #_GFreedesktopDBusProxy.
8706 * _GFreedesktopDBusSkeleton:
8708 * The #_GFreedesktopDBusSkeleton structure contains only private data and should only be accessed using the provided API.
8713 * _GFreedesktopDBusSkeletonClass:
8714 * @parent_class: The parent class.
8716 * Class structure for #_GFreedesktopDBusSkeleton.
8721 * _g_freedesktop_dbus_call_add_match:
8722 * @proxy: A #_GFreedesktopDBusProxy.
8723 * @arg_rule: Argument to pass with the method invocation.
8724 * @cancellable: (allow-none): A #GCancellable or %NULL.
8725 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
8726 * @user_data: User data to pass to @callback.
8728 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.AddMatch">AddMatch()</link> D-Bus method on @proxy.
8729 * 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.
8730 * You can then call _g_freedesktop_dbus_call_add_match_finish() to get the result of the operation.
8732 * See _g_freedesktop_dbus_call_add_match_sync() for the synchronous, blocking version of this method.
8737 * _g_freedesktop_dbus_call_add_match_finish:
8738 * @proxy: A #_GFreedesktopDBusProxy.
8739 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_add_match().
8740 * @error: Return location for error or %NULL.
8742 * Finishes an operation started with _g_freedesktop_dbus_call_add_match().
8744 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
8749 * _g_freedesktop_dbus_call_add_match_sync:
8750 * @proxy: A #_GFreedesktopDBusProxy.
8751 * @arg_rule: Argument to pass with the method invocation.
8752 * @cancellable: (allow-none): A #GCancellable or %NULL.
8753 * @error: Return location for error or %NULL.
8755 * 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.
8757 * See _g_freedesktop_dbus_call_add_match() for the asynchronous version of this method.
8759 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
8764 * _g_freedesktop_dbus_call_get_connection_selinux_security_context:
8765 * @proxy: A #_GFreedesktopDBusProxy.
8766 * @arg_name: Argument to pass with the method invocation.
8767 * @cancellable: (allow-none): A #GCancellable or %NULL.
8768 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
8769 * @user_data: User data to pass to @callback.
8771 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionSELinuxSecurityContext">GetConnectionSELinuxSecurityContext()</link> D-Bus method on @proxy.
8772 * 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.
8773 * You can then call _g_freedesktop_dbus_call_get_connection_selinux_security_context_finish() to get the result of the operation.
8775 * See _g_freedesktop_dbus_call_get_connection_selinux_security_context_sync() for the synchronous, blocking version of this method.
8780 * _g_freedesktop_dbus_call_get_connection_selinux_security_context_finish:
8781 * @proxy: A #_GFreedesktopDBusProxy.
8782 * @out_security_context: (out): Return location for return parameter or %NULL to ignore.
8783 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_get_connection_selinux_security_context().
8784 * @error: Return location for error or %NULL.
8786 * Finishes an operation started with _g_freedesktop_dbus_call_get_connection_selinux_security_context().
8788 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
8793 * _g_freedesktop_dbus_call_get_connection_selinux_security_context_sync:
8794 * @proxy: A #_GFreedesktopDBusProxy.
8795 * @arg_name: Argument to pass with the method invocation.
8796 * @out_security_context: (out): Return location for return parameter or %NULL to ignore.
8797 * @cancellable: (allow-none): A #GCancellable or %NULL.
8798 * @error: Return location for error or %NULL.
8800 * 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.
8802 * See _g_freedesktop_dbus_call_get_connection_selinux_security_context() for the asynchronous version of this method.
8804 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
8809 * _g_freedesktop_dbus_call_get_connection_unix_process_id:
8810 * @proxy: A #_GFreedesktopDBusProxy.
8811 * @arg_name: Argument to pass with the method invocation.
8812 * @cancellable: (allow-none): A #GCancellable or %NULL.
8813 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
8814 * @user_data: User data to pass to @callback.
8816 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionUnixProcessID">GetConnectionUnixProcessID()</link> D-Bus method on @proxy.
8817 * 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.
8818 * You can then call _g_freedesktop_dbus_call_get_connection_unix_process_id_finish() to get the result of the operation.
8820 * See _g_freedesktop_dbus_call_get_connection_unix_process_id_sync() for the synchronous, blocking version of this method.
8825 * _g_freedesktop_dbus_call_get_connection_unix_process_id_finish:
8826 * @proxy: A #_GFreedesktopDBusProxy.
8827 * @out_pid: (out): Return location for return parameter or %NULL to ignore.
8828 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_get_connection_unix_process_id().
8829 * @error: Return location for error or %NULL.
8831 * Finishes an operation started with _g_freedesktop_dbus_call_get_connection_unix_process_id().
8833 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
8838 * _g_freedesktop_dbus_call_get_connection_unix_process_id_sync:
8839 * @proxy: A #_GFreedesktopDBusProxy.
8840 * @arg_name: Argument to pass with the method invocation.
8841 * @out_pid: (out): Return location for return parameter or %NULL to ignore.
8842 * @cancellable: (allow-none): A #GCancellable or %NULL.
8843 * @error: Return location for error or %NULL.
8845 * 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.
8847 * See _g_freedesktop_dbus_call_get_connection_unix_process_id() for the asynchronous version of this method.
8849 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
8854 * _g_freedesktop_dbus_call_get_connection_unix_user:
8855 * @proxy: A #_GFreedesktopDBusProxy.
8856 * @arg_name: Argument to pass with the method invocation.
8857 * @cancellable: (allow-none): A #GCancellable or %NULL.
8858 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
8859 * @user_data: User data to pass to @callback.
8861 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionUnixUser">GetConnectionUnixUser()</link> D-Bus method on @proxy.
8862 * 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.
8863 * You can then call _g_freedesktop_dbus_call_get_connection_unix_user_finish() to get the result of the operation.
8865 * See _g_freedesktop_dbus_call_get_connection_unix_user_sync() for the synchronous, blocking version of this method.
8870 * _g_freedesktop_dbus_call_get_connection_unix_user_finish:
8871 * @proxy: A #_GFreedesktopDBusProxy.
8872 * @out_uid: (out): Return location for return parameter or %NULL to ignore.
8873 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_get_connection_unix_user().
8874 * @error: Return location for error or %NULL.
8876 * Finishes an operation started with _g_freedesktop_dbus_call_get_connection_unix_user().
8878 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
8883 * _g_freedesktop_dbus_call_get_connection_unix_user_sync:
8884 * @proxy: A #_GFreedesktopDBusProxy.
8885 * @arg_name: Argument to pass with the method invocation.
8886 * @out_uid: (out): Return location for return parameter or %NULL to ignore.
8887 * @cancellable: (allow-none): A #GCancellable or %NULL.
8888 * @error: Return location for error or %NULL.
8890 * 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.
8892 * See _g_freedesktop_dbus_call_get_connection_unix_user() for the asynchronous version of this method.
8894 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
8899 * _g_freedesktop_dbus_call_get_id:
8900 * @proxy: A #_GFreedesktopDBusProxy.
8901 * @cancellable: (allow-none): A #GCancellable or %NULL.
8902 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
8903 * @user_data: User data to pass to @callback.
8905 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.GetId">GetId()</link> D-Bus method on @proxy.
8906 * 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.
8907 * You can then call _g_freedesktop_dbus_call_get_id_finish() to get the result of the operation.
8909 * See _g_freedesktop_dbus_call_get_id_sync() for the synchronous, blocking version of this method.
8914 * _g_freedesktop_dbus_call_get_id_finish:
8915 * @proxy: A #_GFreedesktopDBusProxy.
8916 * @out_unique_id: (out): Return location for return parameter or %NULL to ignore.
8917 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_get_id().
8918 * @error: Return location for error or %NULL.
8920 * Finishes an operation started with _g_freedesktop_dbus_call_get_id().
8922 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
8927 * _g_freedesktop_dbus_call_get_id_sync:
8928 * @proxy: A #_GFreedesktopDBusProxy.
8929 * @out_unique_id: (out): Return location for return parameter or %NULL to ignore.
8930 * @cancellable: (allow-none): A #GCancellable or %NULL.
8931 * @error: Return location for error or %NULL.
8933 * 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.
8935 * See _g_freedesktop_dbus_call_get_id() for the asynchronous version of this method.
8937 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
8942 * _g_freedesktop_dbus_call_get_name_owner:
8943 * @proxy: A #_GFreedesktopDBusProxy.
8944 * @arg_name: Argument to pass with the method invocation.
8945 * @cancellable: (allow-none): A #GCancellable or %NULL.
8946 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
8947 * @user_data: User data to pass to @callback.
8949 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.GetNameOwner">GetNameOwner()</link> D-Bus method on @proxy.
8950 * 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.
8951 * You can then call _g_freedesktop_dbus_call_get_name_owner_finish() to get the result of the operation.
8953 * See _g_freedesktop_dbus_call_get_name_owner_sync() for the synchronous, blocking version of this method.
8958 * _g_freedesktop_dbus_call_get_name_owner_finish:
8959 * @proxy: A #_GFreedesktopDBusProxy.
8960 * @out_unique_name: (out): Return location for return parameter or %NULL to ignore.
8961 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_get_name_owner().
8962 * @error: Return location for error or %NULL.
8964 * Finishes an operation started with _g_freedesktop_dbus_call_get_name_owner().
8966 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
8971 * _g_freedesktop_dbus_call_get_name_owner_sync:
8972 * @proxy: A #_GFreedesktopDBusProxy.
8973 * @arg_name: Argument to pass with the method invocation.
8974 * @out_unique_name: (out): Return location for return parameter or %NULL to ignore.
8975 * @cancellable: (allow-none): A #GCancellable or %NULL.
8976 * @error: Return location for error or %NULL.
8978 * 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.
8980 * See _g_freedesktop_dbus_call_get_name_owner() for the asynchronous version of this method.
8982 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
8987 * _g_freedesktop_dbus_call_hello:
8988 * @proxy: A #_GFreedesktopDBusProxy.
8989 * @cancellable: (allow-none): A #GCancellable or %NULL.
8990 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
8991 * @user_data: User data to pass to @callback.
8993 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.Hello">Hello()</link> D-Bus method on @proxy.
8994 * 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.
8995 * You can then call _g_freedesktop_dbus_call_hello_finish() to get the result of the operation.
8997 * See _g_freedesktop_dbus_call_hello_sync() for the synchronous, blocking version of this method.
9002 * _g_freedesktop_dbus_call_hello_finish:
9003 * @proxy: A #_GFreedesktopDBusProxy.
9004 * @out_assigned_name: (out): Return location for return parameter or %NULL to ignore.
9005 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_hello().
9006 * @error: Return location for error or %NULL.
9008 * Finishes an operation started with _g_freedesktop_dbus_call_hello().
9010 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9015 * _g_freedesktop_dbus_call_hello_sync:
9016 * @proxy: A #_GFreedesktopDBusProxy.
9017 * @out_assigned_name: (out): Return location for return parameter or %NULL to ignore.
9018 * @cancellable: (allow-none): A #GCancellable or %NULL.
9019 * @error: Return location for error or %NULL.
9021 * 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.
9023 * See _g_freedesktop_dbus_call_hello() for the asynchronous version of this method.
9025 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9030 * _g_freedesktop_dbus_call_list_activatable_names:
9031 * @proxy: A #_GFreedesktopDBusProxy.
9032 * @cancellable: (allow-none): A #GCancellable or %NULL.
9033 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
9034 * @user_data: User data to pass to @callback.
9036 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.ListActivatableNames">ListActivatableNames()</link> D-Bus method on @proxy.
9037 * 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.
9038 * You can then call _g_freedesktop_dbus_call_list_activatable_names_finish() to get the result of the operation.
9040 * See _g_freedesktop_dbus_call_list_activatable_names_sync() for the synchronous, blocking version of this method.
9045 * _g_freedesktop_dbus_call_list_activatable_names_finish:
9046 * @proxy: A #_GFreedesktopDBusProxy.
9047 * @out_activatable_names: (out): Return location for return parameter or %NULL to ignore.
9048 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_list_activatable_names().
9049 * @error: Return location for error or %NULL.
9051 * Finishes an operation started with _g_freedesktop_dbus_call_list_activatable_names().
9053 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9058 * _g_freedesktop_dbus_call_list_activatable_names_sync:
9059 * @proxy: A #_GFreedesktopDBusProxy.
9060 * @out_activatable_names: (out): Return location for return parameter or %NULL to ignore.
9061 * @cancellable: (allow-none): A #GCancellable or %NULL.
9062 * @error: Return location for error or %NULL.
9064 * 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.
9066 * See _g_freedesktop_dbus_call_list_activatable_names() for the asynchronous version of this method.
9068 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9073 * _g_freedesktop_dbus_call_list_names:
9074 * @proxy: A #_GFreedesktopDBusProxy.
9075 * @cancellable: (allow-none): A #GCancellable or %NULL.
9076 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
9077 * @user_data: User data to pass to @callback.
9079 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.ListNames">ListNames()</link> D-Bus method on @proxy.
9080 * 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.
9081 * You can then call _g_freedesktop_dbus_call_list_names_finish() to get the result of the operation.
9083 * See _g_freedesktop_dbus_call_list_names_sync() for the synchronous, blocking version of this method.
9088 * _g_freedesktop_dbus_call_list_names_finish:
9089 * @proxy: A #_GFreedesktopDBusProxy.
9090 * @out_names: (out): Return location for return parameter or %NULL to ignore.
9091 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_list_names().
9092 * @error: Return location for error or %NULL.
9094 * Finishes an operation started with _g_freedesktop_dbus_call_list_names().
9096 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9101 * _g_freedesktop_dbus_call_list_names_sync:
9102 * @proxy: A #_GFreedesktopDBusProxy.
9103 * @out_names: (out): Return location for return parameter or %NULL to ignore.
9104 * @cancellable: (allow-none): A #GCancellable or %NULL.
9105 * @error: Return location for error or %NULL.
9107 * 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.
9109 * See _g_freedesktop_dbus_call_list_names() for the asynchronous version of this method.
9111 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9116 * _g_freedesktop_dbus_call_list_queued_owners:
9117 * @proxy: A #_GFreedesktopDBusProxy.
9118 * @arg_name: Argument to pass with the method invocation.
9119 * @cancellable: (allow-none): A #GCancellable or %NULL.
9120 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
9121 * @user_data: User data to pass to @callback.
9123 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.ListQueuedOwners">ListQueuedOwners()</link> D-Bus method on @proxy.
9124 * 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.
9125 * You can then call _g_freedesktop_dbus_call_list_queued_owners_finish() to get the result of the operation.
9127 * See _g_freedesktop_dbus_call_list_queued_owners_sync() for the synchronous, blocking version of this method.
9132 * _g_freedesktop_dbus_call_list_queued_owners_finish:
9133 * @proxy: A #_GFreedesktopDBusProxy.
9134 * @out_queued_owners: (out): Return location for return parameter or %NULL to ignore.
9135 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_list_queued_owners().
9136 * @error: Return location for error or %NULL.
9138 * Finishes an operation started with _g_freedesktop_dbus_call_list_queued_owners().
9140 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9145 * _g_freedesktop_dbus_call_list_queued_owners_sync:
9146 * @proxy: A #_GFreedesktopDBusProxy.
9147 * @arg_name: Argument to pass with the method invocation.
9148 * @out_queued_owners: (out): Return location for return parameter or %NULL to ignore.
9149 * @cancellable: (allow-none): A #GCancellable or %NULL.
9150 * @error: Return location for error or %NULL.
9152 * 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.
9154 * See _g_freedesktop_dbus_call_list_queued_owners() for the asynchronous version of this method.
9156 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9161 * _g_freedesktop_dbus_call_name_has_owner:
9162 * @proxy: A #_GFreedesktopDBusProxy.
9163 * @arg_name: Argument to pass with the method invocation.
9164 * @cancellable: (allow-none): A #GCancellable or %NULL.
9165 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
9166 * @user_data: User data to pass to @callback.
9168 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.NameHasOwner">NameHasOwner()</link> D-Bus method on @proxy.
9169 * 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.
9170 * You can then call _g_freedesktop_dbus_call_name_has_owner_finish() to get the result of the operation.
9172 * See _g_freedesktop_dbus_call_name_has_owner_sync() for the synchronous, blocking version of this method.
9177 * _g_freedesktop_dbus_call_name_has_owner_finish:
9178 * @proxy: A #_GFreedesktopDBusProxy.
9179 * @out_has_owner: (out): Return location for return parameter or %NULL to ignore.
9180 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_name_has_owner().
9181 * @error: Return location for error or %NULL.
9183 * Finishes an operation started with _g_freedesktop_dbus_call_name_has_owner().
9185 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9190 * _g_freedesktop_dbus_call_name_has_owner_sync:
9191 * @proxy: A #_GFreedesktopDBusProxy.
9192 * @arg_name: Argument to pass with the method invocation.
9193 * @out_has_owner: (out): Return location for return parameter or %NULL to ignore.
9194 * @cancellable: (allow-none): A #GCancellable or %NULL.
9195 * @error: Return location for error or %NULL.
9197 * 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.
9199 * See _g_freedesktop_dbus_call_name_has_owner() for the asynchronous version of this method.
9201 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9206 * _g_freedesktop_dbus_call_release_name:
9207 * @proxy: A #_GFreedesktopDBusProxy.
9208 * @arg_name: Argument to pass with the method invocation.
9209 * @cancellable: (allow-none): A #GCancellable or %NULL.
9210 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
9211 * @user_data: User data to pass to @callback.
9213 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.ReleaseName">ReleaseName()</link> D-Bus method on @proxy.
9214 * 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.
9215 * You can then call _g_freedesktop_dbus_call_release_name_finish() to get the result of the operation.
9217 * See _g_freedesktop_dbus_call_release_name_sync() for the synchronous, blocking version of this method.
9222 * _g_freedesktop_dbus_call_release_name_finish:
9223 * @proxy: A #_GFreedesktopDBusProxy.
9224 * @out_value: (out): Return location for return parameter or %NULL to ignore.
9225 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_release_name().
9226 * @error: Return location for error or %NULL.
9228 * Finishes an operation started with _g_freedesktop_dbus_call_release_name().
9230 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9235 * _g_freedesktop_dbus_call_release_name_sync:
9236 * @proxy: A #_GFreedesktopDBusProxy.
9237 * @arg_name: Argument to pass with the method invocation.
9238 * @out_value: (out): Return location for return parameter or %NULL to ignore.
9239 * @cancellable: (allow-none): A #GCancellable or %NULL.
9240 * @error: Return location for error or %NULL.
9242 * 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.
9244 * See _g_freedesktop_dbus_call_release_name() for the asynchronous version of this method.
9246 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9251 * _g_freedesktop_dbus_call_reload_config:
9252 * @proxy: A #_GFreedesktopDBusProxy.
9253 * @cancellable: (allow-none): A #GCancellable or %NULL.
9254 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
9255 * @user_data: User data to pass to @callback.
9257 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.ReloadConfig">ReloadConfig()</link> D-Bus method on @proxy.
9258 * 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.
9259 * You can then call _g_freedesktop_dbus_call_reload_config_finish() to get the result of the operation.
9261 * See _g_freedesktop_dbus_call_reload_config_sync() for the synchronous, blocking version of this method.
9266 * _g_freedesktop_dbus_call_reload_config_finish:
9267 * @proxy: A #_GFreedesktopDBusProxy.
9268 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_reload_config().
9269 * @error: Return location for error or %NULL.
9271 * Finishes an operation started with _g_freedesktop_dbus_call_reload_config().
9273 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9278 * _g_freedesktop_dbus_call_reload_config_sync:
9279 * @proxy: A #_GFreedesktopDBusProxy.
9280 * @cancellable: (allow-none): A #GCancellable or %NULL.
9281 * @error: Return location for error or %NULL.
9283 * 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.
9285 * See _g_freedesktop_dbus_call_reload_config() for the asynchronous version of this method.
9287 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9292 * _g_freedesktop_dbus_call_remove_match:
9293 * @proxy: A #_GFreedesktopDBusProxy.
9294 * @arg_rule: Argument to pass with the method invocation.
9295 * @cancellable: (allow-none): A #GCancellable or %NULL.
9296 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
9297 * @user_data: User data to pass to @callback.
9299 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.RemoveMatch">RemoveMatch()</link> D-Bus method on @proxy.
9300 * 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.
9301 * You can then call _g_freedesktop_dbus_call_remove_match_finish() to get the result of the operation.
9303 * See _g_freedesktop_dbus_call_remove_match_sync() for the synchronous, blocking version of this method.
9308 * _g_freedesktop_dbus_call_remove_match_finish:
9309 * @proxy: A #_GFreedesktopDBusProxy.
9310 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_remove_match().
9311 * @error: Return location for error or %NULL.
9313 * Finishes an operation started with _g_freedesktop_dbus_call_remove_match().
9315 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9320 * _g_freedesktop_dbus_call_remove_match_sync:
9321 * @proxy: A #_GFreedesktopDBusProxy.
9322 * @arg_rule: Argument to pass with the method invocation.
9323 * @cancellable: (allow-none): A #GCancellable or %NULL.
9324 * @error: Return location for error or %NULL.
9326 * 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.
9328 * See _g_freedesktop_dbus_call_remove_match() for the asynchronous version of this method.
9330 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9335 * _g_freedesktop_dbus_call_request_name:
9336 * @proxy: A #_GFreedesktopDBusProxy.
9337 * @arg_name: Argument to pass with the method invocation.
9338 * @arg_flags: Argument to pass with the method invocation.
9339 * @cancellable: (allow-none): A #GCancellable or %NULL.
9340 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
9341 * @user_data: User data to pass to @callback.
9343 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.RequestName">RequestName()</link> D-Bus method on @proxy.
9344 * 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.
9345 * You can then call _g_freedesktop_dbus_call_request_name_finish() to get the result of the operation.
9347 * See _g_freedesktop_dbus_call_request_name_sync() for the synchronous, blocking version of this method.
9352 * _g_freedesktop_dbus_call_request_name_finish:
9353 * @proxy: A #_GFreedesktopDBusProxy.
9354 * @out_value: (out): Return location for return parameter or %NULL to ignore.
9355 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_request_name().
9356 * @error: Return location for error or %NULL.
9358 * Finishes an operation started with _g_freedesktop_dbus_call_request_name().
9360 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9365 * _g_freedesktop_dbus_call_request_name_sync:
9366 * @proxy: A #_GFreedesktopDBusProxy.
9367 * @arg_name: Argument to pass with the method invocation.
9368 * @arg_flags: Argument to pass with the method invocation.
9369 * @out_value: (out): Return location for return parameter or %NULL to ignore.
9370 * @cancellable: (allow-none): A #GCancellable or %NULL.
9371 * @error: Return location for error or %NULL.
9373 * 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.
9375 * See _g_freedesktop_dbus_call_request_name() for the asynchronous version of this method.
9377 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9382 * _g_freedesktop_dbus_call_start_service_by_name:
9383 * @proxy: A #_GFreedesktopDBusProxy.
9384 * @arg_name: Argument to pass with the method invocation.
9385 * @arg_flags: Argument to pass with the method invocation.
9386 * @cancellable: (allow-none): A #GCancellable or %NULL.
9387 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
9388 * @user_data: User data to pass to @callback.
9390 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.StartServiceByName">StartServiceByName()</link> D-Bus method on @proxy.
9391 * 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.
9392 * You can then call _g_freedesktop_dbus_call_start_service_by_name_finish() to get the result of the operation.
9394 * See _g_freedesktop_dbus_call_start_service_by_name_sync() for the synchronous, blocking version of this method.
9399 * _g_freedesktop_dbus_call_start_service_by_name_finish:
9400 * @proxy: A #_GFreedesktopDBusProxy.
9401 * @out_value: (out): Return location for return parameter or %NULL to ignore.
9402 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_start_service_by_name().
9403 * @error: Return location for error or %NULL.
9405 * Finishes an operation started with _g_freedesktop_dbus_call_start_service_by_name().
9407 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9412 * _g_freedesktop_dbus_call_start_service_by_name_sync:
9413 * @proxy: A #_GFreedesktopDBusProxy.
9414 * @arg_name: Argument to pass with the method invocation.
9415 * @arg_flags: Argument to pass with the method invocation.
9416 * @out_value: (out): Return location for return parameter or %NULL to ignore.
9417 * @cancellable: (allow-none): A #GCancellable or %NULL.
9418 * @error: Return location for error or %NULL.
9420 * 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.
9422 * See _g_freedesktop_dbus_call_start_service_by_name() for the asynchronous version of this method.
9424 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9429 * _g_freedesktop_dbus_call_update_activation_environment:
9430 * @proxy: A #_GFreedesktopDBusProxy.
9431 * @arg_environment: Argument to pass with the method invocation.
9432 * @cancellable: (allow-none): A #GCancellable or %NULL.
9433 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
9434 * @user_data: User data to pass to @callback.
9436 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.UpdateActivationEnvironment">UpdateActivationEnvironment()</link> D-Bus method on @proxy.
9437 * 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.
9438 * You can then call _g_freedesktop_dbus_call_update_activation_environment_finish() to get the result of the operation.
9440 * See _g_freedesktop_dbus_call_update_activation_environment_sync() for the synchronous, blocking version of this method.
9445 * _g_freedesktop_dbus_call_update_activation_environment_finish:
9446 * @proxy: A #_GFreedesktopDBusProxy.
9447 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_update_activation_environment().
9448 * @error: Return location for error or %NULL.
9450 * Finishes an operation started with _g_freedesktop_dbus_call_update_activation_environment().
9452 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9457 * _g_freedesktop_dbus_call_update_activation_environment_sync:
9458 * @proxy: A #_GFreedesktopDBusProxy.
9459 * @arg_environment: Argument to pass with the method invocation.
9460 * @cancellable: (allow-none): A #GCancellable or %NULL.
9461 * @error: Return location for error or %NULL.
9463 * 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.
9465 * See _g_freedesktop_dbus_call_update_activation_environment() for the asynchronous version of this method.
9467 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9472 * _g_freedesktop_dbus_complete_add_match:
9473 * @object: A #_GFreedesktopDBus.
9474 * @invocation: (transfer full): A #GDBusMethodInvocation.
9476 * 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.
9478 * This method will free @invocation, you cannot use it afterwards.
9483 * _g_freedesktop_dbus_complete_get_connection_selinux_security_context:
9484 * @object: A #_GFreedesktopDBus.
9485 * @invocation: (transfer full): A #GDBusMethodInvocation.
9486 * @security_context: Parameter to return.
9488 * 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.
9490 * This method will free @invocation, you cannot use it afterwards.
9495 * _g_freedesktop_dbus_complete_get_connection_unix_process_id:
9496 * @object: A #_GFreedesktopDBus.
9497 * @invocation: (transfer full): A #GDBusMethodInvocation.
9498 * @pid: Parameter to return.
9500 * 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.
9502 * This method will free @invocation, you cannot use it afterwards.
9507 * _g_freedesktop_dbus_complete_get_connection_unix_user:
9508 * @object: A #_GFreedesktopDBus.
9509 * @invocation: (transfer full): A #GDBusMethodInvocation.
9510 * @uid: Parameter to return.
9512 * 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.
9514 * This method will free @invocation, you cannot use it afterwards.
9519 * _g_freedesktop_dbus_complete_get_id:
9520 * @object: A #_GFreedesktopDBus.
9521 * @invocation: (transfer full): A #GDBusMethodInvocation.
9522 * @unique_id: Parameter to return.
9524 * 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.
9526 * This method will free @invocation, you cannot use it afterwards.
9531 * _g_freedesktop_dbus_complete_get_name_owner:
9532 * @object: A #_GFreedesktopDBus.
9533 * @invocation: (transfer full): A #GDBusMethodInvocation.
9534 * @unique_name: Parameter to return.
9536 * 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.
9538 * This method will free @invocation, you cannot use it afterwards.
9543 * _g_freedesktop_dbus_complete_hello:
9544 * @object: A #_GFreedesktopDBus.
9545 * @invocation: (transfer full): A #GDBusMethodInvocation.
9546 * @assigned_name: Parameter to return.
9548 * 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.
9550 * This method will free @invocation, you cannot use it afterwards.
9555 * _g_freedesktop_dbus_complete_list_activatable_names:
9556 * @object: A #_GFreedesktopDBus.
9557 * @invocation: (transfer full): A #GDBusMethodInvocation.
9558 * @activatable_names: Parameter to return.
9560 * 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.
9562 * This method will free @invocation, you cannot use it afterwards.
9567 * _g_freedesktop_dbus_complete_list_names:
9568 * @object: A #_GFreedesktopDBus.
9569 * @invocation: (transfer full): A #GDBusMethodInvocation.
9570 * @names: Parameter to return.
9572 * 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.
9574 * This method will free @invocation, you cannot use it afterwards.
9579 * _g_freedesktop_dbus_complete_list_queued_owners:
9580 * @object: A #_GFreedesktopDBus.
9581 * @invocation: (transfer full): A #GDBusMethodInvocation.
9582 * @queued_owners: Parameter to return.
9584 * 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.
9586 * This method will free @invocation, you cannot use it afterwards.
9591 * _g_freedesktop_dbus_complete_name_has_owner:
9592 * @object: A #_GFreedesktopDBus.
9593 * @invocation: (transfer full): A #GDBusMethodInvocation.
9594 * @has_owner: Parameter to return.
9596 * 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.
9598 * This method will free @invocation, you cannot use it afterwards.
9603 * _g_freedesktop_dbus_complete_release_name:
9604 * @object: A #_GFreedesktopDBus.
9605 * @invocation: (transfer full): A #GDBusMethodInvocation.
9606 * @value: Parameter to return.
9608 * 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.
9610 * This method will free @invocation, you cannot use it afterwards.
9615 * _g_freedesktop_dbus_complete_reload_config:
9616 * @object: A #_GFreedesktopDBus.
9617 * @invocation: (transfer full): A #GDBusMethodInvocation.
9619 * 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.
9621 * This method will free @invocation, you cannot use it afterwards.
9626 * _g_freedesktop_dbus_complete_remove_match:
9627 * @object: A #_GFreedesktopDBus.
9628 * @invocation: (transfer full): A #GDBusMethodInvocation.
9630 * 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.
9632 * This method will free @invocation, you cannot use it afterwards.
9637 * _g_freedesktop_dbus_complete_request_name:
9638 * @object: A #_GFreedesktopDBus.
9639 * @invocation: (transfer full): A #GDBusMethodInvocation.
9640 * @value: Parameter to return.
9642 * 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.
9644 * This method will free @invocation, you cannot use it afterwards.
9649 * _g_freedesktop_dbus_complete_start_service_by_name:
9650 * @object: A #_GFreedesktopDBus.
9651 * @invocation: (transfer full): A #GDBusMethodInvocation.
9652 * @value: Parameter to return.
9654 * 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.
9656 * This method will free @invocation, you cannot use it afterwards.
9661 * _g_freedesktop_dbus_complete_update_activation_environment:
9662 * @object: A #_GFreedesktopDBus.
9663 * @invocation: (transfer full): A #GDBusMethodInvocation.
9665 * 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.
9667 * This method will free @invocation, you cannot use it afterwards.
9672 * _g_freedesktop_dbus_emit_name_acquired:
9673 * @object: A #_GFreedesktopDBus.
9674 * @arg_name: Argument to pass with the signal.
9676 * Emits the <link linkend="gdbus-signal-org-freedesktop-DBus.NameAcquired">"NameAcquired"</link> D-Bus signal.
9681 * _g_freedesktop_dbus_emit_name_lost:
9682 * @object: A #_GFreedesktopDBus.
9683 * @arg_name: Argument to pass with the signal.
9685 * Emits the <link linkend="gdbus-signal-org-freedesktop-DBus.NameLost">"NameLost"</link> D-Bus signal.
9690 * _g_freedesktop_dbus_emit_name_owner_changed:
9691 * @object: A #_GFreedesktopDBus.
9692 * @arg_name: Argument to pass with the signal.
9693 * @arg_old_owner: Argument to pass with the signal.
9694 * @arg_new_owner: Argument to pass with the signal.
9696 * Emits the <link linkend="gdbus-signal-org-freedesktop-DBus.NameOwnerChanged">"NameOwnerChanged"</link> D-Bus signal.
9701 * _g_freedesktop_dbus_interface_info:
9703 * Gets a machine-readable description of the <link linkend="gdbus-interface-org-freedesktop-DBus.top_of_page">org.freedesktop.DBus</link> D-Bus interface.
9705 * Returns: (transfer none): A #GDBusInterfaceInfo. Do not free.
9710 * _g_freedesktop_dbus_override_properties:
9711 * @klass: The class structure for a #GObject<!-- -->-derived class.
9712 * @property_id_begin: The property id to assign to the first overridden property.
9714 * Overrides all #GObject properties in the #_GFreedesktopDBus interface for a concrete class.
9715 * The properties are overridden in the order they are defined.
9717 * Returns: The last property id.
9722 * _g_freedesktop_dbus_proxy_new:
9723 * @connection: A #GDBusConnection.
9724 * @flags: Flags from the #GDBusProxyFlags enumeration.
9725 * @name: (allow-none): A bus name (well-known or unique) or %NULL if @connection is not a message bus connection.
9726 * @object_path: An object path.
9727 * @cancellable: (allow-none): A #GCancellable or %NULL.
9728 * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
9729 * @user_data: User data to pass to @callback.
9731 * 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.
9733 * 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.
9734 * You can then call _g_freedesktop_dbus_proxy_new_finish() to get the result of the operation.
9736 * See _g_freedesktop_dbus_proxy_new_sync() for the synchronous, blocking version of this constructor.
9741 * _g_freedesktop_dbus_proxy_new_finish:
9742 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_proxy_new().
9743 * @error: Return location for error or %NULL
9745 * Finishes an operation started with _g_freedesktop_dbus_proxy_new().
9747 * Returns: (transfer full) (type _GFreedesktopDBusProxy): The constructed proxy object or %NULL if @error is set.
9752 * _g_freedesktop_dbus_proxy_new_for_bus:
9753 * @bus_type: A #GBusType.
9754 * @flags: Flags from the #GDBusProxyFlags enumeration.
9755 * @name: A bus name (well-known or unique).
9756 * @object_path: An object path.
9757 * @cancellable: (allow-none): A #GCancellable or %NULL.
9758 * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
9759 * @user_data: User data to pass to @callback.
9761 * Like _g_freedesktop_dbus_proxy_new() but takes a #GBusType instead of a #GDBusConnection.
9763 * 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.
9764 * You can then call _g_freedesktop_dbus_proxy_new_for_bus_finish() to get the result of the operation.
9766 * See _g_freedesktop_dbus_proxy_new_for_bus_sync() for the synchronous, blocking version of this constructor.
9771 * _g_freedesktop_dbus_proxy_new_for_bus_finish:
9772 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_proxy_new_for_bus().
9773 * @error: Return location for error or %NULL
9775 * Finishes an operation started with _g_freedesktop_dbus_proxy_new_for_bus().
9777 * Returns: (transfer full) (type _GFreedesktopDBusProxy): The constructed proxy object or %NULL if @error is set.
9782 * _g_freedesktop_dbus_proxy_new_for_bus_sync:
9783 * @bus_type: A #GBusType.
9784 * @flags: Flags from the #GDBusProxyFlags enumeration.
9785 * @name: A bus name (well-known or unique).
9786 * @object_path: An object path.
9787 * @cancellable: (allow-none): A #GCancellable or %NULL.
9788 * @error: Return location for error or %NULL
9790 * Like _g_freedesktop_dbus_proxy_new_sync() but takes a #GBusType instead of a #GDBusConnection.
9792 * The calling thread is blocked until a reply is received.
9794 * See _g_freedesktop_dbus_proxy_new_for_bus() for the asynchronous version of this constructor.
9796 * Returns: (transfer full) (type _GFreedesktopDBusProxy): The constructed proxy object or %NULL if @error is set.
9801 * _g_freedesktop_dbus_proxy_new_sync:
9802 * @connection: A #GDBusConnection.
9803 * @flags: Flags from the #GDBusProxyFlags enumeration.
9804 * @name: (allow-none): A bus name (well-known or unique) or %NULL if @connection is not a message bus connection.
9805 * @object_path: An object path.
9806 * @cancellable: (allow-none): A #GCancellable or %NULL.
9807 * @error: Return location for error or %NULL
9809 * 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.
9811 * The calling thread is blocked until a reply is received.
9813 * See _g_freedesktop_dbus_proxy_new() for the asynchronous version of this constructor.
9815 * Returns: (transfer full) (type _GFreedesktopDBusProxy): The constructed proxy object or %NULL if @error is set.
9820 * _g_freedesktop_dbus_skeleton_new:
9822 * Creates a skeleton object for the D-Bus interface <link linkend="gdbus-interface-org-freedesktop-DBus.top_of_page">org.freedesktop.DBus</link>.
9824 * Returns: (transfer full) (type _GFreedesktopDBusSkeleton): The skeleton object.
9829 * _g_io_module_get_default:
9830 * @extension_point: the name of an extension point
9831 * @envvar: (allow-none): the name of an environment variable to
9832 * override the default implementation.
9833 * @verify_func: (allow-none): a function to call to verify that
9834 * a given implementation is usable in the current environment.
9836 * Retrieves the default object implementing @extension_point.
9838 * If @envvar is not %NULL, and the environment variable with that
9839 * name is set, then the implementation it specifies will be tried
9840 * first. After that, or if @envvar is not set, all other
9841 * implementations will be tried in order of decreasing priority.
9843 * If an extension point implementation implements #GInitable, then
9844 * that implementation will only be used if it initializes
9845 * successfully. Otherwise, if @verify_func is not %NULL, then it will
9846 * be called on each candidate implementation after construction, to
9847 * check if it is actually usable or not.
9849 * The result is cached after it is generated the first time, and
9850 * the function is thread-safe.
9852 * Returns: (transfer none): an object implementing
9853 * @extension_point, or %NULL if there are no usable
9859 * _g_io_module_get_default_type:
9860 * @extension_point: the name of an extension point
9861 * @envvar: (allow-none): the name of an environment variable to
9862 * override the default implementation.
9863 * @is_supported_offset: a vtable offset, or zero
9865 * Retrieves the default class implementing @extension_point.
9867 * If @envvar is not %NULL, and the environment variable with that
9868 * name is set, then the implementation it specifies will be tried
9869 * first. After that, or if @envvar is not set, all other
9870 * implementations will be tried in order of decreasing priority.
9872 * If @is_supported_offset is non-zero, then it is the offset into the
9873 * class vtable at which there is a function that takes no arguments and
9874 * returns a boolean. This function will be called on each candidate
9875 * implementation to check if it is actually usable or not.
9877 * The result is cached after it is generated the first time, and
9878 * the function is thread-safe.
9880 * Returns: (transfer none): an object implementing
9881 * @extension_point, or %NULL if there are no usable
9887 * g_action_activate:
9888 * @action: a #GAction
9889 * @parameter: (allow-none): the parameter to the activation
9891 * Activates the action.
9893 * @parameter must be the correct type of parameter for the action (ie:
9894 * the parameter type given at construction time). If the parameter
9895 * type was %NULL then @parameter must also be %NULL.
9897 * If the @parameter GVariant is floating, it is consumed.
9904 * g_action_change_state:
9905 * @action: a #GAction
9906 * @value: the new state
9908 * Request for the state of @action to be changed to @value.
9910 * The action must be stateful and @value must be of the correct type.
9911 * See g_action_get_state_type().
9913 * This call merely requests a change. The action may refuse to change
9914 * its state or may change its state to something other than @value.
9915 * See g_action_get_state_hint().
9917 * If the @value GVariant is floating, it is consumed.
9924 * g_action_get_enabled:
9925 * @action: a #GAction
9927 * Checks if @action is currently enabled.
9929 * An action must be enabled in order to be activated or in order to
9930 * have its state changed from outside callers.
9932 * Returns: whether the action is enabled
9938 * g_action_get_name:
9939 * @action: a #GAction
9941 * Queries the name of @action.
9943 * Returns: the name of the action
9949 * g_action_get_parameter_type:
9950 * @action: a #GAction
9952 * Queries the type of the parameter that must be given when activating
9955 * When activating the action using g_action_activate(), the #GVariant
9956 * given to that function must be of the type returned by this function.
9958 * In the case that this function returns %NULL, you must not give any
9959 * #GVariant, but %NULL instead.
9961 * Returns: (allow-none): the parameter type
9967 * g_action_get_state:
9968 * @action: a #GAction
9970 * Queries the current state of @action.
9972 * If the action is not stateful then %NULL will be returned. If the
9973 * action is stateful then the type of the return value is the type
9974 * given by g_action_get_state_type().
9976 * The return value (if non-%NULL) should be freed with
9977 * g_variant_unref() when it is no longer required.
9979 * Returns: (transfer full): the current state of the action
9985 * g_action_get_state_hint:
9986 * @action: a #GAction
9988 * Requests a hint about the valid range of values for the state of
9991 * If %NULL is returned it either means that the action is not stateful
9992 * or that there is no hint about the valid range of values for the
9993 * state of the action.
9995 * If a #GVariant array is returned then each item in the array is a
9996 * possible value for the state. If a #GVariant pair (ie: two-tuple) is
9997 * returned then the tuple specifies the inclusive lower and upper bound
9998 * of valid values for the state.
10000 * In any case, the information is merely a hint. It may be possible to
10001 * have a state value outside of the hinted range and setting a value
10002 * within the range may fail.
10004 * The return value (if non-%NULL) should be freed with
10005 * g_variant_unref() when it is no longer required.
10007 * Returns: (nullable) (transfer full): the state range hint
10013 * g_action_get_state_type:
10014 * @action: a #GAction
10016 * Queries the type of the state of @action.
10018 * If the action is stateful (e.g. created with
10019 * g_simple_action_new_stateful()) then this function returns the
10020 * #GVariantType of the state. This is the type of the initial value
10021 * given as the state. All calls to g_action_change_state() must give a
10022 * #GVariant of this type and g_action_get_state() will return a
10023 * #GVariant of the same type.
10025 * If the action is not stateful (e.g. created with g_simple_action_new())
10026 * then this function will return %NULL. In that case, g_action_get_state()
10027 * will return %NULL and you must not call g_action_change_state().
10029 * Returns: (allow-none): the state type, if the action is stateful
10035 * g_action_group_action_added:
10036 * @action_group: a #GActionGroup
10037 * @action_name: the name of an action in the group
10039 * Emits the #GActionGroup::action-added signal on @action_group.
10041 * This function should only be called by #GActionGroup implementations.
10048 * g_action_group_action_enabled_changed:
10049 * @action_group: a #GActionGroup
10050 * @action_name: the name of an action in the group
10051 * @enabled: whether or not the action is now enabled
10053 * Emits the #GActionGroup::action-enabled-changed signal on @action_group.
10055 * This function should only be called by #GActionGroup implementations.
10062 * g_action_group_action_removed:
10063 * @action_group: a #GActionGroup
10064 * @action_name: the name of an action in the group
10066 * Emits the #GActionGroup::action-removed signal on @action_group.
10068 * This function should only be called by #GActionGroup implementations.
10075 * g_action_group_action_state_changed:
10076 * @action_group: a #GActionGroup
10077 * @action_name: the name of an action in the group
10078 * @state: the new state of the named action
10080 * Emits the #GActionGroup::action-state-changed signal on @action_group.
10082 * This function should only be called by #GActionGroup implementations.
10089 * g_action_group_activate_action:
10090 * @action_group: a #GActionGroup
10091 * @action_name: the name of the action to activate
10092 * @parameter: (allow-none): parameters to the activation
10094 * Activate the named action within @action_group.
10096 * If the action is expecting a parameter, then the correct type of
10097 * parameter must be given as @parameter. If the action is expecting no
10098 * parameters then @parameter must be %NULL. See
10099 * g_action_group_get_action_parameter_type().
10106 * g_action_group_change_action_state:
10107 * @action_group: a #GActionGroup
10108 * @action_name: the name of the action to request the change on
10109 * @value: the new state
10111 * Request for the state of the named action within @action_group to be
10112 * changed to @value.
10114 * The action must be stateful and @value must be of the correct type.
10115 * See g_action_group_get_action_state_type().
10117 * This call merely requests a change. The action may refuse to change
10118 * its state or may change its state to something other than @value.
10119 * See g_action_group_get_action_state_hint().
10121 * If the @value GVariant is floating, it is consumed.
10128 * g_action_group_get_action_enabled:
10129 * @action_group: a #GActionGroup
10130 * @action_name: the name of the action to query
10132 * Checks if the named action within @action_group is currently enabled.
10134 * An action must be enabled in order to be activated or in order to
10135 * have its state changed from outside callers.
10137 * Returns: whether or not the action is currently enabled
10143 * g_action_group_get_action_parameter_type:
10144 * @action_group: a #GActionGroup
10145 * @action_name: the name of the action to query
10147 * Queries the type of the parameter that must be given when activating
10148 * the named action within @action_group.
10150 * When activating the action using g_action_group_activate_action(),
10151 * the #GVariant given to that function must be of the type returned
10152 * by this function.
10154 * In the case that this function returns %NULL, you must not give any
10155 * #GVariant, but %NULL instead.
10157 * The parameter type of a particular action will never change but it is
10158 * possible for an action to be removed and for a new action to be added
10159 * with the same name but a different parameter type.
10161 * Returns: (nullable): the parameter type
10167 * g_action_group_get_action_state:
10168 * @action_group: a #GActionGroup
10169 * @action_name: the name of the action to query
10171 * Queries the current state of the named action within @action_group.
10173 * If the action is not stateful then %NULL will be returned. If the
10174 * action is stateful then the type of the return value is the type
10175 * given by g_action_group_get_action_state_type().
10177 * The return value (if non-%NULL) should be freed with
10178 * g_variant_unref() when it is no longer required.
10180 * Returns: (nullable): the current state of the action
10186 * g_action_group_get_action_state_hint:
10187 * @action_group: a #GActionGroup
10188 * @action_name: the name of the action to query
10190 * Requests a hint about the valid range of values for the state of the
10191 * named action within @action_group.
10193 * If %NULL is returned it either means that the action is not stateful
10194 * or that there is no hint about the valid range of values for the
10195 * state of the action.
10197 * If a #GVariant array is returned then each item in the array is a
10198 * possible value for the state. If a #GVariant pair (ie: two-tuple) is
10199 * returned then the tuple specifies the inclusive lower and upper bound
10200 * of valid values for the state.
10202 * In any case, the information is merely a hint. It may be possible to
10203 * have a state value outside of the hinted range and setting a value
10204 * within the range may fail.
10206 * The return value (if non-%NULL) should be freed with
10207 * g_variant_unref() when it is no longer required.
10209 * Returns: (nullable) (transfer full): the state range hint
10215 * g_action_group_get_action_state_type:
10216 * @action_group: a #GActionGroup
10217 * @action_name: the name of the action to query
10219 * Queries the type of the state of the named action within
10222 * If the action is stateful then this function returns the
10223 * #GVariantType of the state. All calls to
10224 * g_action_group_change_action_state() must give a #GVariant of this
10225 * type and g_action_group_get_action_state() will return a #GVariant
10226 * of the same type.
10228 * If the action is not stateful then this function will return %NULL.
10229 * In that case, g_action_group_get_action_state() will return %NULL
10230 * and you must not call g_action_group_change_action_state().
10232 * The state type of a particular action will never change but it is
10233 * possible for an action to be removed and for a new action to be added
10234 * with the same name but a different state type.
10236 * Returns: (nullable) (transfer full): the state type, if the action
10243 * g_action_group_has_action:
10244 * @action_group: a #GActionGroup
10245 * @action_name: the name of the action to check for
10247 * Checks if the named action exists within @action_group.
10249 * Returns: whether the named action exists
10255 * g_action_group_list_actions:
10256 * @action_group: a #GActionGroup
10258 * Lists the actions contained within @action_group.
10260 * The caller is responsible for freeing the list with g_strfreev() when
10261 * it is no longer required.
10263 * Returns: (transfer full): a %NULL-terminated array of the names of the
10264 * actions in the groupb
10270 * g_action_group_query_action:
10271 * @action_group: a #GActionGroup
10272 * @action_name: the name of an action in the group
10273 * @enabled: (out): if the action is presently enabled
10274 * @parameter_type: (out) (allow-none): the parameter type, or %NULL if none needed
10275 * @state_type: (out) (allow-none): the state type, or %NULL if stateless
10276 * @state_hint: (out) (allow-none): the state hint, or %NULL if none
10277 * @state: (out) (allow-none): the current state, or %NULL if stateless
10279 * Queries all aspects of the named action within an @action_group.
10281 * This function acquires the information available from
10282 * g_action_group_has_action(), g_action_group_get_action_enabled(),
10283 * g_action_group_get_action_parameter_type(),
10284 * g_action_group_get_action_state_type(),
10285 * g_action_group_get_action_state_hint() and
10286 * g_action_group_get_action_state() with a single function call.
10288 * This provides two main benefits.
10290 * The first is the improvement in efficiency that comes with not having
10291 * to perform repeated lookups of the action in order to discover
10292 * different things about it. The second is that implementing
10293 * #GActionGroup can now be done by only overriding this one virtual
10296 * The interface provides a default implementation of this function that
10297 * calls the individual functions, as required, to fetch the
10298 * information. The interface also provides default implementations of
10299 * those functions that call this function. All implementations,
10300 * therefore, must override either this function or all of the others.
10302 * If the action exists, %TRUE is returned and any of the requested
10303 * fields (as indicated by having a non-%NULL reference passed in) are
10304 * filled. If the action doesn't exist, %FALSE is returned and the
10305 * fields may or may not have been modified.
10307 * Returns: %TRUE if the action exists, else %FALSE
10313 * g_action_map_add_action:
10314 * @action_map: a #GActionMap
10315 * @action: a #GAction
10317 * Adds an action to the @action_map.
10319 * If the action map already contains an action with the same name
10320 * as @action then the old action is dropped from the action map.
10322 * The action map takes its own reference on @action.
10329 * g_action_map_add_action_entries:
10330 * @action_map: a #GActionMap
10331 * @entries: (array length=n_entries) (element-type GActionEntry): a pointer to
10332 * the first item in an array of #GActionEntry structs
10333 * @n_entries: the length of @entries, or -1 if @entries is %NULL-terminated
10334 * @user_data: the user data for signal connections
10336 * A convenience function for creating multiple #GSimpleAction instances
10337 * and adding them to a #GActionMap.
10339 * Each action is constructed as per one #GActionEntry.
10341 * |[<!-- language="C" -->
10343 * activate_quit (GSimpleAction *simple,
10344 * GVariant *parameter,
10345 * gpointer user_data)
10351 * activate_print_string (GSimpleAction *simple,
10352 * GVariant *parameter,
10353 * gpointer user_data)
10355 * g_print ("%s\n", g_variant_get_string (parameter, NULL));
10358 * static GActionGroup *
10359 * create_action_group (void)
10361 * const GActionEntry entries[] = {
10362 * { "quit", activate_quit },
10363 * { "print-string", activate_print_string, "s" }
10365 * GSimpleActionGroup *group;
10367 * group = g_simple_action_group_new ();
10368 * g_action_map_add_action_entries (G_ACTION_MAP (group), entries, G_N_ELEMENTS (entries), NULL);
10370 * return G_ACTION_GROUP (group);
10379 * g_action_map_lookup_action:
10380 * @action_map: a #GActionMap
10381 * @action_name: the name of an action
10383 * Looks up the action with the name @action_name in @action_map.
10385 * If no such action exists, returns %NULL.
10387 * Returns: (transfer none): a #GAction, or %NULL
10393 * g_action_map_remove_action:
10394 * @action_map: a #GActionMap
10395 * @action_name: the name of the action
10397 * Removes the named action from the action map.
10399 * If no action of this name is in the map then nothing happens.
10406 * g_action_name_is_valid:
10407 * @action_name: an potential action name
10409 * Checks if @action_name is valid.
10411 * @action_name is valid if it consists only of alphanumeric characters,
10412 * plus '-' and '.'. The empty string is not a valid action name.
10414 * It is an error to call this function with a non-utf8 @action_name.
10415 * @action_name must not be %NULL.
10417 * Returns: %TRUE if @action_name is valid
10423 * g_action_parse_detailed_name:
10424 * @detailed_name: a detailed action name
10425 * @action_name: (out): the action name
10426 * @target_value: (out): the target value, or %NULL for no target
10427 * @error: a pointer to a %NULL #GError, or %NULL
10429 * Parses a detailed action name into its separate name and target
10432 * Detailed action names can have three formats.
10434 * The first format is used to represent an action name with no target
10435 * value and consists of just an action name containing no whitespace
10436 * nor the characters ':', '(' or ')'. For example: "app.action".
10438 * The second format is used to represent an action with a target value
10439 * that is a non-empty string consisting only of alphanumerics, plus '-'
10440 * and '.'. In that case, the action name and target value are
10441 * separated by a double colon ("::"). For example:
10442 * "app.action::target".
10444 * The third format is used to represent an action with any type of
10445 * target value, including strings. The target value follows the action
10446 * name, surrounded in parens. For example: "app.action(42)". The
10447 * target value is parsed using g_variant_parse(). If a tuple-typed
10448 * value is desired, it must be specified in the same way, resulting in
10449 * two sets of parens, for example: "app.action((1,2,3))". A string
10450 * target can be specified this way as well: "app.action('target')".
10451 * For strings, this third format must be used if * target value is
10452 * empty or contains characters other than alphanumerics, '-' and '.'.
10454 * Returns: %TRUE if successful, else %FALSE with @error set
10460 * g_action_print_detailed_name:
10461 * @action_name: a valid action name
10462 * @target_value: (allow-none): a #GVariant target value, or %NULL
10464 * Formats a detailed action name from @action_name and @target_value.
10466 * It is an error to call this function with an invalid action name.
10468 * This function is the opposite of
10469 * g_action_parse_detailed_action_name(). It will produce a string that
10470 * can be parsed back to the @action_name and @target_value by that
10473 * See that function for the types of strings that will be printed by
10476 * Returns: a detailed format string
10482 * g_app_info_add_supports_type:
10483 * @appinfo: a #GAppInfo.
10484 * @content_type: a string.
10485 * @error: a #GError.
10487 * Adds a content type to the application information to indicate the
10488 * application is capable of opening files with the given content type.
10490 * Returns: %TRUE on success, %FALSE on error.
10495 * g_app_info_can_delete:
10496 * @appinfo: a #GAppInfo
10498 * Obtains the information whether the #GAppInfo can be deleted.
10499 * See g_app_info_delete().
10501 * Returns: %TRUE if @appinfo can be deleted
10507 * g_app_info_can_remove_supports_type:
10508 * @appinfo: a #GAppInfo.
10510 * Checks if a supported content type can be removed from an application.
10512 * Returns: %TRUE if it is possible to remove supported
10513 * content types from a given @appinfo, %FALSE if not.
10518 * g_app_info_create_from_commandline:
10519 * @commandline: the commandline to use
10520 * @application_name: (allow-none): the application name, or %NULL to use @commandline
10521 * @flags: flags that can specify details of the created #GAppInfo
10522 * @error: a #GError location to store the error occurring, %NULL to ignore.
10524 * Creates a new #GAppInfo from the given information.
10526 * Note that for @commandline, the quoting rules of the Exec key of the
10527 * [freedesktop.org Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec)
10528 * are applied. For example, if the @commandline contains
10529 * percent-encoded URIs, the percent-character must be doubled in order to prevent it from
10530 * being swallowed by Exec key unquoting. See the specification for exact quoting rules.
10532 * Returns: (transfer full): new #GAppInfo for given command.
10537 * g_app_info_delete: (virtual do_delete)
10538 * @appinfo: a #GAppInfo
10540 * Tries to delete a #GAppInfo.
10542 * On some platforms, there may be a difference between user-defined
10543 * #GAppInfos which can be deleted, and system-wide ones which cannot.
10544 * See g_app_info_can_delete().
10546 * Returns: %TRUE if @appinfo has been deleted
10553 * @appinfo: a #GAppInfo.
10555 * Creates a duplicate of a #GAppInfo.
10557 * Returns: (transfer full): a duplicate of @appinfo.
10562 * g_app_info_equal:
10563 * @appinfo1: the first #GAppInfo.
10564 * @appinfo2: the second #GAppInfo.
10566 * Checks if two #GAppInfos are equal.
10568 * Returns: %TRUE if @appinfo1 is equal to @appinfo2. %FALSE otherwise.
10573 * g_app_info_get_all:
10575 * Gets a list of all of the applications currently registered
10578 * For desktop files, this includes applications that have
10579 * `NoDisplay=true` set or are excluded from display by means
10580 * of `OnlyShowIn` or `NotShowIn`. See g_app_info_should_show().
10581 * The returned list does not include applications which have
10582 * the `Hidden` key set.
10584 * Returns: (element-type GAppInfo) (transfer full): a newly allocated #GList of references to #GAppInfos.
10589 * g_app_info_get_all_for_type:
10590 * @content_type: the content type to find a #GAppInfo for
10592 * Gets a list of all #GAppInfos for a given content type,
10593 * including the recommended and fallback #GAppInfos. See
10594 * g_app_info_get_recommended_for_type() and
10595 * g_app_info_get_fallback_for_type().
10597 * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos
10598 * for given @content_type or %NULL on error.
10603 * g_app_info_get_commandline:
10604 * @appinfo: a #GAppInfo
10606 * Gets the commandline with which the application will be
10609 * Returns: a string containing the @appinfo's commandline,
10610 * or %NULL if this information is not available
10616 * g_app_info_get_default_for_type:
10617 * @content_type: the content type to find a #GAppInfo for
10618 * @must_support_uris: if %TRUE, the #GAppInfo is expected to
10621 * Gets the default #GAppInfo for a given content type.
10623 * Returns: (transfer full): #GAppInfo for given @content_type or
10629 * g_app_info_get_default_for_uri_scheme:
10630 * @uri_scheme: a string containing a URI scheme.
10632 * Gets the default application for handling URIs with
10633 * the given URI scheme. A URI scheme is the initial part
10634 * of the URI, up to but not including the ':', e.g. "http",
10637 * Returns: (transfer full): #GAppInfo for given @uri_scheme or %NULL on error.
10642 * g_app_info_get_description:
10643 * @appinfo: a #GAppInfo.
10645 * Gets a human-readable description of an installed application.
10647 * Returns: a string containing a description of the
10648 * application @appinfo, or %NULL if none.
10653 * g_app_info_get_display_name:
10654 * @appinfo: a #GAppInfo.
10656 * Gets the display name of the application. The display name is often more
10657 * descriptive to the user than the name itself.
10659 * Returns: the display name of the application for @appinfo, or the name if
10660 * no display name is available.
10666 * g_app_info_get_executable:
10667 * @appinfo: a #GAppInfo
10669 * Gets the executable's name for the installed application.
10671 * Returns: a string containing the @appinfo's application
10677 * g_app_info_get_fallback_for_type:
10678 * @content_type: the content type to find a #GAppInfo for
10680 * Gets a list of fallback #GAppInfos for a given content type, i.e.
10681 * those applications which claim to support the given content type
10682 * by MIME type subclassing and not directly.
10684 * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos
10685 * for given @content_type or %NULL on error.
10691 * g_app_info_get_icon:
10692 * @appinfo: a #GAppInfo.
10694 * Gets the icon for the application.
10696 * Returns: (transfer none): the default #GIcon for @appinfo or %NULL
10697 * if there is no default icon.
10702 * g_app_info_get_id:
10703 * @appinfo: a #GAppInfo.
10705 * Gets the ID of an application. An id is a string that
10706 * identifies the application. The exact format of the id is
10707 * platform dependent. For instance, on Unix this is the
10708 * desktop file id from the xdg menu specification.
10710 * Note that the returned ID may be %NULL, depending on how
10711 * the @appinfo has been constructed.
10713 * Returns: a string containing the application's ID.
10718 * g_app_info_get_name:
10719 * @appinfo: a #GAppInfo.
10721 * Gets the installed name of the application.
10723 * Returns: the name of the application for @appinfo.
10728 * g_app_info_get_recommended_for_type:
10729 * @content_type: the content type to find a #GAppInfo for
10731 * Gets a list of recommended #GAppInfos for a given content type, i.e.
10732 * those applications which claim to support the given content type exactly,
10733 * and not by MIME type subclassing.
10734 * Note that the first application of the list is the last used one, i.e.
10735 * the last one for which g_app_info_set_as_last_used_for_type() has been
10738 * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos
10739 * for given @content_type or %NULL on error.
10745 * g_app_info_get_supported_types:
10746 * @appinfo: a #GAppInfo that can handle files
10748 * Retrieves the list of content types that @app_info claims to support.
10749 * If this information is not provided by the environment, this function
10750 * will return %NULL.
10751 * This function does not take in consideration associations added with
10752 * g_app_info_add_supports_type(), but only those exported directly by
10755 * Returns: (transfer none) (array zero-terminated=1) (element-type utf8):
10756 * a list of content types.
10762 * g_app_info_launch:
10763 * @appinfo: a #GAppInfo
10764 * @files: (allow-none) (element-type GFile): a #GList of #GFile objects
10765 * @launch_context: (allow-none): a #GAppLaunchContext or %NULL
10766 * @error: a #GError
10768 * Launches the application. Passes @files to the launched application
10769 * as arguments, using the optional @launch_context to get information
10770 * about the details of the launcher (like what screen it is on).
10771 * On error, @error will be set accordingly.
10773 * To launch the application without arguments pass a %NULL @files list.
10775 * Note that even if the launch is successful the application launched
10776 * can fail to start if it runs into problems during startup. There is
10777 * no way to detect this.
10779 * Some URIs can be changed when passed through a GFile (for instance
10780 * unsupported URIs with strange formats like mailto:), so if you have
10781 * a textual URI you want to pass in as argument, consider using
10782 * g_app_info_launch_uris() instead.
10784 * The launched application inherits the environment of the launching
10785 * process, but it can be modified with g_app_launch_context_setenv()
10786 * and g_app_launch_context_unsetenv().
10788 * On UNIX, this function sets the `GIO_LAUNCHED_DESKTOP_FILE`
10789 * environment variable with the path of the launched desktop file and
10790 * `GIO_LAUNCHED_DESKTOP_FILE_PID` to the process id of the launched
10791 * process. This can be used to ignore `GIO_LAUNCHED_DESKTOP_FILE`,
10792 * should it be inherited by further processes. The `DISPLAY` and
10793 * `DESKTOP_STARTUP_ID` environment variables are also set, based
10794 * on information provided in @launch_context.
10796 * Returns: %TRUE on successful launch, %FALSE otherwise.
10801 * g_app_info_launch_default_for_uri:
10802 * @uri: the uri to show
10803 * @launch_context: (allow-none): an optional #GAppLaunchContext.
10804 * @error: a #GError.
10806 * Utility function that launches the default application
10807 * registered to handle the specified uri. Synchronous I/O
10808 * is done on the uri to detect the type of the file if
10811 * Returns: %TRUE on success, %FALSE on error.
10816 * g_app_info_launch_uris:
10817 * @appinfo: a #GAppInfo
10818 * @uris: (allow-none) (element-type utf8): a #GList containing URIs to launch.
10819 * @launch_context: (allow-none): a #GAppLaunchContext or %NULL
10820 * @error: a #GError
10822 * Launches the application. This passes the @uris to the launched application
10823 * as arguments, using the optional @launch_context to get information
10824 * about the details of the launcher (like what screen it is on).
10825 * On error, @error will be set accordingly.
10827 * To launch the application without arguments pass a %NULL @uris list.
10829 * Note that even if the launch is successful the application launched
10830 * can fail to start if it runs into problems during startup. There is
10831 * no way to detect this.
10833 * Returns: %TRUE on successful launch, %FALSE otherwise.
10838 * g_app_info_monitor_get:
10840 * Gets the #GAppInfoMonitor for the current thread-default main
10843 * The #GAppInfoMonitor will emit a "changed" signal in the
10844 * thread-default main context whenever the list of installed
10845 * applications (as reported by g_app_info_get_all()) may have changed.
10847 * You must only call g_object_unref() on the return value from under
10848 * the same main context as you created it.
10850 * Returns: (transfer full): a reference to a #GAppInfoMonitor
10856 * g_app_info_remove_supports_type:
10857 * @appinfo: a #GAppInfo.
10858 * @content_type: a string.
10859 * @error: a #GError.
10861 * Removes a supported type from an application, if possible.
10863 * Returns: %TRUE on success, %FALSE on error.
10868 * g_app_info_reset_type_associations:
10869 * @content_type: a content type
10871 * Removes all changes to the type associations done by
10872 * g_app_info_set_as_default_for_type(),
10873 * g_app_info_set_as_default_for_extension(),
10874 * g_app_info_add_supports_type() or
10875 * g_app_info_remove_supports_type().
10882 * g_app_info_set_as_default_for_extension:
10883 * @appinfo: a #GAppInfo.
10884 * @extension: a string containing the file extension (without the dot).
10885 * @error: a #GError.
10887 * Sets the application as the default handler for the given file extension.
10889 * Returns: %TRUE on success, %FALSE on error.
10894 * g_app_info_set_as_default_for_type:
10895 * @appinfo: a #GAppInfo.
10896 * @content_type: the content type.
10897 * @error: a #GError.
10899 * Sets the application as the default handler for a given type.
10901 * Returns: %TRUE on success, %FALSE on error.
10906 * g_app_info_set_as_last_used_for_type:
10907 * @appinfo: a #GAppInfo.
10908 * @content_type: the content type.
10909 * @error: a #GError.
10911 * Sets the application as the last used application for a given type.
10912 * This will make the application appear as first in the list returned
10913 * by g_app_info_get_recommended_for_type(), regardless of the default
10914 * application for that content type.
10916 * Returns: %TRUE on success, %FALSE on error.
10921 * g_app_info_should_show:
10922 * @appinfo: a #GAppInfo.
10924 * Checks if the application info should be shown in menus that
10925 * list available applications.
10927 * Returns: %TRUE if the @appinfo should be shown, %FALSE otherwise.
10932 * g_app_info_supports_files:
10933 * @appinfo: a #GAppInfo.
10935 * Checks if the application accepts files as arguments.
10937 * Returns: %TRUE if the @appinfo supports files.
10942 * g_app_info_supports_uris:
10943 * @appinfo: a #GAppInfo.
10945 * Checks if the application supports reading files and directories from URIs.
10947 * Returns: %TRUE if the @appinfo supports URIs.
10952 * g_app_launch_context_get_display:
10953 * @context: a #GAppLaunchContext
10954 * @info: a #GAppInfo
10955 * @files: (element-type GFile): a #GList of #GFile objects
10957 * Gets the display string for the @context. This is used to ensure new
10958 * applications are started on the same display as the launching
10959 * application, by setting the `DISPLAY` environment variable.
10961 * Returns: a display string for the display.
10966 * g_app_launch_context_get_environment:
10967 * @context: a #GAppLaunchContext
10969 * Gets the complete environment variable list to be passed to
10970 * the child process when @context is used to launch an application.
10971 * This is a %NULL-terminated array of strings, where each string has
10972 * the form `KEY=VALUE`.
10974 * Returns: (array zero-terminated=1) (transfer full): the
10975 * child's environment
10981 * g_app_launch_context_get_startup_notify_id:
10982 * @context: a #GAppLaunchContext
10983 * @info: a #GAppInfo
10984 * @files: (element-type GFile): a #GList of of #GFile objects
10986 * Initiates startup notification for the application and returns the
10987 * `DESKTOP_STARTUP_ID` for the launched operation, if supported.
10989 * Startup notification IDs are defined in the
10990 * [FreeDesktop.Org Startup Notifications standard](http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt").
10992 * Returns: a startup notification ID for the application, or %NULL if
10998 * g_app_launch_context_launch_failed:
10999 * @context: a #GAppLaunchContext.
11000 * @startup_notify_id: the startup notification id that was returned by g_app_launch_context_get_startup_notify_id().
11002 * Called when an application has failed to launch, so that it can cancel
11003 * the application startup notification started in g_app_launch_context_get_startup_notify_id().
11008 * g_app_launch_context_new:
11010 * Creates a new application launch context. This is not normally used,
11011 * instead you instantiate a subclass of this, such as #GdkAppLaunchContext.
11013 * Returns: a #GAppLaunchContext.
11018 * g_app_launch_context_setenv:
11019 * @context: a #GAppLaunchContext
11020 * @variable: the environment variable to set
11021 * @value: the value for to set the variable to.
11023 * Arranges for @variable to be set to @value in the child's
11024 * environment when @context is used to launch an application.
11031 * g_app_launch_context_unsetenv:
11032 * @context: a #GAppLaunchContext
11033 * @variable: the environment variable to remove
11035 * Arranges for @variable to be unset in the child's environment
11036 * when @context is used to launch an application.
11043 * g_application_activate:
11044 * @application: a #GApplication
11046 * Activates the application.
11048 * In essence, this results in the #GApplication::activate signal being
11049 * emitted in the primary instance.
11051 * The application must be registered before calling this function.
11058 * g_application_add_main_option_entries:
11059 * @application: a #GApplication
11060 * @entries: (array zero-terminated=1) (element-type GOptionEntry): a
11061 * %NULL-terminated list of #GOptionEntrys
11063 * Adds main option entries to be handled by @application.
11065 * This function is comparable to g_option_context_add_main_entries().
11067 * After the commandline arguments are parsed, the
11068 * #GApplication::handle-local-options signal will be emitted. At this
11069 * point, the application can inspect the values pointed to by @arg_data
11070 * in the given #GOptionEntrys.
11072 * Unlike #GOptionContext, #GApplication supports giving a %NULL
11073 * @arg_data for a non-callback #GOptionEntry. This results in the
11074 * argument in question being packed into a #GVariantDict which is also
11075 * passed to #GApplication::handle-local-options, where it can be
11076 * inspected and modified. If %G_APPLICATION_HANDLES_COMMAND_LINE is
11077 * set, then the resulting dictionary is sent to the primary instance,
11078 * where g_application_command_line_get_options_dict() will return it.
11079 * This "packing" is done according to the type of the argument --
11080 * booleans for normal flags, strings for strings, bytestrings for
11081 * filenames, etc. The packing only occurs if the flag is given (ie: we
11082 * do not pack a "false" #GVariant in the case that a flag is missing).
11084 * In general, it is recommended that all commandline arguments are
11085 * parsed locally. The options dictionary should then be used to
11086 * transmit the result of the parsing to the primary instance, where
11087 * g_variant_dict_lookup() can be used. For local options, it is
11088 * possible to either use @arg_data in the usual way, or to consult (and
11089 * potentially remove) the option from the options dictionary.
11091 * This function is new in GLib 2.40. Before then, the only real choice
11092 * was to send all of the commandline arguments (options and all) to the
11093 * primary instance for handling. #GApplication ignored them completely
11094 * on the local side. Calling this function "opts in" to the new
11095 * behaviour, and in particular, means that unrecognised options will be
11096 * treated as errors. Unrecognised options have never been ignored when
11097 * %G_APPLICATION_HANDLES_COMMAND_LINE is unset.
11099 * If #GApplication::handle-local-options needs to see the list of
11100 * filenames, then the use of %G_OPTION_REMAINING is recommended. If
11101 * @arg_data is %NULL then %G_OPTION_REMAINING can be used as a key into
11102 * the options dictionary. If you do use %G_OPTION_REMAINING then you
11103 * need to handle these arguments for yourself because once they are
11104 * consumed, they will no longer be visible to the default handling
11105 * (which treats them as filenames to be opened).
11112 * g_application_add_option_group:
11113 * @application: the #GApplication
11114 * @group: a #GOptionGroup
11116 * Adds a #GOptionGroup to the commandline handling of @application.
11118 * This function is comparable to g_option_context_add_group().
11120 * Unlike g_application_add_main_option_entries(), this function does
11121 * not deal with %NULL @arg_data and never transmits options to the
11122 * primary instance.
11124 * The reason for that is because, by the time the options arrive at the
11125 * primary instance, it is typically too late to do anything with them.
11126 * Taking the GTK option group as an example: GTK will already have been
11127 * initialised by the time the #GApplication::command-line handler runs.
11128 * In the case that this is not the first-running instance of the
11129 * application, the existing instance may already have been running for
11130 * a very long time.
11132 * This means that the options from #GOptionGroup are only really usable
11133 * in the case that the instance of the application being run is the
11134 * first instance. Passing options like `--display=` or `--gdk-debug=`
11135 * on future runs will have no effect on the existing primary instance.
11137 * Calling this function will cause the options in the supplied option
11138 * group to be parsed, but it does not cause you to be "opted in" to the
11139 * new functionality whereby unrecognised options are rejected even if
11140 * %G_APPLICATION_HANDLES_COMMAND_LINE was given.
11147 * g_application_command_line_create_file_for_arg:
11148 * @cmdline: a #GApplicationCommandLine
11149 * @arg: an argument from @cmdline
11151 * Creates a #GFile corresponding to a filename that was given as part
11152 * of the invocation of @cmdline.
11154 * This differs from g_file_new_for_commandline_arg() in that it
11155 * resolves relative pathnames using the current working directory of
11156 * the invoking process rather than the local process.
11158 * Returns: (transfer full): a new #GFile
11164 * g_application_command_line_get_arguments:
11165 * @cmdline: a #GApplicationCommandLine
11166 * @argc: (out) (allow-none): the length of the arguments array, or %NULL
11168 * Gets the list of arguments that was passed on the command line.
11170 * The strings in the array may contain non-UTF-8 data on UNIX (such as
11171 * filenames or arguments given in the system locale) but are always in
11172 * UTF-8 on Windows.
11174 * If you wish to use the return value with #GOptionContext, you must
11175 * use g_option_context_parse_strv().
11177 * The return value is %NULL-terminated and should be freed using
11180 * Returns: (array length=argc) (transfer full): the string array
11181 * containing the arguments (the argv)
11187 * g_application_command_line_get_cwd:
11188 * @cmdline: a #GApplicationCommandLine
11190 * Gets the working directory of the command line invocation.
11191 * The string may contain non-utf8 data.
11193 * It is possible that the remote application did not send a working
11194 * directory, so this may be %NULL.
11196 * The return value should not be modified or freed and is valid for as
11197 * long as @cmdline exists.
11199 * Returns: the current directory, or %NULL
11205 * g_application_command_line_get_environ:
11206 * @cmdline: a #GApplicationCommandLine
11208 * Gets the contents of the 'environ' variable of the command line
11209 * invocation, as would be returned by g_get_environ(), ie as a
11210 * %NULL-terminated list of strings in the form 'NAME=VALUE'.
11211 * The strings may contain non-utf8 data.
11213 * The remote application usually does not send an environment. Use
11214 * %G_APPLICATION_SEND_ENVIRONMENT to affect that. Even with this flag
11215 * set it is possible that the environment is still not available (due
11216 * to invocation messages from other applications).
11218 * The return value should not be modified or freed and is valid for as
11219 * long as @cmdline exists.
11221 * See g_application_command_line_getenv() if you are only interested
11222 * in the value of a single environment variable.
11224 * Returns: (array zero-terminated=1) (transfer none): the environment
11225 * strings, or %NULL if they were not sent
11231 * g_application_command_line_get_exit_status:
11232 * @cmdline: a #GApplicationCommandLine
11234 * Gets the exit status of @cmdline. See
11235 * g_application_command_line_set_exit_status() for more information.
11237 * Returns: the exit status
11243 * g_application_command_line_get_is_remote:
11244 * @cmdline: a #GApplicationCommandLine
11246 * Determines if @cmdline represents a remote invocation.
11248 * Returns: %TRUE if the invocation was remote
11254 * g_application_command_line_get_options_dict:
11255 * @cmdline: a #GApplicationCommandLine
11257 * Gets the options there were passed to g_application_command_line().
11259 * If you did not override local_command_line() then these are the same
11260 * options that were parsed according to the #GOptionEntrys added to the
11261 * application with g_application_add_main_option_entries() and possibly
11262 * modified from your GApplication::handle-local-options handler.
11264 * If no options were sent then an empty dictionary is returned so that
11265 * you don't need to check for %NULL.
11267 * Returns: (transfer none): a #GVariantDict with the options
11273 * g_application_command_line_get_platform_data:
11274 * @cmdline: #GApplicationCommandLine
11276 * Gets the platform data associated with the invocation of @cmdline.
11278 * This is a #GVariant dictionary containing information about the
11279 * context in which the invocation occurred. It typically contains
11280 * information like the current working directory and the startup
11283 * For local invocation, it will be %NULL.
11285 * Returns: (nullable): the platform data, or %NULL
11291 * g_application_command_line_get_stdin:
11292 * @cmdline: a #GApplicationCommandLine
11294 * Gets the stdin of the invoking process.
11296 * The #GInputStream can be used to read data passed to the standard
11297 * input of the invoking process.
11298 * This doesn't work on all platforms. Presently, it is only available
11299 * on UNIX when using a DBus daemon capable of passing file descriptors.
11300 * If stdin is not available then %NULL will be returned. In the
11301 * future, support may be expanded to other platforms.
11303 * You must only call this function once per commandline invocation.
11305 * Returns: (transfer full): a #GInputStream for stdin
11311 * g_application_command_line_getenv:
11312 * @cmdline: a #GApplicationCommandLine
11313 * @name: the environment variable to get
11315 * Gets the value of a particular environment variable of the command
11316 * line invocation, as would be returned by g_getenv(). The strings may
11317 * contain non-utf8 data.
11319 * The remote application usually does not send an environment. Use
11320 * %G_APPLICATION_SEND_ENVIRONMENT to affect that. Even with this flag
11321 * set it is possible that the environment is still not available (due
11322 * to invocation messages from other applications).
11324 * The return value should not be modified or freed and is valid for as
11325 * long as @cmdline exists.
11327 * Returns: the value of the variable, or %NULL if unset or unsent
11333 * g_application_command_line_print:
11334 * @cmdline: a #GApplicationCommandLine
11335 * @format: a printf-style format string
11336 * @...: arguments, as per @format
11338 * Formats a message and prints it using the stdout print handler in the
11339 * invoking process.
11341 * If @cmdline is a local invocation then this is exactly equivalent to
11342 * g_print(). If @cmdline is remote then this is equivalent to calling
11343 * g_print() in the invoking process.
11350 * g_application_command_line_printerr:
11351 * @cmdline: a #GApplicationCommandLine
11352 * @format: a printf-style format string
11353 * @...: arguments, as per @format
11355 * Formats a message and prints it using the stderr print handler in the
11356 * invoking process.
11358 * If @cmdline is a local invocation then this is exactly equivalent to
11359 * g_printerr(). If @cmdline is remote then this is equivalent to
11360 * calling g_printerr() in the invoking process.
11367 * g_application_command_line_set_exit_status:
11368 * @cmdline: a #GApplicationCommandLine
11369 * @exit_status: the exit status
11371 * Sets the exit status that will be used when the invoking process
11374 * The return value of the #GApplication::command-line signal is
11375 * passed to this function when the handler returns. This is the usual
11376 * way of setting the exit status.
11378 * In the event that you want the remote invocation to continue running
11379 * and want to decide on the exit status in the future, you can use this
11380 * call. For the case of a remote invocation, the remote process will
11381 * typically exit when the last reference is dropped on @cmdline. The
11382 * exit status of the remote process will be equal to the last value
11383 * that was set with this function.
11385 * In the case that the commandline invocation is local, the situation
11386 * is slightly more complicated. If the commandline invocation results
11387 * in the mainloop running (ie: because the use-count of the application
11388 * increased to a non-zero value) then the application is considered to
11389 * have been 'successful' in a certain sense, and the exit status is
11390 * always zero. If the application use count is zero, though, the exit
11391 * status of the local #GApplicationCommandLine is used.
11398 * g_application_get_application_id:
11399 * @application: a #GApplication
11401 * Gets the unique identifier for @application.
11403 * Returns: the identifier for @application, owned by @application
11409 * g_application_get_dbus_connection:
11410 * @application: a #GApplication
11412 * Gets the #GDBusConnection being used by the application, or %NULL.
11414 * If #GApplication is using its D-Bus backend then this function will
11415 * return the #GDBusConnection being used for uniqueness and
11416 * communication with the desktop environment and other instances of the
11419 * If #GApplication is not using D-Bus then this function will return
11420 * %NULL. This includes the situation where the D-Bus backend would
11421 * normally be in use but we were unable to connect to the bus.
11423 * This function must not be called before the application has been
11424 * registered. See g_application_get_is_registered().
11426 * Returns: (transfer none): a #GDBusConnection, or %NULL
11432 * g_application_get_dbus_object_path:
11433 * @application: a #GApplication
11435 * Gets the D-Bus object path being used by the application, or %NULL.
11437 * If #GApplication is using its D-Bus backend then this function will
11438 * return the D-Bus object path that #GApplication is using. If the
11439 * application is the primary instance then there is an object published
11440 * at this path. If the application is not the primary instance then
11441 * the result of this function is undefined.
11443 * If #GApplication is not using D-Bus then this function will return
11444 * %NULL. This includes the situation where the D-Bus backend would
11445 * normally be in use but we were unable to connect to the bus.
11447 * This function must not be called before the application has been
11448 * registered. See g_application_get_is_registered().
11450 * Returns: the object path, or %NULL
11456 * g_application_get_default:
11458 * Returns the default #GApplication instance for this process.
11460 * Normally there is only one #GApplication per process and it becomes
11461 * the default when it is created. You can exercise more control over
11462 * this by using g_application_set_default().
11464 * If there is no default application then %NULL is returned.
11466 * Returns: (transfer none): the default application for this process, or %NULL
11472 * g_application_get_flags:
11473 * @application: a #GApplication
11475 * Gets the flags for @application.
11477 * See #GApplicationFlags.
11479 * Returns: the flags for @application
11485 * g_application_get_inactivity_timeout:
11486 * @application: a #GApplication
11488 * Gets the current inactivity timeout for the application.
11490 * This is the amount of time (in milliseconds) after the last call to
11491 * g_application_release() before the application stops running.
11493 * Returns: the timeout, in milliseconds
11499 * g_application_get_is_registered:
11500 * @application: a #GApplication
11502 * Checks if @application is registered.
11504 * An application is registered if g_application_register() has been
11505 * successfully called.
11507 * Returns: %TRUE if @application is registered
11513 * g_application_get_is_remote:
11514 * @application: a #GApplication
11516 * Checks if @application is remote.
11518 * If @application is remote then it means that another instance of
11519 * application already exists (the 'primary' instance). Calls to
11520 * perform actions on @application will result in the actions being
11521 * performed by the primary instance.
11523 * The value of this property cannot be accessed before
11524 * g_application_register() has been called. See
11525 * g_application_get_is_registered().
11527 * Returns: %TRUE if @application is remote
11533 * g_application_get_resource_base_path:
11534 * @application: a #GApplication
11536 * Gets the resource base path of @application.
11538 * See g_application_set_resource_base_path() for more information.
11540 * Returns: (nullable): the base resource path, if one is set
11546 * g_application_hold:
11547 * @application: a #GApplication
11549 * Increases the use count of @application.
11551 * Use this function to indicate that the application has a reason to
11552 * continue to run. For example, g_application_hold() is called by GTK+
11553 * when a toplevel window is on the screen.
11555 * To cancel the hold, call g_application_release().
11560 * g_application_id_is_valid:
11561 * @application_id: a potential application identifier
11563 * Checks if @application_id is a valid application identifier.
11565 * A valid ID is required for calls to g_application_new() and
11566 * g_application_set_application_id().
11568 * For convenience, the restrictions on application identifiers are
11571 * - Application identifiers must contain only the ASCII characters
11572 * "[A-Z][a-z][0-9]_-." and must not begin with a digit.
11574 * - Application identifiers must contain at least one '.' (period)
11575 * character (and thus at least three elements).
11577 * - Application identifiers must not begin or end with a '.' (period)
11580 * - Application identifiers must not contain consecutive '.' (period)
11583 * - Application identifiers must not exceed 255 characters.
11585 * Returns: %TRUE if @application_id is valid
11590 * g_application_mark_busy:
11591 * @application: a #GApplication
11593 * Increases the busy count of @application.
11595 * Use this function to indicate that the application is busy, for instance
11596 * while a long running operation is pending.
11598 * The busy state will be exposed to other processes, so a session shell will
11599 * use that information to indicate the state to the user (e.g. with a
11602 * To cancel the busy indication, use g_application_unmark_busy().
11609 * g_application_new:
11610 * @application_id: (allow-none): the application id
11611 * @flags: the application flags
11613 * Creates a new #GApplication instance.
11615 * If non-%NULL, the application id must be valid. See
11616 * g_application_id_is_valid().
11618 * If no application ID is given then some features of #GApplication
11619 * (most notably application uniqueness) will be disabled.
11621 * Returns: a new #GApplication instance
11626 * g_application_open:
11627 * @application: a #GApplication
11628 * @files: (array length=n_files): an array of #GFiles to open
11629 * @n_files: the length of the @files array
11630 * @hint: a hint (or ""), but never %NULL
11632 * Opens the given files.
11634 * In essence, this results in the #GApplication::open signal being emitted
11635 * in the primary instance.
11637 * @n_files must be greater than zero.
11639 * @hint is simply passed through to the ::open signal. It is
11640 * intended to be used by applications that have multiple modes for
11641 * opening files (eg: "view" vs "edit", etc). Unless you have a need
11642 * for this functionality, you should use "".
11644 * The application must be registered before calling this function
11645 * and it must have the %G_APPLICATION_HANDLES_OPEN flag set.
11652 * g_application_quit:
11653 * @application: a #GApplication
11655 * Immediately quits the application.
11657 * Upon return to the mainloop, g_application_run() will return,
11658 * calling only the 'shutdown' function before doing so.
11660 * The hold count is ignored.
11662 * The result of calling g_application_run() again after it returns is
11670 * g_application_register:
11671 * @application: a #GApplication
11672 * @cancellable: (allow-none): a #GCancellable, or %NULL
11673 * @error: a pointer to a NULL #GError, or %NULL
11675 * Attempts registration of the application.
11677 * This is the point at which the application discovers if it is the
11678 * primary instance or merely acting as a remote for an already-existing
11679 * primary instance. This is implemented by attempting to acquire the
11680 * application identifier as a unique bus name on the session bus using
11683 * If there is no application ID or if %G_APPLICATION_NON_UNIQUE was
11684 * given, then this process will always become the primary instance.
11686 * Due to the internal architecture of GDBus, method calls can be
11687 * dispatched at any time (even if a main loop is not running). For
11688 * this reason, you must ensure that any object paths that you wish to
11689 * register are registered before calling this function.
11691 * If the application has already been registered then %TRUE is
11692 * returned with no work performed.
11694 * The #GApplication::startup signal is emitted if registration succeeds
11695 * and @application is the primary instance (including the non-unique
11698 * In the event of an error (such as @cancellable being cancelled, or a
11699 * failure to connect to the session bus), %FALSE is returned and @error
11700 * is set appropriately.
11702 * Note: the return value of this function is not an indicator that this
11703 * instance is or is not the primary instance of the application. See
11704 * g_application_get_is_remote() for that.
11706 * Returns: %TRUE if registration succeeded
11712 * g_application_release:
11713 * @application: a #GApplication
11715 * Decrease the use count of @application.
11717 * When the use count reaches zero, the application will stop running.
11719 * Never call this function except to cancel the effect of a previous
11720 * call to g_application_hold().
11725 * g_application_run:
11726 * @application: a #GApplication
11727 * @argc: the argc from main() (or 0 if @argv is %NULL)
11728 * @argv: (array length=argc) (allow-none): the argv from main(), or %NULL
11730 * Runs the application.
11732 * This function is intended to be run from main() and its return value
11733 * is intended to be returned by main(). Although you are expected to pass
11734 * the @argc, @argv parameters from main() to this function, it is possible
11735 * to pass %NULL if @argv is not available or commandline handling is not
11736 * required. Note that on Windows, @argc and @argv are ignored, and
11737 * g_win32_get_command_line() is called internally (for proper support
11738 * of Unicode commandline arguments).
11740 * #GApplication will attempt to parse the commandline arguments. You
11741 * can add commandline flags to the list of recognised options by way of
11742 * g_application_add_main_option_entries(). After this, the
11743 * #GApplication::handle-local-options signal is emitted, from which the
11744 * application can inspect the values of its #GOptionEntrys.
11746 * #GApplication::handle-local-options is a good place to handle options
11747 * such as `--version`, where an immediate reply from the local process is
11748 * desired (instead of communicating with an already-running instance).
11749 * A #GApplication::handle-local-options handler can stop further processing
11750 * by returning a non-negative value, which then becomes the exit status of
11753 * What happens next depends on the flags: if
11754 * %G_APPLICATION_HANDLES_COMMAND_LINE was specified then the remaining
11755 * commandline arguments are sent to the primary instance, where a
11756 * #GApplication::command-line signal is emitted. Otherwise, the
11757 * remaining commandline arguments are assumed to be a list of files.
11758 * If there are no files listed, the application is activated via the
11759 * #GApplication::activate signal. If there are one or more files, and
11760 * %G_APPLICATION_HANDLES_OPEN was specified then the files are opened
11761 * via the #GApplication::open signal.
11763 * If you are interested in doing more complicated local handling of the
11764 * commandline then you should implement your own #GApplication subclass
11765 * and override local_command_line(). In this case, you most likely want
11766 * to return %TRUE from your local_command_line() implementation to
11767 * suppress the default handling. See
11768 * [gapplication-example-cmdline2.c][gapplication-example-cmdline2]
11771 * If, after the above is done, the use count of the application is zero
11772 * then the exit status is returned immediately. If the use count is
11773 * non-zero then the default main context is iterated until the use count
11774 * falls to zero, at which point 0 is returned.
11776 * If the %G_APPLICATION_IS_SERVICE flag is set, then the service will
11777 * run for as much as 10 seconds with a use count of zero while waiting
11778 * for the message that caused the activation to arrive. After that,
11779 * if the use count falls to zero the application will exit immediately,
11780 * except in the case that g_application_set_inactivity_timeout() is in
11783 * This function sets the prgname (g_set_prgname()), if not already set,
11784 * to the basename of argv[0]. Since 2.38, if %G_APPLICATION_IS_SERVICE
11785 * is specified, the prgname is set to the application ID. The main
11786 * impact of this is is that the wmclass of windows created by Gtk+ will
11787 * be set accordingly, which helps the window manager determine which
11788 * application is showing the window.
11790 * Since 2.40, applications that are not explicitly flagged as services
11791 * or launchers (ie: neither %G_APPLICATION_IS_SERVICE or
11792 * %G_APPLICATION_IS_LAUNCHER are given as flags) will check (from the
11793 * default handler for local_command_line) if "--gapplication-service"
11794 * was given in the command line. If this flag is present then normal
11795 * commandline processing is interrupted and the
11796 * %G_APPLICATION_IS_SERVICE flag is set. This provides a "compromise"
11797 * solution whereby running an application directly from the commandline
11798 * will invoke it in the normal way (which can be useful for debugging)
11799 * while still allowing applications to be D-Bus activated in service
11800 * mode. The D-Bus service file should invoke the executable with
11801 * "--gapplication-service" as the sole commandline argument. This
11802 * approach is suitable for use by most graphical applications but
11803 * should not be used from applications like editors that need precise
11804 * control over when processes invoked via the commandline will exit and
11805 * what their exit status will be.
11807 * Returns: the exit status
11813 * g_application_send_notification:
11814 * @application: a #GApplication
11815 * @id: (allow-none): id of the notification, or %NULL
11816 * @notification: the #GNotification to send
11818 * Sends a notification on behalf of @application to the desktop shell.
11819 * There is no guarantee that the notification is displayed immediately,
11822 * Notifications may persist after the application exits. It will be
11823 * D-Bus-activated when the notification or one of its actions is
11826 * Modifying @notification after this call has no effect. However, the
11827 * object can be reused for a later call to this function.
11829 * @id may be any string that uniquely identifies the event for the
11830 * application. It does not need to be in any special format. For
11831 * example, "new-message" might be appropriate for a notification about
11834 * If a previous notification was sent with the same @id, it will be
11835 * replaced with @notification and shown again as if it was a new
11836 * notification. This works even for notifications sent from a previous
11837 * execution of the application, as long as @id is the same string.
11839 * @id may be %NULL, but it is impossible to replace or withdraw
11840 * notifications without an id.
11842 * If @notification is no longer relevant, it can be withdrawn with
11843 * g_application_withdraw_notification().
11850 * g_application_set_action_group:
11851 * @application: a #GApplication
11852 * @action_group: (allow-none): a #GActionGroup, or %NULL
11854 * This used to be how actions were associated with a #GApplication.
11855 * Now there is #GActionMap for that.
11858 * Deprecated: 2.32: Use the #GActionMap interface instead. Never ever
11859 * mix use of this API with use of #GActionMap on the same @application
11860 * or things will go very badly wrong. This function is known to
11861 * introduce buggy behaviour (ie: signals not emitted on changes to the
11862 * action group), so you should really use #GActionMap instead.
11867 * g_application_set_application_id:
11868 * @application: a #GApplication
11869 * @application_id: (allow-none): the identifier for @application
11871 * Sets the unique identifier for @application.
11873 * The application id can only be modified if @application has not yet
11876 * If non-%NULL, the application id must be valid. See
11877 * g_application_id_is_valid().
11884 * g_application_set_default:
11885 * @application: (allow-none): the application to set as default, or %NULL
11887 * Sets or unsets the default application for the process, as returned
11888 * by g_application_get_default().
11890 * This function does not take its own reference on @application. If
11891 * @application is destroyed then the default application will revert
11899 * g_application_set_flags:
11900 * @application: a #GApplication
11901 * @flags: the flags for @application
11903 * Sets the flags for @application.
11905 * The flags can only be modified if @application has not yet been
11908 * See #GApplicationFlags.
11915 * g_application_set_inactivity_timeout:
11916 * @application: a #GApplication
11917 * @inactivity_timeout: the timeout, in milliseconds
11919 * Sets the current inactivity timeout for the application.
11921 * This is the amount of time (in milliseconds) after the last call to
11922 * g_application_release() before the application stops running.
11924 * This call has no side effects of its own. The value set here is only
11925 * used for next time g_application_release() drops the use count to
11926 * zero. Any timeouts currently in progress are not impacted.
11933 * g_application_set_resource_base_path:
11934 * @application: a #GApplication
11935 * @resource_path: (nullable): the resource path to use
11937 * Sets (or unsets) the base resource path of @application.
11939 * The path is used to automatically load various [application
11940 * resources][gresource] such as menu layouts and action descriptions.
11941 * The various types of resources will be found at fixed names relative
11942 * to the given base path.
11944 * By default, the resource base path is determined from the application
11945 * ID by prefixing '/' and replacing each '.' with '/'. This is done at
11946 * the time that the #GApplication object is constructed. Changes to
11947 * the application ID after that point will not have an impact on the
11948 * resource base path.
11950 * As an example, if the application has an ID of "org.example.app" then
11951 * the default resource base path will be "/org/example/app". If this
11952 * is a #GtkApplication (and you have not manually changed the path)
11953 * then Gtk will then search for the menus of the application at
11954 * "/org/example/app/gtk/menus.ui".
11956 * See #GResource for more information about adding resources to your
11959 * You can disable automatic resource loading functionality by setting
11960 * the path to %NULL.
11962 * Changing the resource base path once the application is running is
11963 * not recommended. The point at which the resource path is consulted
11964 * for forming paths for various purposes is unspecified.
11971 * g_application_unmark_busy:
11972 * @application: a #GApplication
11974 * Decreases the busy count of @application.
11976 * When the busy count reaches zero, the new state will be propagated
11977 * to other processes.
11979 * This function must only be called to cancel the effect of a previous
11980 * call to g_application_mark_busy().
11987 * g_application_withdraw_notification:
11988 * @application: a #GApplication
11989 * @id: id of a previously sent notification
11991 * Withdraws a notification that was sent with
11992 * g_application_send_notification().
11994 * This call does nothing if a notification with @id doesn't exist or
11995 * the notification was never sent.
11997 * This function works even for notifications sent in previous
11998 * executions of this application, as long @id is the same as it was for
11999 * the sent notification.
12001 * Note that notifications are dismissed when the user clicks on one
12002 * of the buttons in a notification or triggers its default action, so
12003 * there is no need to explicitly withdraw the notification in that case.
12010 * g_async_initable_init_async:
12011 * @initable: a #GAsyncInitable.
12012 * @io_priority: the [I/O priority][io-priority] of the operation
12013 * @cancellable: optional #GCancellable object, %NULL to ignore.
12014 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
12015 * @user_data: the data to pass to callback function
12017 * Starts asynchronous initialization of the object implementing the
12018 * interface. This must be done before any real use of the object after
12019 * initial construction. If the object also implements #GInitable you can
12020 * optionally call g_initable_init() instead.
12022 * When the initialization is finished, @callback will be called. You can
12023 * then call g_async_initable_init_finish() to get the result of the
12026 * Implementations may also support cancellation. If @cancellable is not
12027 * %NULL, then initialization can be cancelled by triggering the cancellable
12028 * object from another thread. If the operation was cancelled, the error
12029 * %G_IO_ERROR_CANCELLED will be returned. If @cancellable is not %NULL, and
12030 * the object doesn't support cancellable initialization, the error
12031 * %G_IO_ERROR_NOT_SUPPORTED will be returned.
12033 * As with #GInitable, if the object is not initialized, or initialization
12034 * returns with an error, then all operations on the object except
12035 * g_object_ref() and g_object_unref() are considered to be invalid, and
12036 * have undefined behaviour. They will often fail with g_critical() or
12037 * g_warning(), but this must not be relied on.
12039 * Implementations of this method must be idempotent: i.e. multiple calls
12040 * to this function with the same argument should return the same results.
12041 * Only the first call initializes the object; further calls return the result
12042 * of the first call. This is so that it's safe to implement the singleton
12043 * pattern in the GObject constructor function.
12045 * For classes that also support the #GInitable interface, the default
12046 * implementation of this method will run the g_initable_init() function
12047 * in a thread, so if you want to support asynchronous initialization via
12048 * threads, just implement the #GAsyncInitable interface without overriding
12049 * any interface methods.
12056 * g_async_initable_init_finish:
12057 * @initable: a #GAsyncInitable.
12058 * @res: a #GAsyncResult.
12059 * @error: a #GError location to store the error occurring, or %NULL to
12062 * Finishes asynchronous initialization and returns the result.
12063 * See g_async_initable_init_async().
12065 * Returns: %TRUE if successful. If an error has occurred, this function
12066 * will return %FALSE and set @error appropriately if present.
12072 * g_async_initable_new_async:
12073 * @object_type: a #GType supporting #GAsyncInitable.
12074 * @io_priority: the [I/O priority][io-priority] of the operation
12075 * @cancellable: optional #GCancellable object, %NULL to ignore.
12076 * @callback: a #GAsyncReadyCallback to call when the initialization is
12078 * @user_data: the data to pass to callback function
12079 * @first_property_name: (allow-none): the name of the first property, or %NULL if no
12081 * @...: the value of the first property, followed by other property
12082 * value pairs, and ended by %NULL.
12084 * Helper function for constructing #GAsyncInitable object. This is
12085 * similar to g_object_new() but also initializes the object asynchronously.
12087 * When the initialization is finished, @callback will be called. You can
12088 * then call g_async_initable_new_finish() to get the new object and check
12096 * g_async_initable_new_finish:
12097 * @initable: the #GAsyncInitable from the callback
12098 * @res: the #GAsyncResult from the callback
12099 * @error: return location for errors, or %NULL to ignore
12101 * Finishes the async construction for the various g_async_initable_new
12102 * calls, returning the created object or %NULL on error.
12104 * Returns: (type GObject.Object) (transfer full): a newly created #GObject,
12105 * or %NULL on error. Free with g_object_unref().
12111 * g_async_initable_new_valist_async:
12112 * @object_type: a #GType supporting #GAsyncInitable.
12113 * @first_property_name: the name of the first property, followed by
12114 * the value, and other property value pairs, and ended by %NULL.
12115 * @var_args: The var args list generated from @first_property_name.
12116 * @io_priority: the [I/O priority][io-priority] of the operation
12117 * @cancellable: optional #GCancellable object, %NULL to ignore.
12118 * @callback: a #GAsyncReadyCallback to call when the initialization is
12120 * @user_data: the data to pass to callback function
12122 * Helper function for constructing #GAsyncInitable object. This is
12123 * similar to g_object_new_valist() but also initializes the object
12126 * When the initialization is finished, @callback will be called. You can
12127 * then call g_async_initable_new_finish() to get the new object and check
12135 * g_async_initable_newv_async:
12136 * @object_type: a #GType supporting #GAsyncInitable.
12137 * @n_parameters: the number of parameters in @parameters
12138 * @parameters: the parameters to use to construct the object
12139 * @io_priority: the [I/O priority][io-priority] of the operation
12140 * @cancellable: optional #GCancellable object, %NULL to ignore.
12141 * @callback: a #GAsyncReadyCallback to call when the initialization is
12143 * @user_data: the data to pass to callback function
12145 * Helper function for constructing #GAsyncInitable object. This is
12146 * similar to g_object_newv() but also initializes the object asynchronously.
12148 * When the initialization is finished, @callback will be called. You can
12149 * then call g_async_initable_new_finish() to get the new object and check
12157 * g_async_result_get_source_object:
12158 * @res: a #GAsyncResult
12160 * Gets the source object from a #GAsyncResult.
12162 * Returns: (transfer full): a new reference to the source object for the @res,
12163 * or %NULL if there is none.
12168 * g_async_result_get_user_data:
12169 * @res: a #GAsyncResult.
12171 * Gets the user data from a #GAsyncResult.
12173 * Returns: (transfer full): the user data for @res.
12178 * g_async_result_is_tagged:
12179 * @res: a #GAsyncResult
12180 * @source_tag: an application-defined tag
12182 * Checks if @res has the given @source_tag (generally a function
12183 * pointer indicating the function @res was created by).
12185 * Returns: %TRUE if @res has the indicated @source_tag, %FALSE if
12192 * g_async_result_legacy_propagate_error:
12193 * @res: a #GAsyncResult
12194 * @error: (out): a location to propagate the error to.
12196 * If @res is a #GSimpleAsyncResult, this is equivalent to
12197 * g_simple_async_result_propagate_error(). Otherwise it returns
12200 * This can be used for legacy error handling in async *_finish()
12201 * wrapper functions that traditionally handled #GSimpleAsyncResult
12202 * error returns themselves rather than calling into the virtual method.
12203 * This should not be used in new code; #GAsyncResult errors that are
12204 * set by virtual methods should also be extracted by virtual methods,
12205 * to enable subclasses to chain up correctly.
12207 * Returns: %TRUE if @error is has been filled in with an error from
12208 * @res, %FALSE if not.
12214 * g_buffered_input_stream_fill:
12215 * @stream: a #GBufferedInputStream
12216 * @count: the number of bytes that will be read from the stream
12217 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
12218 * @error: location to store the error occurring, or %NULL to ignore
12220 * Tries to read @count bytes from the stream into the buffer.
12221 * Will block during this read.
12223 * If @count is zero, returns zero and does nothing. A value of @count
12224 * larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
12226 * On success, the number of bytes read into the buffer is returned.
12227 * It is not an error if this is not the same as the requested size, as it
12228 * can happen e.g. near the end of a file. Zero is returned on end of file
12229 * (or if @count is zero), but never otherwise.
12231 * If @count is -1 then the attempted read size is equal to the number of
12232 * bytes that are required to fill the buffer.
12234 * If @cancellable is not %NULL, then the operation can be cancelled by
12235 * triggering the cancellable object from another thread. If the operation
12236 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
12237 * operation was partially finished when the operation was cancelled the
12238 * partial result will be returned, without an error.
12240 * On error -1 is returned and @error is set accordingly.
12242 * For the asynchronous, non-blocking, version of this function, see
12243 * g_buffered_input_stream_fill_async().
12245 * Returns: the number of bytes read into @stream's buffer, up to @count,
12251 * g_buffered_input_stream_fill_async:
12252 * @stream: a #GBufferedInputStream
12253 * @count: the number of bytes that will be read from the stream
12254 * @io_priority: the [I/O priority][io-priority] of the request
12255 * @cancellable: (allow-none): optional #GCancellable object
12256 * @callback: (scope async): a #GAsyncReadyCallback
12257 * @user_data: (closure): a #gpointer
12259 * Reads data into @stream's buffer asynchronously, up to @count size.
12260 * @io_priority can be used to prioritize reads. For the synchronous
12261 * version of this function, see g_buffered_input_stream_fill().
12263 * If @count is -1 then the attempted read size is equal to the number
12264 * of bytes that are required to fill the buffer.
12269 * g_buffered_input_stream_fill_finish:
12270 * @stream: a #GBufferedInputStream
12271 * @result: a #GAsyncResult
12272 * @error: a #GError
12274 * Finishes an asynchronous read.
12276 * Returns: a #gssize of the read stream, or %-1 on an error.
12281 * g_buffered_input_stream_get_available:
12282 * @stream: #GBufferedInputStream
12284 * Gets the size of the available data within the stream.
12286 * Returns: size of the available stream.
12291 * g_buffered_input_stream_get_buffer_size:
12292 * @stream: a #GBufferedInputStream
12294 * Gets the size of the input buffer.
12296 * Returns: the current buffer size.
12301 * g_buffered_input_stream_new:
12302 * @base_stream: a #GInputStream
12304 * Creates a new #GInputStream from the given @base_stream, with
12305 * a buffer set to the default size (4 kilobytes).
12307 * Returns: a #GInputStream for the given @base_stream.
12312 * g_buffered_input_stream_new_sized:
12313 * @base_stream: a #GInputStream
12316 * Creates a new #GBufferedInputStream from the given @base_stream,
12317 * with a buffer set to @size.
12319 * Returns: a #GInputStream.
12324 * g_buffered_input_stream_peek:
12325 * @stream: a #GBufferedInputStream
12326 * @buffer: (array length=count) (element-type guint8): a pointer to
12327 * an allocated chunk of memory
12328 * @offset: a #gsize
12331 * Peeks in the buffer, copying data of size @count into @buffer,
12332 * offset @offset bytes.
12334 * Returns: a #gsize of the number of bytes peeked, or -1 on error.
12339 * g_buffered_input_stream_peek_buffer:
12340 * @stream: a #GBufferedInputStream
12341 * @count: (out): a #gsize to get the number of bytes available in the buffer
12343 * Returns the buffer with the currently available bytes. The returned
12344 * buffer must not be modified and will become invalid when reading from
12345 * the stream or filling the buffer.
12347 * Returns: (array length=count) (element-type guint8) (transfer none):
12353 * g_buffered_input_stream_read_byte:
12354 * @stream: a #GBufferedInputStream
12355 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
12356 * @error: location to store the error occurring, or %NULL to ignore
12358 * Tries to read a single byte from the stream or the buffer. Will block
12359 * during this read.
12361 * On success, the byte read from the stream is returned. On end of stream
12362 * -1 is returned but it's not an exceptional error and @error is not set.
12364 * If @cancellable is not %NULL, then the operation can be cancelled by
12365 * triggering the cancellable object from another thread. If the operation
12366 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
12367 * operation was partially finished when the operation was cancelled the
12368 * partial result will be returned, without an error.
12370 * On error -1 is returned and @error is set accordingly.
12372 * Returns: the byte read from the @stream, or -1 on end of stream or error.
12377 * g_buffered_input_stream_set_buffer_size:
12378 * @stream: a #GBufferedInputStream
12381 * Sets the size of the internal buffer of @stream to @size, or to the
12382 * size of the contents of the buffer. The buffer can never be resized
12383 * smaller than its current contents.
12388 * g_buffered_output_stream_get_auto_grow:
12389 * @stream: a #GBufferedOutputStream.
12391 * Checks if the buffer automatically grows as data is added.
12393 * Returns: %TRUE if the @stream's buffer automatically grows,
12394 * %FALSE otherwise.
12399 * g_buffered_output_stream_get_buffer_size:
12400 * @stream: a #GBufferedOutputStream.
12402 * Gets the size of the buffer in the @stream.
12404 * Returns: the current size of the buffer.
12409 * g_buffered_output_stream_new:
12410 * @base_stream: a #GOutputStream.
12412 * Creates a new buffered output stream for a base stream.
12414 * Returns: a #GOutputStream for the given @base_stream.
12419 * g_buffered_output_stream_new_sized:
12420 * @base_stream: a #GOutputStream.
12423 * Creates a new buffered output stream with a given buffer size.
12425 * Returns: a #GOutputStream with an internal buffer set to @size.
12430 * g_buffered_output_stream_set_auto_grow:
12431 * @stream: a #GBufferedOutputStream.
12432 * @auto_grow: a #gboolean.
12434 * Sets whether or not the @stream's buffer should automatically grow.
12435 * If @auto_grow is true, then each write will just make the buffer
12436 * larger, and you must manually flush the buffer to actually write out
12437 * the data to the underlying stream.
12442 * g_buffered_output_stream_set_buffer_size:
12443 * @stream: a #GBufferedOutputStream.
12446 * Sets the size of the internal buffer to @size.
12452 * @bus_type: a #GBusType
12453 * @cancellable: (allow-none): a #GCancellable or %NULL
12454 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
12455 * @user_data: the data to pass to @callback
12457 * Asynchronously connects to the message bus specified by @bus_type.
12459 * When the operation is finished, @callback will be invoked. You can
12460 * then call g_bus_get_finish() to get the result of the operation.
12462 * This is a asynchronous failable function. See g_bus_get_sync() for
12463 * the synchronous version.
12470 * g_bus_get_finish:
12471 * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed
12473 * @error: return location for error or %NULL
12475 * Finishes an operation started with g_bus_get().
12477 * The returned object is a singleton, that is, shared with other
12478 * callers of g_bus_get() and g_bus_get_sync() for @bus_type. In the
12479 * event that you need a private message bus connection, use
12480 * g_dbus_address_get_for_bus_sync() and
12481 * g_dbus_connection_new_for_address().
12483 * Note that the returned #GDBusConnection object will (usually) have
12484 * the #GDBusConnection:exit-on-close property set to %TRUE.
12486 * Returns: (transfer full): a #GDBusConnection or %NULL if @error is set.
12487 * Free with g_object_unref().
12494 * @bus_type: a #GBusType
12495 * @cancellable: (allow-none): a #GCancellable or %NULL
12496 * @error: return location for error or %NULL
12498 * Synchronously connects to the message bus specified by @bus_type.
12499 * Note that the returned object may shared with other callers,
12500 * e.g. if two separate parts of a process calls this function with
12501 * the same @bus_type, they will share the same object.
12503 * This is a synchronous failable function. See g_bus_get() and
12504 * g_bus_get_finish() for the asynchronous version.
12506 * The returned object is a singleton, that is, shared with other
12507 * callers of g_bus_get() and g_bus_get_sync() for @bus_type. In the
12508 * event that you need a private message bus connection, use
12509 * g_dbus_address_get_for_bus_sync() and
12510 * g_dbus_connection_new_for_address().
12512 * Note that the returned #GDBusConnection object will (usually) have
12513 * the #GDBusConnection:exit-on-close property set to %TRUE.
12515 * Returns: (transfer full): a #GDBusConnection or %NULL if @error is set.
12516 * Free with g_object_unref().
12523 * @bus_type: the type of bus to own a name on
12524 * @name: the well-known name to own
12525 * @flags: a set of flags from the #GBusNameOwnerFlags enumeration
12526 * @bus_acquired_handler: (allow-none): handler to invoke when connected to the bus of type @bus_type or %NULL
12527 * @name_acquired_handler: (allow-none): handler to invoke when @name is acquired or %NULL
12528 * @name_lost_handler: (allow-none): handler to invoke when @name is lost or %NULL
12529 * @user_data: user data to pass to handlers
12530 * @user_data_free_func: (allow-none): function for freeing @user_data or %NULL
12532 * Starts acquiring @name on the bus specified by @bus_type and calls
12533 * @name_acquired_handler and @name_lost_handler when the name is
12534 * acquired respectively lost. Callbacks will be invoked in the
12535 * [thread-default main context][g-main-context-push-thread-default]
12536 * of the thread you are calling this function from.
12538 * You are guaranteed that one of the @name_acquired_handler and @name_lost_handler
12539 * callbacks will be invoked after calling this function - there are three
12542 * - @name_lost_handler with a %NULL connection (if a connection to the bus
12545 * - @bus_acquired_handler then @name_lost_handler (if the name can't be
12548 * - @bus_acquired_handler then @name_acquired_handler (if the name was
12551 * When you are done owning the name, just call g_bus_unown_name()
12552 * with the owner id this function returns.
12554 * If the name is acquired or lost (for example another application
12555 * could acquire the name if you allow replacement or the application
12556 * currently owning the name exits), the handlers are also invoked.
12557 * If the #GDBusConnection that is used for attempting to own the name
12558 * closes, then @name_lost_handler is invoked since it is no longer
12559 * possible for other processes to access the process.
12561 * You cannot use g_bus_own_name() several times for the same name (unless
12562 * interleaved with calls to g_bus_unown_name()) - only the first call
12565 * Another guarantee is that invocations of @name_acquired_handler
12566 * and @name_lost_handler are guaranteed to alternate; that
12567 * is, if @name_acquired_handler is invoked then you are
12568 * guaranteed that the next time one of the handlers is invoked, it
12569 * will be @name_lost_handler. The reverse is also true.
12571 * If you plan on exporting objects (using e.g.
12572 * g_dbus_connection_register_object()), note that it is generally too late
12573 * to export the objects in @name_acquired_handler. Instead, you can do this
12574 * in @bus_acquired_handler since you are guaranteed that this will run
12575 * before @name is requested from the bus.
12577 * This behavior makes it very simple to write applications that wants
12578 * to [own names][gdbus-owning-names] and export objects.
12579 * Simply register objects to be exported in @bus_acquired_handler and
12580 * unregister the objects (if any) in @name_lost_handler.
12582 * Returns: an identifier (never 0) that an be used with
12583 * g_bus_unown_name() to stop owning the name.
12589 * g_bus_own_name_on_connection:
12590 * @connection: a #GDBusConnection
12591 * @name: the well-known name to own
12592 * @flags: a set of flags from the #GBusNameOwnerFlags enumeration
12593 * @name_acquired_handler: (allow-none): handler to invoke when @name is acquired or %NULL
12594 * @name_lost_handler: (allow-none): handler to invoke when @name is lost or %NULL
12595 * @user_data: user data to pass to handlers
12596 * @user_data_free_func: (allow-none): function for freeing @user_data or %NULL
12598 * Like g_bus_own_name() but takes a #GDBusConnection instead of a
12601 * Returns: an identifier (never 0) that an be used with
12602 * g_bus_unown_name() to stop owning the name
12608 * g_bus_own_name_on_connection_with_closures: (rename-to g_bus_own_name_on_connection)
12609 * @connection: a #GDBusConnection
12610 * @name: the well-known name to own
12611 * @flags: a set of flags from the #GBusNameOwnerFlags enumeration
12612 * @name_acquired_closure: (allow-none): #GClosure to invoke when @name is
12613 * acquired or %NULL
12614 * @name_lost_closure: (allow-none): #GClosure to invoke when @name is lost
12617 * Version of g_bus_own_name_on_connection() using closures instead of
12618 * callbacks for easier binding in other languages.
12620 * Returns: an identifier (never 0) that an be used with
12621 * g_bus_unown_name() to stop owning the name.
12627 * g_bus_own_name_with_closures: (rename-to g_bus_own_name)
12628 * @bus_type: the type of bus to own a name on
12629 * @name: the well-known name to own
12630 * @flags: a set of flags from the #GBusNameOwnerFlags enumeration
12631 * @bus_acquired_closure: (allow-none): #GClosure to invoke when connected to
12632 * the bus of type @bus_type or %NULL
12633 * @name_acquired_closure: (allow-none): #GClosure to invoke when @name is
12634 * acquired or %NULL
12635 * @name_lost_closure: (allow-none): #GClosure to invoke when @name is lost or
12638 * Version of g_bus_own_name() using closures instead of callbacks for
12639 * easier binding in other languages.
12641 * Returns: an identifier (never 0) that an be used with
12642 * g_bus_unown_name() to stop owning the name.
12648 * g_bus_unown_name:
12649 * @owner_id: an identifier obtained from g_bus_own_name()
12651 * Stops owning a name.
12658 * g_bus_unwatch_name:
12659 * @watcher_id: An identifier obtained from g_bus_watch_name()
12661 * Stops watching a name.
12668 * g_bus_watch_name:
12669 * @bus_type: The type of bus to watch a name on.
12670 * @name: The name (well-known or unique) to watch.
12671 * @flags: Flags from the #GBusNameWatcherFlags enumeration.
12672 * @name_appeared_handler: (allow-none): Handler to invoke when @name is known to exist or %NULL.
12673 * @name_vanished_handler: (allow-none): Handler to invoke when @name is known to not exist or %NULL.
12674 * @user_data: User data to pass to handlers.
12675 * @user_data_free_func: (allow-none): Function for freeing @user_data or %NULL.
12677 * Starts watching @name on the bus specified by @bus_type and calls
12678 * @name_appeared_handler and @name_vanished_handler when the name is
12679 * known to have a owner respectively known to lose its
12680 * owner. Callbacks will be invoked in the
12681 * [thread-default main context][g-main-context-push-thread-default]
12682 * of the thread you are calling this function from.
12684 * You are guaranteed that one of the handlers will be invoked after
12685 * calling this function. When you are done watching the name, just
12686 * call g_bus_unwatch_name() with the watcher id this function
12689 * If the name vanishes or appears (for example the application owning
12690 * the name could restart), the handlers are also invoked. If the
12691 * #GDBusConnection that is used for watching the name disconnects, then
12692 * @name_vanished_handler is invoked since it is no longer
12693 * possible to access the name.
12695 * Another guarantee is that invocations of @name_appeared_handler
12696 * and @name_vanished_handler are guaranteed to alternate; that
12697 * is, if @name_appeared_handler is invoked then you are
12698 * guaranteed that the next time one of the handlers is invoked, it
12699 * will be @name_vanished_handler. The reverse is also true.
12701 * This behavior makes it very simple to write applications that want
12702 * to take action when a certain [name exists][gdbus-watching-names].
12703 * Basically, the application should create object proxies in
12704 * @name_appeared_handler and destroy them again (if any) in
12705 * @name_vanished_handler.
12707 * Returns: An identifier (never 0) that an be used with
12708 * g_bus_unwatch_name() to stop watching the name.
12714 * g_bus_watch_name_on_connection:
12715 * @connection: A #GDBusConnection.
12716 * @name: The name (well-known or unique) to watch.
12717 * @flags: Flags from the #GBusNameWatcherFlags enumeration.
12718 * @name_appeared_handler: (allow-none): Handler to invoke when @name is known to exist or %NULL.
12719 * @name_vanished_handler: (allow-none): Handler to invoke when @name is known to not exist or %NULL.
12720 * @user_data: User data to pass to handlers.
12721 * @user_data_free_func: (allow-none): Function for freeing @user_data or %NULL.
12723 * Like g_bus_watch_name() but takes a #GDBusConnection instead of a
12726 * Returns: An identifier (never 0) that an be used with
12727 * g_bus_unwatch_name() to stop watching the name.
12733 * g_bus_watch_name_on_connection_with_closures: (rename-to g_bus_watch_name_on_connection)
12734 * @connection: A #GDBusConnection.
12735 * @name: The name (well-known or unique) to watch.
12736 * @flags: Flags from the #GBusNameWatcherFlags enumeration.
12737 * @name_appeared_closure: (allow-none): #GClosure to invoke when @name is known
12738 * to exist or %NULL.
12739 * @name_vanished_closure: (allow-none): #GClosure to invoke when @name is known
12740 * to not exist or %NULL.
12742 * Version of g_bus_watch_name_on_connection() using closures instead of callbacks for
12743 * easier binding in other languages.
12745 * Returns: An identifier (never 0) that an be used with
12746 * g_bus_unwatch_name() to stop watching the name.
12752 * g_bus_watch_name_with_closures: (rename-to g_bus_watch_name)
12753 * @bus_type: The type of bus to watch a name on.
12754 * @name: The name (well-known or unique) to watch.
12755 * @flags: Flags from the #GBusNameWatcherFlags enumeration.
12756 * @name_appeared_closure: (allow-none): #GClosure to invoke when @name is known
12757 * to exist or %NULL.
12758 * @name_vanished_closure: (allow-none): #GClosure to invoke when @name is known
12759 * to not exist or %NULL.
12761 * Version of g_bus_watch_name() using closures instead of callbacks for
12762 * easier binding in other languages.
12764 * Returns: An identifier (never 0) that an be used with
12765 * g_bus_unwatch_name() to stop watching the name.
12771 * g_bytes_icon_get_bytes:
12774 * Gets the #GBytes associated with the given @icon.
12776 * Returns: (transfer none): a #GBytes, or %NULL.
12782 * g_bytes_icon_new:
12783 * @bytes: a #GBytes.
12785 * Creates a new icon for a bytes.
12787 * Returns: (transfer full) (type GBytesIcon): a #GIcon for the given
12788 * @bytes, or %NULL on error.
12794 * g_cancellable_cancel:
12795 * @cancellable: a #GCancellable object.
12797 * Will set @cancellable to cancelled, and will emit the
12798 * #GCancellable::cancelled signal. (However, see the warning about
12799 * race conditions in the documentation for that signal if you are
12800 * planning to connect to it.)
12802 * This function is thread-safe. In other words, you can safely call
12803 * it from a thread other than the one running the operation that was
12804 * passed the @cancellable.
12806 * The convention within gio is that cancelling an asynchronous
12807 * operation causes it to complete asynchronously. That is, if you
12808 * cancel the operation from the same thread in which it is running,
12809 * then the operation's #GAsyncReadyCallback will not be invoked until
12810 * the application returns to the main loop.
12815 * g_cancellable_connect:
12816 * @cancellable: A #GCancellable.
12817 * @callback: The #GCallback to connect.
12818 * @data: Data to pass to @callback.
12819 * @data_destroy_func: (allow-none): Free function for @data or %NULL.
12821 * Convenience function to connect to the #GCancellable::cancelled
12822 * signal. Also handles the race condition that may happen
12823 * if the cancellable is cancelled right before connecting.
12825 * @callback is called at most once, either directly at the
12826 * time of the connect if @cancellable is already cancelled,
12827 * or when @cancellable is cancelled in some thread.
12829 * @data_destroy_func will be called when the handler is
12830 * disconnected, or immediately if the cancellable is already
12833 * See #GCancellable::cancelled for details on how to use this.
12835 * Since GLib 2.40, the lock protecting @cancellable is not held when
12836 * @callback is invoked. This lifts a restriction in place for
12837 * earlier GLib versions which now makes it easier to write cleanup
12838 * code that unconditionally invokes e.g. g_cancellable_cancel().
12840 * Returns: The id of the signal handler or 0 if @cancellable has already
12847 * g_cancellable_disconnect:
12848 * @cancellable: (allow-none): A #GCancellable or %NULL.
12849 * @handler_id: Handler id of the handler to be disconnected, or %0.
12851 * Disconnects a handler from a cancellable instance similar to
12852 * g_signal_handler_disconnect(). Additionally, in the event that a
12853 * signal handler is currently running, this call will block until the
12854 * handler has finished. Calling this function from a
12855 * #GCancellable::cancelled signal handler will therefore result in a
12858 * This avoids a race condition where a thread cancels at the
12859 * same time as the cancellable operation is finished and the
12860 * signal handler is removed. See #GCancellable::cancelled for
12861 * details on how to use this.
12863 * If @cancellable is %NULL or @handler_id is %0 this function does
12871 * g_cancellable_get_current:
12873 * Gets the top cancellable from the stack.
12875 * Returns: (nullable) (transfer none): a #GCancellable from the top
12876 * of the stack, or %NULL if the stack is empty.
12881 * g_cancellable_get_fd:
12882 * @cancellable: a #GCancellable.
12884 * Gets the file descriptor for a cancellable job. This can be used to
12885 * implement cancellable operations on Unix systems. The returned fd will
12886 * turn readable when @cancellable is cancelled.
12888 * You are not supposed to read from the fd yourself, just check for
12889 * readable status. Reading to unset the readable status is done
12890 * with g_cancellable_reset().
12892 * After a successful return from this function, you should use
12893 * g_cancellable_release_fd() to free up resources allocated for
12894 * the returned file descriptor.
12896 * See also g_cancellable_make_pollfd().
12898 * Returns: A valid file descriptor. %-1 if the file descriptor
12899 * is not supported, or on errors.
12904 * g_cancellable_is_cancelled:
12905 * @cancellable: (allow-none): a #GCancellable or %NULL
12907 * Checks if a cancellable job has been cancelled.
12909 * Returns: %TRUE if @cancellable is cancelled,
12910 * FALSE if called with %NULL or if item is not cancelled.
12915 * g_cancellable_make_pollfd:
12916 * @cancellable: (allow-none): a #GCancellable or %NULL
12917 * @pollfd: a pointer to a #GPollFD
12919 * Creates a #GPollFD corresponding to @cancellable; this can be passed
12920 * to g_poll() and used to poll for cancellation. This is useful both
12921 * for unix systems without a native poll and for portability to
12924 * When this function returns %TRUE, you should use
12925 * g_cancellable_release_fd() to free up resources allocated for the
12926 * @pollfd. After a %FALSE return, do not call g_cancellable_release_fd().
12928 * If this function returns %FALSE, either no @cancellable was given or
12929 * resource limits prevent this function from allocating the necessary
12930 * structures for polling. (On Linux, you will likely have reached
12931 * the maximum number of file descriptors.) The suggested way to handle
12932 * these cases is to ignore the @cancellable.
12934 * You are not supposed to read from the fd yourself, just check for
12935 * readable status. Reading to unset the readable status is done
12936 * with g_cancellable_reset().
12938 * Returns: %TRUE if @pollfd was successfully initialized, %FALSE on
12939 * failure to prepare the cancellable.
12945 * g_cancellable_new:
12947 * Creates a new #GCancellable object.
12949 * Applications that want to start one or more operations
12950 * that should be cancellable should create a #GCancellable
12951 * and pass it to the operations.
12953 * One #GCancellable can be used in multiple consecutive
12954 * operations or in multiple concurrent operations.
12956 * Returns: a #GCancellable.
12961 * g_cancellable_pop_current:
12962 * @cancellable: a #GCancellable object
12964 * Pops @cancellable off the cancellable stack (verifying that @cancellable
12965 * is on the top of the stack).
12970 * g_cancellable_push_current:
12971 * @cancellable: a #GCancellable object
12973 * Pushes @cancellable onto the cancellable stack. The current
12974 * cancellable can then be received using g_cancellable_get_current().
12976 * This is useful when implementing cancellable operations in
12977 * code that does not allow you to pass down the cancellable object.
12979 * This is typically called automatically by e.g. #GFile operations,
12980 * so you rarely have to call this yourself.
12985 * g_cancellable_release_fd:
12986 * @cancellable: a #GCancellable
12988 * Releases a resources previously allocated by g_cancellable_get_fd()
12989 * or g_cancellable_make_pollfd().
12991 * For compatibility reasons with older releases, calling this function
12992 * is not strictly required, the resources will be automatically freed
12993 * when the @cancellable is finalized. However, the @cancellable will
12994 * block scarce file descriptors until it is finalized if this function
12995 * is not called. This can cause the application to run out of file
12996 * descriptors when many #GCancellables are used at the same time.
13003 * g_cancellable_reset:
13004 * @cancellable: a #GCancellable object.
13006 * Resets @cancellable to its uncancelled state.
13008 * If cancellable is currently in use by any cancellable operation
13009 * then the behavior of this function is undefined.
13014 * g_cancellable_set_error_if_cancelled:
13015 * @cancellable: (allow-none): a #GCancellable or %NULL
13016 * @error: #GError to append error state to
13018 * If the @cancellable is cancelled, sets the error to notify
13019 * that the operation was cancelled.
13021 * Returns: %TRUE if @cancellable was cancelled, %FALSE if it was not
13026 * g_cancellable_source_new: (skip)
13027 * @cancellable: (allow-none): a #GCancellable, or %NULL
13029 * Creates a source that triggers if @cancellable is cancelled and
13030 * calls its callback of type #GCancellableSourceFunc. This is
13031 * primarily useful for attaching to another (non-cancellable) source
13032 * with g_source_add_child_source() to add cancellability to it.
13034 * For convenience, you can call this with a %NULL #GCancellable,
13035 * in which case the source will never trigger.
13037 * Returns: (transfer full): the new #GSource.
13043 * g_charset_converter_get_num_fallbacks:
13044 * @converter: a #GCharsetConverter
13046 * Gets the number of fallbacks that @converter has applied so far.
13048 * Returns: the number of fallbacks that @converter has applied
13054 * g_charset_converter_get_use_fallback:
13055 * @converter: a #GCharsetConverter
13057 * Gets the #GCharsetConverter:use-fallback property.
13059 * Returns: %TRUE if fallbacks are used by @converter
13065 * g_charset_converter_new:
13066 * @to_charset: destination charset
13067 * @from_charset: source charset
13068 * @error: #GError for error reporting, or %NULL to ignore.
13070 * Creates a new #GCharsetConverter.
13072 * Returns: a new #GCharsetConverter or %NULL on error.
13078 * g_charset_converter_set_use_fallback:
13079 * @converter: a #GCharsetConverter
13080 * @use_fallback: %TRUE to use fallbacks
13082 * Sets the #GCharsetConverter:use-fallback property.
13089 * g_content_type_can_be_executable:
13090 * @type: a content type string
13092 * Checks if a content type can be executable. Note that for instance
13093 * things like text files can be executables (i.e. scripts and batch files).
13095 * Returns: %TRUE if the file type corresponds to a type that
13096 * can be executable, %FALSE otherwise.
13101 * g_content_type_equals:
13102 * @type1: a content type string
13103 * @type2: a content type string
13105 * Compares two content types for equality.
13107 * Returns: %TRUE if the two strings are identical or equivalent,
13108 * %FALSE otherwise.
13113 * g_content_type_from_mime_type:
13114 * @mime_type: a mime type string
13116 * Tries to find a content type based on the mime type name.
13118 * Returns: (nullable): Newly allocated string with content type or
13119 * %NULL. Free with g_free()
13125 * g_content_type_get_description:
13126 * @type: a content type string
13128 * Gets the human readable description of the content type.
13130 * Returns: a short description of the content type @type. Free the
13131 * returned string with g_free()
13136 * g_content_type_get_generic_icon_name:
13137 * @type: a content type string
13139 * Gets the generic icon name for a content type.
13142 * [shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec)
13143 * specification for more on the generic icon name.
13145 * Returns: (allow-none): the registered generic icon name for the given @type,
13146 * or %NULL if unknown. Free with g_free()
13152 * g_content_type_get_icon:
13153 * @type: a content type string
13155 * Gets the icon for a content type.
13157 * Returns: (transfer full): #GIcon corresponding to the content type. Free the returned
13158 * object with g_object_unref()
13163 * g_content_type_get_mime_type:
13164 * @type: a content type string
13166 * Gets the mime type for the content type, if one is registered.
13168 * Returns: (nullable): the registered mime type for the given @type,
13169 * or %NULL if unknown.
13174 * g_content_type_get_symbolic_icon:
13175 * @type: a content type string
13177 * Gets the symbolic icon for a content type.
13179 * Returns: (transfer full): symbolic #GIcon corresponding to the content type.
13180 * Free the returned object with g_object_unref()
13186 * g_content_type_guess:
13187 * @filename: (allow-none): a string, or %NULL
13188 * @data: (allow-none) (array length=data_size): a stream of data, or %NULL
13189 * @data_size: the size of @data
13190 * @result_uncertain: (allow-none) (out): return location for the certainty
13191 * of the result, or %NULL
13193 * Guesses the content type based on example data. If the function is
13194 * uncertain, @result_uncertain will be set to %TRUE. Either @filename
13195 * or @data may be %NULL, in which case the guess will be based solely
13196 * on the other argument.
13198 * Returns: a string indicating a guessed content type for the
13199 * given data. Free with g_free()
13204 * g_content_type_guess_for_tree:
13205 * @root: the root of the tree to guess a type for
13207 * Tries to guess the type of the tree with root @root, by
13208 * looking at the files it contains. The result is an array
13209 * of content types, with the best guess coming first.
13211 * The types returned all have the form x-content/foo, e.g.
13212 * x-content/audio-cdda (for audio CDs) or x-content/image-dcf
13213 * (for a camera memory card). See the
13214 * [shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec)
13215 * specification for more on x-content types.
13217 * This function is useful in the implementation of
13218 * g_mount_guess_content_type().
13220 * Returns: (transfer full) (array zero-terminated=1): an %NULL-terminated
13221 * array of zero or more content types. Free with g_strfreev()
13227 * g_content_type_is_a:
13228 * @type: a content type string
13229 * @supertype: a content type string
13231 * Determines if @type is a subset of @supertype.
13233 * Returns: %TRUE if @type is a kind of @supertype,
13234 * %FALSE otherwise.
13239 * g_content_type_is_unknown:
13240 * @type: a content type string
13242 * Checks if the content type is the generic "unknown" type.
13243 * On UNIX this is the "application/octet-stream" mimetype,
13244 * while on win32 it is "*".
13246 * Returns: %TRUE if the type is the unknown type.
13251 * g_content_types_get_registered:
13253 * Gets a list of strings containing all the registered content types
13254 * known to the system. The list and its data should be freed using
13255 * g_list_free_full (list, g_free).
13257 * Returns: (element-type utf8) (transfer full): list of the registered
13263 * g_converter_convert:
13264 * @converter: a #GConverter.
13265 * @inbuf: (array length=inbuf_size) (element-type guint8): the buffer
13266 * containing the data to convert.
13267 * @inbuf_size: the number of bytes in @inbuf
13268 * @outbuf: a buffer to write converted data in.
13269 * @outbuf_size: the number of bytes in @outbuf, must be at least one
13270 * @flags: a #GConverterFlags controlling the conversion details
13271 * @bytes_read: (out): will be set to the number of bytes read from @inbuf on success
13272 * @bytes_written: (out): will be set to the number of bytes written to @outbuf on success
13273 * @error: location to store the error occurring, or %NULL to ignore
13275 * This is the main operation used when converting data. It is to be called
13276 * multiple times in a loop, and each time it will do some work, i.e.
13277 * producing some output (in @outbuf) or consuming some input (from @inbuf) or
13278 * both. If its not possible to do any work an error is returned.
13280 * Note that a single call may not consume all input (or any input at all).
13281 * Also a call may produce output even if given no input, due to state stored
13282 * in the converter producing output.
13284 * If any data was either produced or consumed, and then an error happens, then
13285 * only the successful conversion is reported and the error is returned on the
13288 * A full conversion loop involves calling this method repeatedly, each time
13289 * giving it new input and space output space. When there is no more input
13290 * data after the data in @inbuf, the flag %G_CONVERTER_INPUT_AT_END must be set.
13291 * The loop will be (unless some error happens) returning %G_CONVERTER_CONVERTED
13292 * each time until all data is consumed and all output is produced, then
13293 * %G_CONVERTER_FINISHED is returned instead. Note, that %G_CONVERTER_FINISHED
13294 * may be returned even if %G_CONVERTER_INPUT_AT_END is not set, for instance
13295 * in a decompression converter where the end of data is detectable from the
13296 * data (and there might even be other data after the end of the compressed data).
13298 * When some data has successfully been converted @bytes_read and is set to
13299 * the number of bytes read from @inbuf, and @bytes_written is set to indicate
13300 * how many bytes was written to @outbuf. If there are more data to output
13301 * or consume (i.e. unless the %G_CONVERTER_INPUT_AT_END is specified) then
13302 * %G_CONVERTER_CONVERTED is returned, and if no more data is to be output
13303 * then %G_CONVERTER_FINISHED is returned.
13305 * On error %G_CONVERTER_ERROR is returned and @error is set accordingly.
13306 * Some errors need special handling:
13308 * %G_IO_ERROR_NO_SPACE is returned if there is not enough space
13309 * to write the resulting converted data, the application should
13310 * call the function again with a larger @outbuf to continue.
13312 * %G_IO_ERROR_PARTIAL_INPUT is returned if there is not enough
13313 * input to fully determine what the conversion should produce,
13314 * and the %G_CONVERTER_INPUT_AT_END flag is not set. This happens for
13315 * example with an incomplete multibyte sequence when converting text,
13316 * or when a regexp matches up to the end of the input (and may match
13317 * further input). It may also happen when @inbuf_size is zero and
13318 * there is no more data to produce.
13320 * When this happens the application should read more input and then
13321 * call the function again. If further input shows that there is no
13322 * more data call the function again with the same data but with
13323 * the %G_CONVERTER_INPUT_AT_END flag set. This may cause the conversion
13324 * to finish as e.g. in the regexp match case (or, to fail again with
13325 * %G_IO_ERROR_PARTIAL_INPUT in e.g. a charset conversion where the
13326 * input is actually partial).
13328 * After g_converter_convert() has returned %G_CONVERTER_FINISHED the
13329 * converter object is in an invalid state where its not allowed
13330 * to call g_converter_convert() anymore. At this time you can only
13331 * free the object or call g_converter_reset() to reset it to the
13334 * If the flag %G_CONVERTER_FLUSH is set then conversion is modified
13335 * to try to write out all internal state to the output. The application
13336 * has to call the function multiple times with the flag set, and when
13337 * the available input has been consumed and all internal state has
13338 * been produced then %G_CONVERTER_FLUSHED (or %G_CONVERTER_FINISHED if
13339 * really at the end) is returned instead of %G_CONVERTER_CONVERTED.
13340 * This is somewhat similar to what happens at the end of the input stream,
13341 * but done in the middle of the data.
13343 * This has different meanings for different conversions. For instance
13344 * in a compression converter it would mean that we flush all the
13345 * compression state into output such that if you uncompress the
13346 * compressed data you get back all the input data. Doing this may
13347 * make the final file larger due to padding though. Another example
13348 * is a regexp conversion, where if you at the end of the flushed data
13349 * have a match, but there is also a potential longer match. In the
13350 * non-flushed case we would ask for more input, but when flushing we
13351 * treat this as the end of input and do the match.
13353 * Flushing is not always possible (like if a charset converter flushes
13354 * at a partial multibyte sequence). Converters are supposed to try
13355 * to produce as much output as possible and then return an error
13356 * (typically %G_IO_ERROR_PARTIAL_INPUT).
13358 * Returns: a #GConverterResult, %G_CONVERTER_ERROR on error.
13364 * g_converter_input_stream_get_converter:
13365 * @converter_stream: a #GConverterInputStream
13367 * Gets the #GConverter that is used by @converter_stream.
13369 * Returns: (transfer none): the converter of the converter input stream
13375 * g_converter_input_stream_new:
13376 * @base_stream: a #GInputStream
13377 * @converter: a #GConverter
13379 * Creates a new converter input stream for the @base_stream.
13381 * Returns: a new #GInputStream.
13386 * g_converter_output_stream_get_converter:
13387 * @converter_stream: a #GConverterOutputStream
13389 * Gets the #GConverter that is used by @converter_stream.
13391 * Returns: (transfer none): the converter of the converter output stream
13397 * g_converter_output_stream_new:
13398 * @base_stream: a #GOutputStream
13399 * @converter: a #GConverter
13401 * Creates a new converter output stream for the @base_stream.
13403 * Returns: a new #GOutputStream.
13408 * g_converter_reset:
13409 * @converter: a #GConverter.
13411 * Resets all internal state in the converter, making it behave
13412 * as if it was just created. If the converter has any internal
13413 * state that would produce output then that output is lost.
13420 * g_credentials_get_native: (skip)
13421 * @credentials: A #GCredentials.
13422 * @native_type: The type of native credentials to get.
13424 * Gets a pointer to native credentials of type @native_type from
13427 * It is a programming error (which will cause an warning to be
13428 * logged) to use this method if there is no #GCredentials support for
13429 * the OS or if @native_type isn't supported by the OS.
13431 * Returns: The pointer to native credentials or %NULL if the
13432 * operation there is no #GCredentials support for the OS or if
13433 * @native_type isn't supported by the OS. Do not free the returned
13434 * data, it is owned by @credentials.
13440 * g_credentials_get_unix_pid:
13441 * @credentials: A #GCredentials
13442 * @error: Return location for error or %NULL.
13444 * Tries to get the UNIX process identifier from @credentials. This
13445 * method is only available on UNIX platforms.
13447 * This operation can fail if #GCredentials is not supported on the
13448 * OS or if the native credentials type does not contain information
13449 * about the UNIX process ID.
13451 * Returns: The UNIX process ID, or -1 if @error is set.
13457 * g_credentials_get_unix_user:
13458 * @credentials: A #GCredentials
13459 * @error: Return location for error or %NULL.
13461 * Tries to get the UNIX user identifier from @credentials. This
13462 * method is only available on UNIX platforms.
13464 * This operation can fail if #GCredentials is not supported on the
13465 * OS or if the native credentials type does not contain information
13466 * about the UNIX user.
13468 * Returns: The UNIX user identifier or -1 if @error is set.
13474 * g_credentials_is_same_user:
13475 * @credentials: A #GCredentials.
13476 * @other_credentials: A #GCredentials.
13477 * @error: Return location for error or %NULL.
13479 * Checks if @credentials and @other_credentials is the same user.
13481 * This operation can fail if #GCredentials is not supported on the
13484 * Returns: %TRUE if @credentials and @other_credentials has the same
13485 * user, %FALSE otherwise or if @error is set.
13491 * g_credentials_new:
13493 * Creates a new #GCredentials object with credentials matching the
13494 * the current process.
13496 * Returns: A #GCredentials. Free with g_object_unref().
13502 * g_credentials_set_native:
13503 * @credentials: A #GCredentials.
13504 * @native_type: The type of native credentials to set.
13505 * @native: A pointer to native credentials.
13507 * Copies the native credentials of type @native_type from @native
13508 * into @credentials.
13510 * It is a programming error (which will cause an warning to be
13511 * logged) to use this method if there is no #GCredentials support for
13512 * the OS or if @native_type isn't supported by the OS.
13519 * g_credentials_set_unix_user:
13520 * @credentials: A #GCredentials.
13521 * @uid: The UNIX user identifier to set.
13522 * @error: Return location for error or %NULL.
13524 * Tries to set the UNIX user identifier on @credentials. This method
13525 * is only available on UNIX platforms.
13527 * This operation can fail if #GCredentials is not supported on the
13528 * OS or if the native credentials type does not contain information
13529 * about the UNIX user. It can also fail if the OS does not allow the
13530 * use of "spoofed" credentials.
13532 * Returns: %TRUE if @uid was set, %FALSE if error is set.
13538 * g_credentials_to_string:
13539 * @credentials: A #GCredentials object.
13541 * Creates a human-readable textual representation of @credentials
13542 * that can be used in logging and debug messages. The format of the
13543 * returned string may change in future GLib release.
13545 * Returns: A string that should be freed with g_free().
13551 * g_data_input_stream_get_byte_order:
13552 * @stream: a given #GDataInputStream.
13554 * Gets the byte order for the data input stream.
13556 * Returns: the @stream's current #GDataStreamByteOrder.
13561 * g_data_input_stream_get_newline_type:
13562 * @stream: a given #GDataInputStream.
13564 * Gets the current newline type for the @stream.
13566 * Returns: #GDataStreamNewlineType for the given @stream.
13571 * g_data_input_stream_new:
13572 * @base_stream: a #GInputStream.
13574 * Creates a new data input stream for the @base_stream.
13576 * Returns: a new #GDataInputStream.
13581 * g_data_input_stream_read_byte:
13582 * @stream: a given #GDataInputStream.
13583 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
13584 * @error: #GError for error reporting.
13586 * Reads an unsigned 8-bit/1-byte value from @stream.
13588 * Returns: an unsigned 8-bit/1-byte value read from the @stream or %0
13589 * if an error occurred.
13594 * g_data_input_stream_read_int16:
13595 * @stream: a given #GDataInputStream.
13596 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
13597 * @error: #GError for error reporting.
13599 * Reads a 16-bit/2-byte value from @stream.
13601 * In order to get the correct byte order for this read operation,
13602 * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().
13604 * Returns: a signed 16-bit/2-byte value read from @stream or %0 if
13605 * an error occurred.
13610 * g_data_input_stream_read_int32:
13611 * @stream: a given #GDataInputStream.
13612 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
13613 * @error: #GError for error reporting.
13615 * Reads a signed 32-bit/4-byte value from @stream.
13617 * In order to get the correct byte order for this read operation,
13618 * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().
13620 * If @cancellable is not %NULL, then the operation can be cancelled by
13621 * triggering the cancellable object from another thread. If the operation
13622 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
13624 * Returns: a signed 32-bit/4-byte value read from the @stream or %0 if
13625 * an error occurred.
13630 * g_data_input_stream_read_int64:
13631 * @stream: a given #GDataInputStream.
13632 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
13633 * @error: #GError for error reporting.
13635 * Reads a 64-bit/8-byte value from @stream.
13637 * In order to get the correct byte order for this read operation,
13638 * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().
13640 * If @cancellable is not %NULL, then the operation can be cancelled by
13641 * triggering the cancellable object from another thread. If the operation
13642 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
13644 * Returns: a signed 64-bit/8-byte value read from @stream or %0 if
13645 * an error occurred.
13650 * g_data_input_stream_read_line:
13651 * @stream: a given #GDataInputStream.
13652 * @length: (out): a #gsize to get the length of the data read in.
13653 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
13654 * @error: #GError for error reporting.
13656 * Reads a line from the data input stream. Note that no encoding
13657 * checks or conversion is performed; the input is not guaranteed to
13658 * be UTF-8, and may in fact have embedded NUL characters.
13660 * If @cancellable is not %NULL, then the operation can be cancelled by
13661 * triggering the cancellable object from another thread. If the operation
13662 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
13664 * Returns: (nullable) (transfer full) (array zero-terminated=1) (element-type guint8):
13665 * a NUL terminated byte array with the line that was read in
13666 * (without the newlines). Set @length to a #gsize to get the length
13667 * of the read line. On an error, it will return %NULL and @error
13668 * will be set. If there's no content to read, it will still return
13669 * %NULL, but @error won't be set.
13674 * g_data_input_stream_read_line_async:
13675 * @stream: a given #GDataInputStream.
13676 * @io_priority: the [I/O priority][io-priority] of the request
13677 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
13678 * @callback: (scope async): callback to call when the request is satisfied.
13679 * @user_data: (closure): the data to pass to callback function.
13681 * The asynchronous version of g_data_input_stream_read_line(). It is
13682 * an error to have two outstanding calls to this function.
13684 * When the operation is finished, @callback will be called. You
13685 * can then call g_data_input_stream_read_line_finish() to get
13686 * the result of the operation.
13693 * g_data_input_stream_read_line_finish:
13694 * @stream: a given #GDataInputStream.
13695 * @result: the #GAsyncResult that was provided to the callback.
13696 * @length: (out): a #gsize to get the length of the data read in.
13697 * @error: #GError for error reporting.
13699 * Finish an asynchronous call started by
13700 * g_data_input_stream_read_line_async(). Note the warning about
13701 * string encoding in g_data_input_stream_read_line() applies here as
13704 * Returns: (nullable) (transfer full) (array zero-terminated=1) (element-type guint8):
13705 * a NUL-terminated byte array with the line that was read in
13706 * (without the newlines). Set @length to a #gsize to get the length
13707 * of the read line. On an error, it will return %NULL and @error
13708 * will be set. If there's no content to read, it will still return
13709 * %NULL, but @error won't be set.
13715 * g_data_input_stream_read_line_finish_utf8:
13716 * @stream: a given #GDataInputStream.
13717 * @result: the #GAsyncResult that was provided to the callback.
13718 * @length: (out): a #gsize to get the length of the data read in.
13719 * @error: #GError for error reporting.
13721 * Finish an asynchronous call started by
13722 * g_data_input_stream_read_line_async().
13724 * Returns: (nullable) (transfer full): a string with the line that
13725 * was read in (without the newlines). Set @length to a #gsize to
13726 * get the length of the read line. On an error, it will return
13727 * %NULL and @error will be set. For UTF-8 conversion errors, the set
13728 * error domain is %G_CONVERT_ERROR. If there's no content to read,
13729 * it will still return %NULL, but @error won't be set.
13735 * g_data_input_stream_read_line_utf8:
13736 * @stream: a given #GDataInputStream.
13737 * @length: (out): a #gsize to get the length of the data read in.
13738 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
13739 * @error: #GError for error reporting.
13741 * Reads a UTF-8 encoded line from the data input stream.
13743 * If @cancellable is not %NULL, then the operation can be cancelled by
13744 * triggering the cancellable object from another thread. If the operation
13745 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
13747 * Returns: (nullable) (transfer full): a NUL terminated UTF-8 string
13748 * with the line that was read in (without the newlines). Set
13749 * @length to a #gsize to get the length of the read line. On an
13750 * error, it will return %NULL and @error will be set. For UTF-8
13751 * conversion errors, the set error domain is %G_CONVERT_ERROR. If
13752 * there's no content to read, it will still return %NULL, but @error
13759 * g_data_input_stream_read_uint16:
13760 * @stream: a given #GDataInputStream.
13761 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
13762 * @error: #GError for error reporting.
13764 * Reads an unsigned 16-bit/2-byte value from @stream.
13766 * In order to get the correct byte order for this read operation,
13767 * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().
13769 * Returns: an unsigned 16-bit/2-byte value read from the @stream or %0 if
13770 * an error occurred.
13775 * g_data_input_stream_read_uint32:
13776 * @stream: a given #GDataInputStream.
13777 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
13778 * @error: #GError for error reporting.
13780 * Reads an unsigned 32-bit/4-byte value from @stream.
13782 * In order to get the correct byte order for this read operation,
13783 * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().
13785 * If @cancellable is not %NULL, then the operation can be cancelled by
13786 * triggering the cancellable object from another thread. If the operation
13787 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
13789 * Returns: an unsigned 32-bit/4-byte value read from the @stream or %0 if
13790 * an error occurred.
13795 * g_data_input_stream_read_uint64:
13796 * @stream: a given #GDataInputStream.
13797 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
13798 * @error: #GError for error reporting.
13800 * Reads an unsigned 64-bit/8-byte value from @stream.
13802 * In order to get the correct byte order for this read operation,
13803 * see g_data_input_stream_get_byte_order().
13805 * If @cancellable is not %NULL, then the operation can be cancelled by
13806 * triggering the cancellable object from another thread. If the operation
13807 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
13809 * Returns: an unsigned 64-bit/8-byte read from @stream or %0 if
13810 * an error occurred.
13815 * g_data_input_stream_read_until:
13816 * @stream: a given #GDataInputStream.
13817 * @stop_chars: characters to terminate the read.
13818 * @length: (out): a #gsize to get the length of the data read in.
13819 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
13820 * @error: #GError for error reporting.
13822 * Reads a string from the data input stream, up to the first
13823 * occurrence of any of the stop characters.
13825 * Note that, in contrast to g_data_input_stream_read_until_async(),
13826 * this function consumes the stop character that it finds.
13828 * Don't use this function in new code. Its functionality is
13829 * inconsistent with g_data_input_stream_read_until_async(). Both
13830 * functions will be marked as deprecated in a future release. Use
13831 * g_data_input_stream_read_upto() instead, but note that that function
13832 * does not consume the stop character.
13834 * Returns: (transfer full): a string with the data that was read
13835 * before encountering any of the stop characters. Set @length to
13836 * a #gsize to get the length of the string. This function will
13837 * return %NULL on an error.
13842 * g_data_input_stream_read_until_async:
13843 * @stream: a given #GDataInputStream.
13844 * @stop_chars: characters to terminate the read.
13845 * @io_priority: the [I/O priority][io-priority] of the request
13846 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
13847 * @callback: (scope async): callback to call when the request is satisfied.
13848 * @user_data: (closure): the data to pass to callback function.
13850 * The asynchronous version of g_data_input_stream_read_until().
13851 * It is an error to have two outstanding calls to this function.
13853 * Note that, in contrast to g_data_input_stream_read_until(),
13854 * this function does not consume the stop character that it finds. You
13855 * must read it for yourself.
13857 * When the operation is finished, @callback will be called. You
13858 * can then call g_data_input_stream_read_until_finish() to get
13859 * the result of the operation.
13861 * Don't use this function in new code. Its functionality is
13862 * inconsistent with g_data_input_stream_read_until(). Both functions
13863 * will be marked as deprecated in a future release. Use
13864 * g_data_input_stream_read_upto_async() instead.
13871 * g_data_input_stream_read_until_finish:
13872 * @stream: a given #GDataInputStream.
13873 * @result: the #GAsyncResult that was provided to the callback.
13874 * @length: (out): a #gsize to get the length of the data read in.
13875 * @error: #GError for error reporting.
13877 * Finish an asynchronous call started by
13878 * g_data_input_stream_read_until_async().
13881 * Returns: (transfer full): a string with the data that was read
13882 * before encountering any of the stop characters. Set @length to
13883 * a #gsize to get the length of the string. This function will
13884 * return %NULL on an error.
13889 * g_data_input_stream_read_upto:
13890 * @stream: a #GDataInputStream
13891 * @stop_chars: characters to terminate the read
13892 * @stop_chars_len: length of @stop_chars. May be -1 if @stop_chars is
13894 * @length: (out): a #gsize to get the length of the data read in
13895 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
13896 * @error: #GError for error reporting
13898 * Reads a string from the data input stream, up to the first
13899 * occurrence of any of the stop characters.
13901 * In contrast to g_data_input_stream_read_until(), this function
13902 * does not consume the stop character. You have to use
13903 * g_data_input_stream_read_byte() to get it before calling
13904 * g_data_input_stream_read_upto() again.
13906 * Note that @stop_chars may contain '\0' if @stop_chars_len is
13909 * Returns: (transfer full): a string with the data that was read
13910 * before encountering any of the stop characters. Set @length to
13911 * a #gsize to get the length of the string. This function will
13912 * return %NULL on an error
13918 * g_data_input_stream_read_upto_async:
13919 * @stream: a #GDataInputStream
13920 * @stop_chars: characters to terminate the read
13921 * @stop_chars_len: length of @stop_chars. May be -1 if @stop_chars is
13923 * @io_priority: the [I/O priority][io-priority] of the request
13924 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
13925 * @callback: (scope async): callback to call when the request is satisfied
13926 * @user_data: (closure): the data to pass to callback function
13928 * The asynchronous version of g_data_input_stream_read_upto().
13929 * It is an error to have two outstanding calls to this function.
13931 * In contrast to g_data_input_stream_read_until(), this function
13932 * does not consume the stop character. You have to use
13933 * g_data_input_stream_read_byte() to get it before calling
13934 * g_data_input_stream_read_upto() again.
13936 * Note that @stop_chars may contain '\0' if @stop_chars_len is
13939 * When the operation is finished, @callback will be called. You
13940 * can then call g_data_input_stream_read_upto_finish() to get
13941 * the result of the operation.
13948 * g_data_input_stream_read_upto_finish:
13949 * @stream: a #GDataInputStream
13950 * @result: the #GAsyncResult that was provided to the callback
13951 * @length: (out): a #gsize to get the length of the data read in
13952 * @error: #GError for error reporting
13954 * Finish an asynchronous call started by
13955 * g_data_input_stream_read_upto_async().
13957 * Note that this function does not consume the stop character. You
13958 * have to use g_data_input_stream_read_byte() to get it before calling
13959 * g_data_input_stream_read_upto_async() again.
13961 * Returns: (transfer full): a string with the data that was read
13962 * before encountering any of the stop characters. Set @length to
13963 * a #gsize to get the length of the string. This function will
13964 * return %NULL on an error.
13970 * g_data_input_stream_set_byte_order:
13971 * @stream: a given #GDataInputStream.
13972 * @order: a #GDataStreamByteOrder to set.
13974 * This function sets the byte order for the given @stream. All subsequent
13975 * reads from the @stream will be read in the given @order.
13980 * g_data_input_stream_set_newline_type:
13981 * @stream: a #GDataInputStream.
13982 * @type: the type of new line return as #GDataStreamNewlineType.
13984 * Sets the newline type for the @stream.
13986 * Note that using G_DATA_STREAM_NEWLINE_TYPE_ANY is slightly unsafe. If a read
13987 * chunk ends in "CR" we must read an additional byte to know if this is "CR" or
13988 * "CR LF", and this might block if there is no more data available.
13993 * g_data_output_stream_get_byte_order:
13994 * @stream: a #GDataOutputStream.
13996 * Gets the byte order for the stream.
13998 * Returns: the #GDataStreamByteOrder for the @stream.
14003 * g_data_output_stream_new:
14004 * @base_stream: a #GOutputStream.
14006 * Creates a new data output stream for @base_stream.
14008 * Returns: #GDataOutputStream.
14013 * g_data_output_stream_put_byte:
14014 * @stream: a #GDataOutputStream.
14015 * @data: a #guchar.
14016 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
14017 * @error: a #GError, %NULL to ignore.
14019 * Puts a byte into the output stream.
14021 * Returns: %TRUE if @data was successfully added to the @stream.
14026 * g_data_output_stream_put_int16:
14027 * @stream: a #GDataOutputStream.
14028 * @data: a #gint16.
14029 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
14030 * @error: a #GError, %NULL to ignore.
14032 * Puts a signed 16-bit integer into the output stream.
14034 * Returns: %TRUE if @data was successfully added to the @stream.
14039 * g_data_output_stream_put_int32:
14040 * @stream: a #GDataOutputStream.
14041 * @data: a #gint32.
14042 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
14043 * @error: a #GError, %NULL to ignore.
14045 * Puts a signed 32-bit integer into the output stream.
14047 * Returns: %TRUE if @data was successfully added to the @stream.
14052 * g_data_output_stream_put_int64:
14053 * @stream: a #GDataOutputStream.
14054 * @data: a #gint64.
14055 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
14056 * @error: a #GError, %NULL to ignore.
14058 * Puts a signed 64-bit integer into the stream.
14060 * Returns: %TRUE if @data was successfully added to the @stream.
14065 * g_data_output_stream_put_string:
14066 * @stream: a #GDataOutputStream.
14068 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
14069 * @error: a #GError, %NULL to ignore.
14071 * Puts a string into the output stream.
14073 * Returns: %TRUE if @string was successfully added to the @stream.
14078 * g_data_output_stream_put_uint16:
14079 * @stream: a #GDataOutputStream.
14080 * @data: a #guint16.
14081 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
14082 * @error: a #GError, %NULL to ignore.
14084 * Puts an unsigned 16-bit integer into the output stream.
14086 * Returns: %TRUE if @data was successfully added to the @stream.
14091 * g_data_output_stream_put_uint32:
14092 * @stream: a #GDataOutputStream.
14093 * @data: a #guint32.
14094 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
14095 * @error: a #GError, %NULL to ignore.
14097 * Puts an unsigned 32-bit integer into the stream.
14099 * Returns: %TRUE if @data was successfully added to the @stream.
14104 * g_data_output_stream_put_uint64:
14105 * @stream: a #GDataOutputStream.
14106 * @data: a #guint64.
14107 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
14108 * @error: a #GError, %NULL to ignore.
14110 * Puts an unsigned 64-bit integer into the stream.
14112 * Returns: %TRUE if @data was successfully added to the @stream.
14117 * g_data_output_stream_set_byte_order:
14118 * @stream: a #GDataOutputStream.
14119 * @order: a %GDataStreamByteOrder.
14121 * Sets the byte order of the data output stream to @order.
14126 * g_dbus_action_group_get:
14127 * @connection: A #GDBusConnection
14128 * @bus_name: the bus name which exports the action group
14129 * @object_path: the object path at which the action group is exported
14131 * Obtains a #GDBusActionGroup for the action group which is exported at
14132 * the given @bus_name and @object_path.
14134 * The thread default main context is taken at the time of this call.
14135 * All signals on the menu model (and any linked models) are reported
14136 * with respect to this context. All calls on the returned menu model
14137 * (and linked models) must also originate from this same context, with
14138 * the thread default main context unchanged.
14140 * This call is non-blocking. The returned action group may or may not
14141 * already be filled in. The correct thing to do is connect the signals
14142 * for the action group to monitor for changes and then to call
14143 * g_action_group_list_actions() to get the initial list.
14145 * Returns: (transfer full): a #GDBusActionGroup
14151 * g_dbus_address_escape_value:
14152 * @string: an unescaped string to be included in a D-Bus address
14153 * as the value in a key-value pair
14155 * Escape @string so it can appear in a D-Bus address as the value
14156 * part of a key-value pair.
14158 * For instance, if @string is "/run/bus-for-:0",
14159 * this function would return "/run/bus-for-%3A0",
14160 * which could be used in a D-Bus address like
14161 * "unix:nonce-tcp:host=127.0.0.1,port=42,noncefile=/run/bus-for-%3A0".
14163 * Returns: (transfer full): a copy of @string with all
14164 * non-optionally-escaped bytes escaped
14170 * g_dbus_address_get_for_bus_sync:
14171 * @bus_type: a #GBusType
14172 * @cancellable: (allow-none): a #GCancellable or %NULL
14173 * @error: return location for error or %NULL
14175 * Synchronously looks up the D-Bus address for the well-known message
14176 * bus instance specified by @bus_type. This may involve using various
14177 * platform specific mechanisms.
14179 * Returns: a valid D-Bus address string for @bus_type or %NULL if
14186 * g_dbus_address_get_stream:
14187 * @address: A valid D-Bus address.
14188 * @cancellable: (allow-none): A #GCancellable or %NULL.
14189 * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
14190 * @user_data: Data to pass to @callback.
14192 * Asynchronously connects to an endpoint specified by @address and
14193 * sets up the connection so it is in a state to run the client-side
14194 * of the D-Bus authentication conversation.
14196 * When the operation is finished, @callback will be invoked. You can
14197 * then call g_dbus_address_get_stream_finish() to get the result of
14200 * This is an asynchronous failable function. See
14201 * g_dbus_address_get_stream_sync() for the synchronous version.
14208 * g_dbus_address_get_stream_finish:
14209 * @res: A #GAsyncResult obtained from the GAsyncReadyCallback passed to g_dbus_address_get_stream().
14210 * @out_guid: %NULL or return location to store the GUID extracted from @address, if any.
14211 * @error: Return location for error or %NULL.
14213 * Finishes an operation started with g_dbus_address_get_stream().
14215 * Returns: (transfer full): A #GIOStream or %NULL if @error is set.
14221 * g_dbus_address_get_stream_sync:
14222 * @address: A valid D-Bus address.
14223 * @out_guid: %NULL or return location to store the GUID extracted from @address, if any.
14224 * @cancellable: (allow-none): A #GCancellable or %NULL.
14225 * @error: Return location for error or %NULL.
14227 * Synchronously connects to an endpoint specified by @address and
14228 * sets up the connection so it is in a state to run the client-side
14229 * of the D-Bus authentication conversation.
14231 * This is a synchronous failable function. See
14232 * g_dbus_address_get_stream() for the asynchronous version.
14234 * Returns: (transfer full): A #GIOStream or %NULL if @error is set.
14240 * g_dbus_annotation_info_lookup:
14241 * @annotations: (array zero-terminated=1) (allow-none): A %NULL-terminated array of annotations or %NULL.
14242 * @name: The name of the annotation to look up.
14244 * Looks up the value of an annotation.
14246 * The cost of this function is O(n) in number of annotations.
14248 * Returns: The value or %NULL if not found. Do not free, it is owned by @annotations.
14254 * g_dbus_annotation_info_ref:
14255 * @info: A #GDBusNodeInfo
14257 * If @info is statically allocated does nothing. Otherwise increases
14258 * the reference count.
14260 * Returns: The same @info.
14266 * g_dbus_annotation_info_unref:
14267 * @info: A #GDBusAnnotationInfo.
14269 * If @info is statically allocated, does nothing. Otherwise decreases
14270 * the reference count of @info. When its reference count drops to 0,
14271 * the memory used is freed.
14278 * g_dbus_arg_info_ref:
14279 * @info: A #GDBusArgInfo
14281 * If @info is statically allocated does nothing. Otherwise increases
14282 * the reference count.
14284 * Returns: The same @info.
14290 * g_dbus_arg_info_unref:
14291 * @info: A #GDBusArgInfo.
14293 * If @info is statically allocated, does nothing. Otherwise decreases
14294 * the reference count of @info. When its reference count drops to 0,
14295 * the memory used is freed.
14302 * g_dbus_auth_observer_allow_mechanism:
14303 * @observer: A #GDBusAuthObserver.
14304 * @mechanism: The name of the mechanism, e.g. `DBUS_COOKIE_SHA1`.
14306 * Emits the #GDBusAuthObserver::allow-mechanism signal on @observer.
14308 * Returns: %TRUE if @mechanism can be used to authenticate the other peer, %FALSE if not.
14314 * g_dbus_auth_observer_authorize_authenticated_peer:
14315 * @observer: A #GDBusAuthObserver.
14316 * @stream: A #GIOStream for the #GDBusConnection.
14317 * @credentials: (allow-none): Credentials received from the peer or %NULL.
14319 * Emits the #GDBusAuthObserver::authorize-authenticated-peer signal on @observer.
14321 * Returns: %TRUE if the peer is authorized, %FALSE if not.
14327 * g_dbus_auth_observer_new:
14329 * Creates a new #GDBusAuthObserver object.
14331 * Returns: A #GDBusAuthObserver. Free with g_object_unref().
14337 * g_dbus_connection_add_filter:
14338 * @connection: a #GDBusConnection
14339 * @filter_function: a filter function
14340 * @user_data: user data to pass to @filter_function
14341 * @user_data_free_func: function to free @user_data with when filter
14342 * is removed or %NULL
14344 * Adds a message filter. Filters are handlers that are run on all
14345 * incoming and outgoing messages, prior to standard dispatch. Filters
14346 * are run in the order that they were added. The same handler can be
14347 * added as a filter more than once, in which case it will be run more
14348 * than once. Filters added during a filter callback won't be run on
14349 * the message being processed. Filter functions are allowed to modify
14350 * and even drop messages.
14352 * Note that filters are run in a dedicated message handling thread so
14353 * they can't block and, generally, can't do anything but signal a
14354 * worker thread. Also note that filters are rarely needed - use API
14355 * such as g_dbus_connection_send_message_with_reply(),
14356 * g_dbus_connection_signal_subscribe() or g_dbus_connection_call() instead.
14358 * If a filter consumes an incoming message the message is not
14359 * dispatched anywhere else - not even the standard dispatch machinery
14360 * (that API such as g_dbus_connection_signal_subscribe() and
14361 * g_dbus_connection_send_message_with_reply() relies on) will see the
14362 * message. Similary, if a filter consumes an outgoing message, the
14363 * message will not be sent to the other peer.
14365 * Returns: a filter identifier that can be used with
14366 * g_dbus_connection_remove_filter()
14372 * g_dbus_connection_call:
14373 * @connection: a #GDBusConnection
14374 * @bus_name: (allow-none): a unique or well-known bus name or %NULL if
14375 * @connection is not a message bus connection
14376 * @object_path: path of remote object
14377 * @interface_name: D-Bus interface to invoke method on
14378 * @method_name: the name of the method to invoke
14379 * @parameters: (allow-none): a #GVariant tuple with parameters for the method
14380 * or %NULL if not passing parameters
14381 * @reply_type: (allow-none): the expected type of the reply, or %NULL
14382 * @flags: flags from the #GDBusCallFlags enumeration
14383 * @timeout_msec: the timeout in milliseconds, -1 to use the default
14384 * timeout or %G_MAXINT for no timeout
14385 * @cancellable: (allow-none): a #GCancellable or %NULL
14386 * @callback: (allow-none): a #GAsyncReadyCallback to call when the request
14387 * is satisfied or %NULL if you don't care about the result of the
14388 * method invocation
14389 * @user_data: the data to pass to @callback
14391 * Asynchronously invokes the @method_name method on the
14392 * @interface_name D-Bus interface on the remote object at
14393 * @object_path owned by @bus_name.
14395 * If @connection is closed then the operation will fail with
14396 * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will
14397 * fail with %G_IO_ERROR_CANCELLED. If @parameters contains a value
14398 * not compatible with the D-Bus protocol, the operation fails with
14399 * %G_IO_ERROR_INVALID_ARGUMENT.
14401 * If @reply_type is non-%NULL then the reply will be checked for having this type and an
14402 * error will be raised if it does not match. Said another way, if you give a @reply_type
14403 * then any non-%NULL return value will be of this type.
14405 * If the @parameters #GVariant is floating, it is consumed. This allows
14406 * convenient 'inline' use of g_variant_new(), e.g.:
14407 * |[<!-- language="C" -->
14408 * g_dbus_connection_call (connection,
14409 * "org.freedesktop.StringThings",
14410 * "/org/freedesktop/StringThings",
14411 * "org.freedesktop.StringThings",
14413 * g_variant_new ("(ss)",
14417 * G_DBUS_CALL_FLAGS_NONE,
14420 * (GAsyncReadyCallback) two_strings_done,
14424 * This is an asynchronous method. When the operation is finished,
14425 * @callback will be invoked in the
14426 * [thread-default main context][g-main-context-push-thread-default]
14427 * of the thread you are calling this method from. You can then call
14428 * g_dbus_connection_call_finish() to get the result of the operation.
14429 * See g_dbus_connection_call_sync() for the synchronous version of this
14432 * If @callback is %NULL then the D-Bus method call message will be sent with
14433 * the %G_DBUS_MESSAGE_FLAGS_NO_REPLY_EXPECTED flag set.
14440 * g_dbus_connection_call_finish:
14441 * @connection: a #GDBusConnection
14442 * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_call()
14443 * @error: return location for error or %NULL
14445 * Finishes an operation started with g_dbus_connection_call().
14447 * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
14448 * return values. Free with g_variant_unref().
14454 * g_dbus_connection_call_sync:
14455 * @connection: a #GDBusConnection
14456 * @bus_name: (allow-none): a unique or well-known bus name or %NULL if
14457 * @connection is not a message bus connection
14458 * @object_path: path of remote object
14459 * @interface_name: D-Bus interface to invoke method on
14460 * @method_name: the name of the method to invoke
14461 * @parameters: (allow-none): a #GVariant tuple with parameters for the method
14462 * or %NULL if not passing parameters
14463 * @reply_type: (allow-none): the expected type of the reply, or %NULL
14464 * @flags: flags from the #GDBusCallFlags enumeration
14465 * @timeout_msec: the timeout in milliseconds, -1 to use the default
14466 * timeout or %G_MAXINT for no timeout
14467 * @cancellable: (allow-none): a #GCancellable or %NULL
14468 * @error: return location for error or %NULL
14470 * Synchronously invokes the @method_name method on the
14471 * @interface_name D-Bus interface on the remote object at
14472 * @object_path owned by @bus_name.
14474 * If @connection is closed then the operation will fail with
14475 * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the
14476 * operation will fail with %G_IO_ERROR_CANCELLED. If @parameters
14477 * contains a value not compatible with the D-Bus protocol, the operation
14478 * fails with %G_IO_ERROR_INVALID_ARGUMENT.
14480 * If @reply_type is non-%NULL then the reply will be checked for having
14481 * this type and an error will be raised if it does not match. Said
14482 * another way, if you give a @reply_type then any non-%NULL return
14483 * value will be of this type.
14485 * If the @parameters #GVariant is floating, it is consumed.
14486 * This allows convenient 'inline' use of g_variant_new(), e.g.:
14487 * |[<!-- language="C" -->
14488 * g_dbus_connection_call_sync (connection,
14489 * "org.freedesktop.StringThings",
14490 * "/org/freedesktop/StringThings",
14491 * "org.freedesktop.StringThings",
14493 * g_variant_new ("(ss)",
14497 * G_DBUS_CALL_FLAGS_NONE,
14503 * The calling thread is blocked until a reply is received. See
14504 * g_dbus_connection_call() for the asynchronous version of
14507 * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
14508 * return values. Free with g_variant_unref().
14514 * g_dbus_connection_call_with_unix_fd_list:
14515 * @connection: a #GDBusConnection
14516 * @bus_name: (allow-none): a unique or well-known bus name or %NULL if
14517 * @connection is not a message bus connection
14518 * @object_path: path of remote object
14519 * @interface_name: D-Bus interface to invoke method on
14520 * @method_name: the name of the method to invoke
14521 * @parameters: (allow-none): a #GVariant tuple with parameters for the method
14522 * or %NULL if not passing parameters
14523 * @reply_type: (allow-none): the expected type of the reply, or %NULL
14524 * @flags: flags from the #GDBusCallFlags enumeration
14525 * @timeout_msec: the timeout in milliseconds, -1 to use the default
14526 * timeout or %G_MAXINT for no timeout
14527 * @fd_list: (allow-none): a #GUnixFDList or %NULL
14528 * @cancellable: (allow-none): a #GCancellable or %NULL
14529 * @callback: (allow-none): a #GAsyncReadyCallback to call when the request is
14530 * satisfied or %NULL if you don't * care about the result of the
14531 * method invocation
14532 * @user_data: The data to pass to @callback.
14534 * Like g_dbus_connection_call() but also takes a #GUnixFDList object.
14536 * This method is only available on UNIX.
14543 * g_dbus_connection_call_with_unix_fd_list_finish:
14544 * @connection: a #GDBusConnection
14545 * @out_fd_list: (out) (allow-none): return location for a #GUnixFDList or %NULL
14546 * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed to
14547 * g_dbus_connection_call_with_unix_fd_list()
14548 * @error: return location for error or %NULL
14550 * Finishes an operation started with g_dbus_connection_call_with_unix_fd_list().
14552 * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
14553 * return values. Free with g_variant_unref().
14559 * g_dbus_connection_call_with_unix_fd_list_sync:
14560 * @connection: a #GDBusConnection
14561 * @bus_name: (allow-none): a unique or well-known bus name or %NULL
14562 * if @connection is not a message bus connection
14563 * @object_path: path of remote object
14564 * @interface_name: D-Bus interface to invoke method on
14565 * @method_name: the name of the method to invoke
14566 * @parameters: (allow-none): a #GVariant tuple with parameters for
14567 * the method or %NULL if not passing parameters
14568 * @reply_type: (allow-none): the expected type of the reply, or %NULL
14569 * @flags: flags from the #GDBusCallFlags enumeration
14570 * @timeout_msec: the timeout in milliseconds, -1 to use the default
14571 * timeout or %G_MAXINT for no timeout
14572 * @fd_list: (allow-none): a #GUnixFDList or %NULL
14573 * @out_fd_list: (out) (allow-none): return location for a #GUnixFDList or %NULL
14574 * @cancellable: (allow-none): a #GCancellable or %NULL
14575 * @error: return location for error or %NULL
14577 * Like g_dbus_connection_call_sync() but also takes and returns #GUnixFDList objects.
14579 * This method is only available on UNIX.
14581 * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
14582 * return values. Free with g_variant_unref().
14588 * g_dbus_connection_close:
14589 * @connection: a #GDBusConnection
14590 * @cancellable: (allow-none): a #GCancellable or %NULL
14591 * @callback: (allow-none): a #GAsyncReadyCallback to call when the request is
14592 * satisfied or %NULL if you don't care about the result
14593 * @user_data: The data to pass to @callback
14595 * Closes @connection. Note that this never causes the process to
14596 * exit (this might only happen if the other end of a shared message
14597 * bus connection disconnects, see #GDBusConnection:exit-on-close).
14599 * Once the connection is closed, operations such as sending a message
14600 * will return with the error %G_IO_ERROR_CLOSED. Closing a connection
14601 * will not automatically flush the connection so queued messages may
14602 * be lost. Use g_dbus_connection_flush() if you need such guarantees.
14604 * If @connection is already closed, this method fails with
14605 * %G_IO_ERROR_CLOSED.
14607 * When @connection has been closed, the #GDBusConnection::closed
14608 * signal is emitted in the
14609 * [thread-default main context][g-main-context-push-thread-default]
14610 * of the thread that @connection was constructed in.
14612 * This is an asynchronous method. When the operation is finished,
14613 * @callback will be invoked in the
14614 * [thread-default main context][g-main-context-push-thread-default]
14615 * of the thread you are calling this method from. You can
14616 * then call g_dbus_connection_close_finish() to get the result of the
14617 * operation. See g_dbus_connection_close_sync() for the synchronous
14625 * g_dbus_connection_close_finish:
14626 * @connection: a #GDBusConnection
14627 * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed
14628 * to g_dbus_connection_close()
14629 * @error: return location for error or %NULL
14631 * Finishes an operation started with g_dbus_connection_close().
14633 * Returns: %TRUE if the operation succeeded, %FALSE if @error is set
14639 * g_dbus_connection_close_sync:
14640 * @connection: a #GDBusConnection
14641 * @cancellable: (allow-none): a #GCancellable or %NULL
14642 * @error: return location for error or %NULL
14644 * Synchronously closees @connection. The calling thread is blocked
14645 * until this is done. See g_dbus_connection_close() for the
14646 * asynchronous version of this method and more details about what it
14649 * Returns: %TRUE if the operation succeeded, %FALSE if @error is set
14655 * g_dbus_connection_emit_signal:
14656 * @connection: a #GDBusConnection
14657 * @destination_bus_name: (allow-none): the unique bus name for the destination
14658 * for the signal or %NULL to emit to all listeners
14659 * @object_path: path of remote object
14660 * @interface_name: D-Bus interface to emit a signal on
14661 * @signal_name: the name of the signal to emit
14662 * @parameters: (allow-none): a #GVariant tuple with parameters for the signal
14663 * or %NULL if not passing parameters
14664 * @error: Return location for error or %NULL
14668 * If the parameters GVariant is floating, it is consumed.
14670 * This can only fail if @parameters is not compatible with the D-Bus protocol.
14672 * Returns: %TRUE unless @error is set
14678 * g_dbus_connection_export_action_group:
14679 * @connection: a #GDBusConnection
14680 * @object_path: a D-Bus object path
14681 * @action_group: a #GActionGroup
14682 * @error: a pointer to a %NULL #GError, or %NULL
14684 * Exports @action_group on @connection at @object_path.
14686 * The implemented D-Bus API should be considered private. It is
14687 * subject to change in the future.
14689 * A given object path can only have one action group exported on it.
14690 * If this constraint is violated, the export will fail and 0 will be
14691 * returned (with @error set accordingly).
14693 * You can unexport the action group using
14694 * g_dbus_connection_unexport_action_group() with the return value of
14697 * The thread default main context is taken at the time of this call.
14698 * All incoming action activations and state change requests are
14699 * reported from this context. Any changes on the action group that
14700 * cause it to emit signals must also come from this same context.
14701 * Since incoming action activations and state change requests are
14702 * rather likely to cause changes on the action group, this effectively
14703 * limits a given action group to being exported from only one main
14706 * Returns: the ID of the export (never zero), or 0 in case of failure
14712 * g_dbus_connection_export_menu_model:
14713 * @connection: a #GDBusConnection
14714 * @object_path: a D-Bus object path
14715 * @menu: a #GMenuModel
14716 * @error: return location for an error, or %NULL
14718 * Exports @menu on @connection at @object_path.
14720 * The implemented D-Bus API should be considered private.
14721 * It is subject to change in the future.
14723 * An object path can only have one menu model exported on it. If this
14724 * constraint is violated, the export will fail and 0 will be
14725 * returned (with @error set accordingly).
14727 * You can unexport the menu model using
14728 * g_dbus_connection_unexport_menu_model() with the return value of
14731 * Returns: the ID of the export (never zero), or 0 in case of failure
14737 * g_dbus_connection_flush:
14738 * @connection: a #GDBusConnection
14739 * @cancellable: (allow-none): a #GCancellable or %NULL
14740 * @callback: (allow-none): a #GAsyncReadyCallback to call when the
14741 * request is satisfied or %NULL if you don't care about the result
14742 * @user_data: The data to pass to @callback
14744 * Asynchronously flushes @connection, that is, writes all queued
14745 * outgoing message to the transport and then flushes the transport
14746 * (using g_output_stream_flush_async()). This is useful in programs
14747 * that wants to emit a D-Bus signal and then exit immediately. Without
14748 * flushing the connection, there is no guaranteed that the message has
14749 * been sent to the networking buffers in the OS kernel.
14751 * This is an asynchronous method. When the operation is finished,
14752 * @callback will be invoked in the
14753 * [thread-default main context][g-main-context-push-thread-default]
14754 * of the thread you are calling this method from. You can
14755 * then call g_dbus_connection_flush_finish() to get the result of the
14756 * operation. See g_dbus_connection_flush_sync() for the synchronous
14764 * g_dbus_connection_flush_finish:
14765 * @connection: a #GDBusConnection
14766 * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed
14767 * to g_dbus_connection_flush()
14768 * @error: return location for error or %NULL
14770 * Finishes an operation started with g_dbus_connection_flush().
14772 * Returns: %TRUE if the operation succeeded, %FALSE if @error is set
14778 * g_dbus_connection_flush_sync:
14779 * @connection: a #GDBusConnection
14780 * @cancellable: (allow-none): a #GCancellable or %NULL
14781 * @error: return location for error or %NULL
14783 * Synchronously flushes @connection. The calling thread is blocked
14784 * until this is done. See g_dbus_connection_flush() for the
14785 * asynchronous version of this method and more details about what it
14788 * Returns: %TRUE if the operation succeeded, %FALSE if @error is set
14794 * g_dbus_connection_get_capabilities:
14795 * @connection: a #GDBusConnection
14797 * Gets the capabilities negotiated with the remote peer
14799 * Returns: zero or more flags from the #GDBusCapabilityFlags enumeration
14805 * g_dbus_connection_get_exit_on_close:
14806 * @connection: a #GDBusConnection
14808 * Gets whether the process is terminated when @connection is
14809 * closed by the remote peer. See
14810 * #GDBusConnection:exit-on-close for more details.
14812 * Returns: whether the process is terminated when @connection is
14813 * closed by the remote peer
14819 * g_dbus_connection_get_guid:
14820 * @connection: a #GDBusConnection
14822 * The GUID of the peer performing the role of server when
14823 * authenticating. See #GDBusConnection:guid for more details.
14825 * Returns: The GUID. Do not free this string, it is owned by
14832 * g_dbus_connection_get_last_serial:
14833 * @connection: a #GDBusConnection
14835 * Retrieves the last serial number assigned to a #GDBusMessage on
14836 * the current thread. This includes messages sent via both low-level
14837 * API such as g_dbus_connection_send_message() as well as
14838 * high-level API such as g_dbus_connection_emit_signal(),
14839 * g_dbus_connection_call() or g_dbus_proxy_call().
14841 * Returns: the last used serial or zero when no message has been sent
14842 * within the current thread
14848 * g_dbus_connection_get_peer_credentials:
14849 * @connection: a #GDBusConnection
14851 * Gets the credentials of the authenticated peer. This will always
14852 * return %NULL unless @connection acted as a server
14853 * (e.g. %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER was passed)
14854 * when set up and the client passed credentials as part of the
14855 * authentication process.
14857 * In a message bus setup, the message bus is always the server and
14858 * each application is a client. So this method will always return
14859 * %NULL for message bus clients.
14861 * Returns: (transfer none): a #GCredentials or %NULL if not available.
14862 * Do not free this object, it is owned by @connection.
14868 * g_dbus_connection_get_stream:
14869 * @connection: a #GDBusConnection
14871 * Gets the underlying stream used for IO.
14873 * While the #GDBusConnection is active, it will interact with this
14874 * stream from a worker thread, so it is not safe to interact with
14875 * the stream directly.
14877 * Returns: (transfer none): the stream used for IO
14883 * g_dbus_connection_get_unique_name:
14884 * @connection: a #GDBusConnection
14886 * Gets the unique name of @connection as assigned by the message
14887 * bus. This can also be used to figure out if @connection is a
14888 * message bus connection.
14890 * Returns: the unique name or %NULL if @connection is not a message
14891 * bus connection. Do not free this string, it is owned by
14898 * g_dbus_connection_is_closed:
14899 * @connection: a #GDBusConnection
14901 * Gets whether @connection is closed.
14903 * Returns: %TRUE if the connection is closed, %FALSE otherwise
14909 * g_dbus_connection_new:
14910 * @stream: a #GIOStream
14911 * @guid: (allow-none): the GUID to use if a authenticating as a server or %NULL
14912 * @flags: flags describing how to make the connection
14913 * @observer: (allow-none): a #GDBusAuthObserver or %NULL
14914 * @cancellable: (allow-none): a #GCancellable or %NULL
14915 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
14916 * @user_data: the data to pass to @callback
14918 * Asynchronously sets up a D-Bus connection for exchanging D-Bus messages
14919 * with the end represented by @stream.
14921 * If @stream is a #GSocketConnection, then the corresponding #GSocket
14922 * will be put into non-blocking mode.
14924 * The D-Bus connection will interact with @stream from a worker thread.
14925 * As a result, the caller should not interact with @stream after this
14926 * method has been called, except by calling g_object_unref() on it.
14928 * If @observer is not %NULL it may be used to control the
14929 * authentication process.
14931 * When the operation is finished, @callback will be invoked. You can
14932 * then call g_dbus_connection_new_finish() to get the result of the
14935 * This is a asynchronous failable constructor. See
14936 * g_dbus_connection_new_sync() for the synchronous
14944 * g_dbus_connection_new_finish:
14945 * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback
14946 * passed to g_dbus_connection_new().
14947 * @error: return location for error or %NULL
14949 * Finishes an operation started with g_dbus_connection_new().
14951 * Returns: a #GDBusConnection or %NULL if @error is set. Free
14952 * with g_object_unref().
14958 * g_dbus_connection_new_for_address:
14959 * @address: a D-Bus address
14960 * @flags: flags describing how to make the connection
14961 * @observer: (allow-none): a #GDBusAuthObserver or %NULL
14962 * @cancellable: (allow-none): a #GCancellable or %NULL
14963 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
14964 * @user_data: the data to pass to @callback
14966 * Asynchronously connects and sets up a D-Bus client connection for
14967 * exchanging D-Bus messages with an endpoint specified by @address
14968 * which must be in the D-Bus address format.
14970 * This constructor can only be used to initiate client-side
14971 * connections - use g_dbus_connection_new() if you need to act as the
14972 * server. In particular, @flags cannot contain the
14973 * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER or
14974 * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS flags.
14976 * When the operation is finished, @callback will be invoked. You can
14977 * then call g_dbus_connection_new_finish() to get the result of the
14980 * If @observer is not %NULL it may be used to control the
14981 * authentication process.
14983 * This is a asynchronous failable constructor. See
14984 * g_dbus_connection_new_for_address_sync() for the synchronous
14992 * g_dbus_connection_new_for_address_finish:
14993 * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed
14994 * to g_dbus_connection_new()
14995 * @error: return location for error or %NULL
14997 * Finishes an operation started with g_dbus_connection_new_for_address().
14999 * Returns: a #GDBusConnection or %NULL if @error is set. Free with
15000 * g_object_unref().
15006 * g_dbus_connection_new_for_address_sync:
15007 * @address: a D-Bus address
15008 * @flags: flags describing how to make the connection
15009 * @observer: (allow-none): a #GDBusAuthObserver or %NULL
15010 * @cancellable: (allow-none): a #GCancellable or %NULL
15011 * @error: return location for error or %NULL
15013 * Synchronously connects and sets up a D-Bus client connection for
15014 * exchanging D-Bus messages with an endpoint specified by @address
15015 * which must be in the D-Bus address format.
15017 * This constructor can only be used to initiate client-side
15018 * connections - use g_dbus_connection_new_sync() if you need to act
15019 * as the server. In particular, @flags cannot contain the
15020 * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER or
15021 * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS flags.
15023 * This is a synchronous failable constructor. See
15024 * g_dbus_connection_new_for_address() for the asynchronous version.
15026 * If @observer is not %NULL it may be used to control the
15027 * authentication process.
15029 * Returns: a #GDBusConnection or %NULL if @error is set. Free with
15030 * g_object_unref().
15036 * g_dbus_connection_new_sync:
15037 * @stream: a #GIOStream
15038 * @guid: (allow-none): the GUID to use if a authenticating as a server or %NULL
15039 * @flags: flags describing how to make the connection
15040 * @observer: (allow-none): a #GDBusAuthObserver or %NULL
15041 * @cancellable: (allow-none): a #GCancellable or %NULL
15042 * @error: return location for error or %NULL
15044 * Synchronously sets up a D-Bus connection for exchanging D-Bus messages
15045 * with the end represented by @stream.
15047 * If @stream is a #GSocketConnection, then the corresponding #GSocket
15048 * will be put into non-blocking mode.
15050 * The D-Bus connection will interact with @stream from a worker thread.
15051 * As a result, the caller should not interact with @stream after this
15052 * method has been called, except by calling g_object_unref() on it.
15054 * If @observer is not %NULL it may be used to control the
15055 * authentication process.
15057 * This is a synchronous failable constructor. See
15058 * g_dbus_connection_new() for the asynchronous version.
15060 * Returns: a #GDBusConnection or %NULL if @error is set. Free with g_object_unref().
15066 * g_dbus_connection_register_object:
15067 * @connection: a #GDBusConnection
15068 * @object_path: the object path to register at
15069 * @interface_info: introspection data for the interface
15070 * @vtable: (allow-none): a #GDBusInterfaceVTable to call into or %NULL
15071 * @user_data: (allow-none): data to pass to functions in @vtable
15072 * @user_data_free_func: function to call when the object path is unregistered
15073 * @error: return location for error or %NULL
15075 * Registers callbacks for exported objects at @object_path with the
15076 * D-Bus interface that is described in @interface_info.
15078 * Calls to functions in @vtable (and @user_data_free_func) will happen
15080 * [thread-default main context][g-main-context-push-thread-default]
15081 * of the thread you are calling this method from.
15083 * Note that all #GVariant values passed to functions in @vtable will match
15084 * the signature given in @interface_info - if a remote caller passes
15085 * incorrect values, the `org.freedesktop.DBus.Error.InvalidArgs`
15086 * is returned to the remote caller.
15088 * Additionally, if the remote caller attempts to invoke methods or
15089 * access properties not mentioned in @interface_info the
15090 * `org.freedesktop.DBus.Error.UnknownMethod` resp.
15091 * `org.freedesktop.DBus.Error.InvalidArgs` errors
15092 * are returned to the caller.
15094 * It is considered a programming error if the
15095 * #GDBusInterfaceGetPropertyFunc function in @vtable returns a
15096 * #GVariant of incorrect type.
15098 * If an existing callback is already registered at @object_path and
15099 * @interface_name, then @error is set to #G_IO_ERROR_EXISTS.
15101 * GDBus automatically implements the standard D-Bus interfaces
15102 * org.freedesktop.DBus.Properties, org.freedesktop.DBus.Introspectable
15103 * and org.freedesktop.Peer, so you don't have to implement those for the
15104 * objects you export. You can implement org.freedesktop.DBus.Properties
15105 * yourself, e.g. to handle getting and setting of properties asynchronously.
15107 * Note that the reference count on @interface_info will be
15108 * incremented by 1 (unless allocated statically, e.g. if the
15109 * reference count is -1, see g_dbus_interface_info_ref()) for as long
15110 * as the object is exported. Also note that @vtable will be copied.
15112 * See this [server][gdbus-server] for an example of how to use this method.
15114 * Returns: 0 if @error is set, otherwise a registration id (never 0)
15115 * that can be used with g_dbus_connection_unregister_object()
15121 * g_dbus_connection_register_subtree:
15122 * @connection: a #GDBusConnection
15123 * @object_path: the object path to register the subtree at
15124 * @vtable: a #GDBusSubtreeVTable to enumerate, introspect and
15125 * dispatch nodes in the subtree
15126 * @flags: flags used to fine tune the behavior of the subtree
15127 * @user_data: data to pass to functions in @vtable
15128 * @user_data_free_func: function to call when the subtree is unregistered
15129 * @error: return location for error or %NULL
15131 * Registers a whole subtree of dynamic objects.
15133 * The @enumerate and @introspection functions in @vtable are used to
15134 * convey, to remote callers, what nodes exist in the subtree rooted
15137 * When handling remote calls into any node in the subtree, first the
15138 * @enumerate function is used to check if the node exists. If the node exists
15139 * or the #G_DBUS_SUBTREE_FLAGS_DISPATCH_TO_UNENUMERATED_NODES flag is set
15140 * the @introspection function is used to check if the node supports the
15141 * requested method. If so, the @dispatch function is used to determine
15142 * where to dispatch the call. The collected #GDBusInterfaceVTable and
15143 * #gpointer will be used to call into the interface vtable for processing
15146 * All calls into user-provided code will be invoked in the
15147 * [thread-default main context][g-main-context-push-thread-default]
15148 * of the thread you are calling this method from.
15150 * If an existing subtree is already registered at @object_path or
15151 * then @error is set to #G_IO_ERROR_EXISTS.
15153 * Note that it is valid to register regular objects (using
15154 * g_dbus_connection_register_object()) in a subtree registered with
15155 * g_dbus_connection_register_subtree() - if so, the subtree handler
15156 * is tried as the last resort. One way to think about a subtree
15157 * handler is to consider it a fallback handler for object paths not
15158 * registered via g_dbus_connection_register_object() or other bindings.
15160 * Note that @vtable will be copied so you cannot change it after
15163 * See this [server][gdbus-subtree-server] for an example of how to use
15166 * Returns: 0 if @error is set, otherwise a subtree registration id (never 0)
15167 * that can be used with g_dbus_connection_unregister_subtree() .
15173 * g_dbus_connection_remove_filter:
15174 * @connection: a #GDBusConnection
15175 * @filter_id: an identifier obtained from g_dbus_connection_add_filter()
15177 * Removes a filter.
15184 * g_dbus_connection_send_message:
15185 * @connection: a #GDBusConnection
15186 * @message: a #GDBusMessage
15187 * @flags: flags affecting how the message is sent
15188 * @out_serial: (out) (allow-none): return location for serial number assigned
15189 * to @message when sending it or %NULL
15190 * @error: Return location for error or %NULL
15192 * Asynchronously sends @message to the peer represented by @connection.
15194 * Unless @flags contain the
15195 * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number
15196 * will be assigned by @connection and set on @message via
15197 * g_dbus_message_set_serial(). If @out_serial is not %NULL, then the
15198 * serial number used will be written to this location prior to
15199 * submitting the message to the underlying transport.
15201 * If @connection is closed then the operation will fail with
15202 * %G_IO_ERROR_CLOSED. If @message is not well-formed,
15203 * the operation fails with %G_IO_ERROR_INVALID_ARGUMENT.
15205 * See this [server][gdbus-server] and [client][gdbus-unix-fd-client]
15206 * for an example of how to use this low-level API to send and receive
15207 * UNIX file descriptors.
15209 * Note that @message must be unlocked, unless @flags contain the
15210 * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag.
15212 * Returns: %TRUE if the message was well-formed and queued for
15213 * transmission, %FALSE if @error is set
15219 * g_dbus_connection_send_message_with_reply:
15220 * @connection: a #GDBusConnection
15221 * @message: a #GDBusMessage
15222 * @flags: flags affecting how the message is sent
15223 * @timeout_msec: the timeout in milliseconds, -1 to use the default
15224 * timeout or %G_MAXINT for no timeout
15225 * @out_serial: (out) (allow-none): return location for serial number assigned
15226 * to @message when sending it or %NULL
15227 * @cancellable: (allow-none): a #GCancellable or %NULL
15228 * @callback: (allow-none): a #GAsyncReadyCallback to call when the request
15229 * is satisfied or %NULL if you don't care about the result
15230 * @user_data: The data to pass to @callback
15232 * Asynchronously sends @message to the peer represented by @connection.
15234 * Unless @flags contain the
15235 * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number
15236 * will be assigned by @connection and set on @message via
15237 * g_dbus_message_set_serial(). If @out_serial is not %NULL, then the
15238 * serial number used will be written to this location prior to
15239 * submitting the message to the underlying transport.
15241 * If @connection is closed then the operation will fail with
15242 * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will
15243 * fail with %G_IO_ERROR_CANCELLED. If @message is not well-formed,
15244 * the operation fails with %G_IO_ERROR_INVALID_ARGUMENT.
15246 * This is an asynchronous method. When the operation is finished, @callback
15247 * will be invoked in the
15248 * [thread-default main context][g-main-context-push-thread-default]
15249 * of the thread you are calling this method from. You can then call
15250 * g_dbus_connection_send_message_with_reply_finish() to get the result of the operation.
15251 * See g_dbus_connection_send_message_with_reply_sync() for the synchronous version.
15253 * Note that @message must be unlocked, unless @flags contain the
15254 * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag.
15256 * See this [server][gdbus-server] and [client][gdbus-unix-fd-client]
15257 * for an example of how to use this low-level API to send and receive
15258 * UNIX file descriptors.
15265 * g_dbus_connection_send_message_with_reply_finish:
15266 * @connection: a #GDBusConnection
15267 * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed to
15268 * g_dbus_connection_send_message_with_reply()
15269 * @error: teturn location for error or %NULL
15271 * Finishes an operation started with g_dbus_connection_send_message_with_reply().
15273 * Note that @error is only set if a local in-process error
15274 * occurred. That is to say that the returned #GDBusMessage object may
15275 * be of type %G_DBUS_MESSAGE_TYPE_ERROR. Use
15276 * g_dbus_message_to_gerror() to transcode this to a #GError.
15278 * See this [server][gdbus-server] and [client][gdbus-unix-fd-client]
15279 * for an example of how to use this low-level API to send and receive
15280 * UNIX file descriptors.
15282 * Returns: (transfer full): a locked #GDBusMessage or %NULL if @error is set
15288 * g_dbus_connection_send_message_with_reply_sync:
15289 * @connection: a #GDBusConnection
15290 * @message: a #GDBusMessage
15291 * @flags: flags affecting how the message is sent.
15292 * @timeout_msec: the timeout in milliseconds, -1 to use the default
15293 * timeout or %G_MAXINT for no timeout
15294 * @out_serial: (out) (allow-none): return location for serial number
15295 * assigned to @message when sending it or %NULL
15296 * @cancellable: (allow-none): a #GCancellable or %NULL
15297 * @error: return location for error or %NULL
15299 * Synchronously sends @message to the peer represented by @connection
15300 * and blocks the calling thread until a reply is received or the
15301 * timeout is reached. See g_dbus_connection_send_message_with_reply()
15302 * for the asynchronous version of this method.
15304 * Unless @flags contain the
15305 * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number
15306 * will be assigned by @connection and set on @message via
15307 * g_dbus_message_set_serial(). If @out_serial is not %NULL, then the
15308 * serial number used will be written to this location prior to
15309 * submitting the message to the underlying transport.
15311 * If @connection is closed then the operation will fail with
15312 * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will
15313 * fail with %G_IO_ERROR_CANCELLED. If @message is not well-formed,
15314 * the operation fails with %G_IO_ERROR_INVALID_ARGUMENT.
15316 * Note that @error is only set if a local in-process error
15317 * occurred. That is to say that the returned #GDBusMessage object may
15318 * be of type %G_DBUS_MESSAGE_TYPE_ERROR. Use
15319 * g_dbus_message_to_gerror() to transcode this to a #GError.
15321 * See this [server][gdbus-server] and [client][gdbus-unix-fd-client]
15322 * for an example of how to use this low-level API to send and receive
15323 * UNIX file descriptors.
15325 * Note that @message must be unlocked, unless @flags contain the
15326 * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag.
15328 * Returns: (transfer full): a locked #GDBusMessage that is the reply
15329 * to @message or %NULL if @error is set
15335 * g_dbus_connection_set_exit_on_close:
15336 * @connection: a #GDBusConnection
15337 * @exit_on_close: whether the process should be terminated
15338 * when @connection is closed by the remote peer
15340 * Sets whether the process should be terminated when @connection is
15341 * closed by the remote peer. See #GDBusConnection:exit-on-close for
15344 * Note that this function should be used with care. Most modern UNIX
15345 * desktops tie the notion of a user session the session bus, and expect
15346 * all of a users applications to quit when their bus connection goes away.
15347 * If you are setting @exit_on_close to %FALSE for the shared session
15348 * bus connection, you should make sure that your application exits
15349 * when the user session ends.
15356 * g_dbus_connection_signal_subscribe:
15357 * @connection: a #GDBusConnection
15358 * @sender: (allow-none): sender name to match on (unique or well-known name)
15359 * or %NULL to listen from all senders
15360 * @interface_name: (allow-none): D-Bus interface name to match on or %NULL to
15361 * match on all interfaces
15362 * @member: (allow-none): D-Bus signal name to match on or %NULL to match on
15364 * @object_path: (allow-none): object path to match on or %NULL to match on
15366 * @arg0: (allow-none): contents of first string argument to match on or %NULL
15367 * to match on all kinds of arguments
15368 * @flags: flags describing how to subscribe to the signal (currently unused)
15369 * @callback: callback to invoke when there is a signal matching the requested data
15370 * @user_data: user data to pass to @callback
15371 * @user_data_free_func: (allow-none): function to free @user_data with when
15372 * subscription is removed or %NULL
15374 * Subscribes to signals on @connection and invokes @callback with a whenever
15375 * the signal is received. Note that @callback will be invoked in the
15376 * [thread-default main context][g-main-context-push-thread-default]
15377 * of the thread you are calling this method from.
15379 * If @connection is not a message bus connection, @sender must be
15382 * If @sender is a well-known name note that @callback is invoked with
15383 * the unique name for the owner of @sender, not the well-known name
15384 * as one would expect. This is because the message bus rewrites the
15385 * name. As such, to avoid certain race conditions, users should be
15386 * tracking the name owner of the well-known name and use that when
15387 * processing the received signal.
15389 * If one of %G_DBUS_SIGNAL_FLAGS_MATCH_ARG0_NAMESPACE or
15390 * %G_DBUS_SIGNAL_FLAGS_MATCH_ARG0_PATH are given, @arg0 is
15391 * interpreted as part of a namespace or path. The first argument
15392 * of a signal is matched against that part as specified by D-Bus.
15394 * Returns: a subscription identifier that can be used with g_dbus_connection_signal_unsubscribe()
15400 * g_dbus_connection_signal_unsubscribe:
15401 * @connection: a #GDBusConnection
15402 * @subscription_id: a subscription id obtained from
15403 * g_dbus_connection_signal_subscribe()
15405 * Unsubscribes from signals.
15412 * g_dbus_connection_start_message_processing:
15413 * @connection: a #GDBusConnection
15415 * If @connection was created with
15416 * %G_DBUS_CONNECTION_FLAGS_DELAY_MESSAGE_PROCESSING, this method
15417 * starts processing messages. Does nothing on if @connection wasn't
15418 * created with this flag or if the method has already been called.
15425 * g_dbus_connection_unexport_action_group:
15426 * @connection: a #GDBusConnection
15427 * @export_id: the ID from g_dbus_connection_export_action_group()
15429 * Reverses the effect of a previous call to
15430 * g_dbus_connection_export_action_group().
15432 * It is an error to call this function with an ID that wasn't returned
15433 * from g_dbus_connection_export_action_group() or to call it with the
15434 * same ID more than once.
15441 * g_dbus_connection_unexport_menu_model:
15442 * @connection: a #GDBusConnection
15443 * @export_id: the ID from g_dbus_connection_export_menu_model()
15445 * Reverses the effect of a previous call to
15446 * g_dbus_connection_export_menu_model().
15448 * It is an error to call this function with an ID that wasn't returned
15449 * from g_dbus_connection_export_menu_model() or to call it with the
15450 * same ID more than once.
15457 * g_dbus_connection_unregister_object:
15458 * @connection: a #GDBusConnection
15459 * @registration_id: a registration id obtained from
15460 * g_dbus_connection_register_object()
15462 * Unregisters an object.
15464 * Returns: %TRUE if the object was unregistered, %FALSE otherwise
15470 * g_dbus_connection_unregister_subtree:
15471 * @connection: a #GDBusConnection
15472 * @registration_id: a subtree registration id obtained from
15473 * g_dbus_connection_register_subtree()
15475 * Unregisters a subtree.
15477 * Returns: %TRUE if the subtree was unregistered, %FALSE otherwise
15483 * g_dbus_error_encode_gerror:
15484 * @error: A #GError.
15486 * Creates a D-Bus error name to use for @error. If @error matches
15487 * a registered error (cf. g_dbus_error_register_error()), the corresponding
15488 * D-Bus error name will be returned.
15490 * Otherwise the a name of the form
15491 * `org.gtk.GDBus.UnmappedGError.Quark._ESCAPED_QUARK_NAME.Code_ERROR_CODE`
15492 * will be used. This allows other GDBus applications to map the error
15493 * on the wire back to a #GError using g_dbus_error_new_for_dbus_error().
15495 * This function is typically only used in object mappings to put a
15496 * #GError on the wire. Regular applications should not use it.
15498 * Returns: A D-Bus error name (never %NULL). Free with g_free().
15504 * g_dbus_error_get_remote_error:
15505 * @error: a #GError
15507 * Gets the D-Bus error name used for @error, if any.
15509 * This function is guaranteed to return a D-Bus error name for all
15510 * #GErrors returned from functions handling remote method calls
15511 * (e.g. g_dbus_connection_call_finish()) unless
15512 * g_dbus_error_strip_remote_error() has been used on @error.
15514 * Returns: an allocated string or %NULL if the D-Bus error name
15515 * could not be found. Free with g_free().
15521 * g_dbus_error_is_remote_error:
15522 * @error: A #GError.
15524 * Checks if @error represents an error received via D-Bus from a remote peer. If so,
15525 * use g_dbus_error_get_remote_error() to get the name of the error.
15527 * Returns: %TRUE if @error represents an error from a remote peer,
15528 * %FALSE otherwise.
15534 * g_dbus_error_new_for_dbus_error:
15535 * @dbus_error_name: D-Bus error name.
15536 * @dbus_error_message: D-Bus error message.
15538 * Creates a #GError based on the contents of @dbus_error_name and
15539 * @dbus_error_message.
15541 * Errors registered with g_dbus_error_register_error() will be looked
15542 * up using @dbus_error_name and if a match is found, the error domain
15543 * and code is used. Applications can use g_dbus_error_get_remote_error()
15544 * to recover @dbus_error_name.
15546 * If a match against a registered error is not found and the D-Bus
15547 * error name is in a form as returned by g_dbus_error_encode_gerror()
15548 * the error domain and code encoded in the name is used to
15549 * create the #GError. Also, @dbus_error_name is added to the error message
15550 * such that it can be recovered with g_dbus_error_get_remote_error().
15552 * Otherwise, a #GError with the error code %G_IO_ERROR_DBUS_ERROR
15553 * in the #G_IO_ERROR error domain is returned. Also, @dbus_error_name is
15554 * added to the error message such that it can be recovered with
15555 * g_dbus_error_get_remote_error().
15557 * In all three cases, @dbus_error_name can always be recovered from the
15558 * returned #GError using the g_dbus_error_get_remote_error() function
15559 * (unless g_dbus_error_strip_remote_error() hasn't been used on the returned error).
15561 * This function is typically only used in object mappings to prepare
15562 * #GError instances for applications. Regular applications should not use
15565 * Returns: An allocated #GError. Free with g_error_free().
15571 * g_dbus_error_register_error:
15572 * @error_domain: A #GQuark for a error domain.
15573 * @error_code: An error code.
15574 * @dbus_error_name: A D-Bus error name.
15576 * Creates an association to map between @dbus_error_name and
15577 * #GErrors specified by @error_domain and @error_code.
15579 * This is typically done in the routine that returns the #GQuark for
15582 * Returns: %TRUE if the association was created, %FALSE if it already
15589 * g_dbus_error_register_error_domain:
15590 * @error_domain_quark_name: The error domain name.
15591 * @quark_volatile: A pointer where to store the #GQuark.
15592 * @entries: A pointer to @num_entries #GDBusErrorEntry struct items.
15593 * @num_entries: Number of items to register.
15595 * Helper function for associating a #GError error domain with D-Bus error names.
15602 * g_dbus_error_set_dbus_error:
15603 * @error: A pointer to a #GError or %NULL.
15604 * @dbus_error_name: D-Bus error name.
15605 * @dbus_error_message: D-Bus error message.
15606 * @format: (allow-none): printf()-style format to prepend to @dbus_error_message or %NULL.
15607 * @...: Arguments for @format.
15609 * Does nothing if @error is %NULL. Otherwise sets *@error to
15610 * a new #GError created with g_dbus_error_new_for_dbus_error()
15611 * with @dbus_error_message prepend with @format (unless %NULL).
15618 * g_dbus_error_set_dbus_error_valist:
15619 * @error: A pointer to a #GError or %NULL.
15620 * @dbus_error_name: D-Bus error name.
15621 * @dbus_error_message: D-Bus error message.
15622 * @format: (allow-none): printf()-style format to prepend to @dbus_error_message or %NULL.
15623 * @var_args: Arguments for @format.
15625 * Like g_dbus_error_set_dbus_error() but intended for language bindings.
15632 * g_dbus_error_strip_remote_error:
15633 * @error: A #GError.
15635 * Looks for extra information in the error message used to recover
15636 * the D-Bus error name and strips it if found. If stripped, the
15637 * message field in @error will correspond exactly to what was
15638 * received on the wire.
15640 * This is typically used when presenting errors to the end user.
15642 * Returns: %TRUE if information was stripped, %FALSE otherwise.
15648 * g_dbus_error_unregister_error:
15649 * @error_domain: A #GQuark for a error domain.
15650 * @error_code: An error code.
15651 * @dbus_error_name: A D-Bus error name.
15653 * Destroys an association previously set up with g_dbus_error_register_error().
15655 * Returns: %TRUE if the association was destroyed, %FALSE if it wasn't found.
15661 * g_dbus_generate_guid:
15663 * Generate a D-Bus GUID that can be used with
15664 * e.g. g_dbus_connection_new().
15666 * See the D-Bus specification regarding what strings are valid D-Bus
15667 * GUID (for example, D-Bus GUIDs are not RFC-4122 compliant).
15669 * Returns: A valid D-Bus GUID. Free with g_free().
15675 * g_dbus_gvalue_to_gvariant:
15676 * @gvalue: A #GValue to convert to a #GVariant
15677 * @type: A #GVariantType
15679 * Converts a #GValue to a #GVariant of the type indicated by the @type
15682 * The conversion is using the following rules:
15684 * - #G_TYPE_STRING: 's', 'o', 'g' or 'ay'
15685 * - #G_TYPE_STRV: 'as', 'ao' or 'aay'
15686 * - #G_TYPE_BOOLEAN: 'b'
15687 * - #G_TYPE_UCHAR: 'y'
15688 * - #G_TYPE_INT: 'i', 'n'
15689 * - #G_TYPE_UINT: 'u', 'q'
15690 * - #G_TYPE_INT64 'x'
15691 * - #G_TYPE_UINT64: 't'
15692 * - #G_TYPE_DOUBLE: 'd'
15693 * - #G_TYPE_VARIANT: Any #GVariantType
15695 * This can fail if e.g. @gvalue is of type #G_TYPE_STRING and @type
15696 * is ['i'][G-VARIANT-TYPE-INT32:CAPS]. It will also fail for any #GType
15697 * (including e.g. #G_TYPE_OBJECT and #G_TYPE_BOXED derived-types) not
15698 * in the table above.
15700 * Note that if @gvalue is of type #G_TYPE_VARIANT and its value is
15701 * %NULL, the empty #GVariant instance (never %NULL) for @type is
15702 * returned (e.g. 0 for scalar types, the empty string for string types,
15703 * '/' for object path types, the empty array for any array type and so on).
15705 * See the g_dbus_gvariant_to_gvalue() function for how to convert a
15706 * #GVariant to a #GValue.
15708 * Returns: A #GVariant (never floating) of #GVariantType @type holding
15709 * the data from @gvalue or %NULL in case of failure. Free with
15710 * g_variant_unref().
15716 * g_dbus_gvariant_to_gvalue:
15717 * @value: A #GVariant.
15718 * @out_gvalue: (out): Return location pointing to a zero-filled (uninitialized) #GValue.
15720 * Converts a #GVariant to a #GValue. If @value is floating, it is consumed.
15722 * The rules specified in the g_dbus_gvalue_to_gvariant() function are
15723 * used - this function is essentially its reverse form.
15725 * The conversion never fails - a valid #GValue is always returned in
15733 * g_dbus_interface_dup_object: (rename-to g_dbus_interface_get_object)
15734 * @interface_: An exported D-Bus interface.
15736 * Gets the #GDBusObject that @interface_ belongs to, if any.
15738 * Returns: (transfer full): A #GDBusObject or %NULL. The returned
15739 * reference should be freed with g_object_unref().
15745 * g_dbus_interface_get_info:
15746 * @interface_: An exported D-Bus interface.
15748 * Gets D-Bus introspection information for the D-Bus interface
15749 * implemented by @interface_.
15751 * Returns: (transfer none): A #GDBusInterfaceInfo. Do not free.
15757 * g_dbus_interface_get_object: (skip)
15758 * @interface_: An exported D-Bus interface
15760 * Gets the #GDBusObject that @interface_ belongs to, if any.
15762 * It is not safe to use the returned object if @interface_ or
15763 * the returned object is being used from other threads. See
15764 * g_dbus_interface_dup_object() for a thread-safe alternative.
15766 * Returns: (transfer none): A #GDBusObject or %NULL. The returned
15767 * reference belongs to @interface_ and should not be freed.
15773 * g_dbus_interface_info_cache_build:
15774 * @info: A #GDBusInterfaceInfo.
15776 * Builds a lookup-cache to speed up
15777 * g_dbus_interface_info_lookup_method(),
15778 * g_dbus_interface_info_lookup_signal() and
15779 * g_dbus_interface_info_lookup_property().
15781 * If this has already been called with @info, the existing cache is
15782 * used and its use count is increased.
15784 * Note that @info cannot be modified until
15785 * g_dbus_interface_info_cache_release() is called.
15792 * g_dbus_interface_info_cache_release:
15793 * @info: A GDBusInterfaceInfo
15795 * Decrements the usage count for the cache for @info built by
15796 * g_dbus_interface_info_cache_build() (if any) and frees the
15797 * resources used by the cache if the usage count drops to zero.
15804 * g_dbus_interface_info_generate_xml:
15805 * @info: A #GDBusNodeInfo
15806 * @indent: Indentation level.
15807 * @string_builder: (out): A #GString to to append XML data to.
15809 * Appends an XML representation of @info (and its children) to @string_builder.
15811 * This function is typically used for generating introspection XML
15812 * documents at run-time for handling the
15813 * `org.freedesktop.DBus.Introspectable.Introspect`
15821 * g_dbus_interface_info_lookup_method:
15822 * @info: A #GDBusInterfaceInfo.
15823 * @name: A D-Bus method name (typically in CamelCase)
15825 * Looks up information about a method.
15827 * The cost of this function is O(n) in number of methods unless
15828 * g_dbus_interface_info_cache_build() has been used on @info.
15830 * Returns: (transfer none): A #GDBusMethodInfo or %NULL if not found. Do not free, it is owned by @info.
15836 * g_dbus_interface_info_lookup_property:
15837 * @info: A #GDBusInterfaceInfo.
15838 * @name: A D-Bus property name (typically in CamelCase).
15840 * Looks up information about a property.
15842 * The cost of this function is O(n) in number of properties unless
15843 * g_dbus_interface_info_cache_build() has been used on @info.
15845 * Returns: (transfer none): A #GDBusPropertyInfo or %NULL if not found. Do not free, it is owned by @info.
15851 * g_dbus_interface_info_lookup_signal:
15852 * @info: A #GDBusInterfaceInfo.
15853 * @name: A D-Bus signal name (typically in CamelCase)
15855 * Looks up information about a signal.
15857 * The cost of this function is O(n) in number of signals unless
15858 * g_dbus_interface_info_cache_build() has been used on @info.
15860 * Returns: (transfer none): A #GDBusSignalInfo or %NULL if not found. Do not free, it is owned by @info.
15866 * g_dbus_interface_info_ref:
15867 * @info: A #GDBusInterfaceInfo
15869 * If @info is statically allocated does nothing. Otherwise increases
15870 * the reference count.
15872 * Returns: The same @info.
15878 * g_dbus_interface_info_unref:
15879 * @info: A #GDBusInterfaceInfo.
15881 * If @info is statically allocated, does nothing. Otherwise decreases
15882 * the reference count of @info. When its reference count drops to 0,
15883 * the memory used is freed.
15890 * g_dbus_interface_set_object:
15891 * @interface_: An exported D-Bus interface.
15892 * @object: (allow-none): A #GDBusObject or %NULL.
15894 * Sets the #GDBusObject for @interface_ to @object.
15896 * Note that @interface_ will hold a weak reference to @object.
15903 * g_dbus_interface_skeleton_export:
15904 * @interface_: The D-Bus interface to export.
15905 * @connection: A #GDBusConnection to export @interface_ on.
15906 * @object_path: The path to export the interface at.
15907 * @error: Return location for error or %NULL.
15909 * Exports @interface_ at @object_path on @connection.
15911 * This can be called multiple times to export the same @interface_
15912 * onto multiple connections however the @object_path provided must be
15913 * the same for all connections.
15915 * Use g_dbus_interface_skeleton_unexport() to unexport the object.
15917 * Returns: %TRUE if the interface was exported on @connection, otherwise %FALSE with
15924 * g_dbus_interface_skeleton_flush:
15925 * @interface_: A #GDBusInterfaceSkeleton.
15927 * If @interface_ has outstanding changes, request for these changes to be
15928 * emitted immediately.
15930 * For example, an exported D-Bus interface may queue up property
15931 * changes and emit the
15932 * `org.freedesktop.DBus.Properties::Propert``
15933 * signal later (e.g. in an idle handler). This technique is useful
15934 * for collapsing multiple property changes into one.
15941 * g_dbus_interface_skeleton_get_connection:
15942 * @interface_: A #GDBusInterfaceSkeleton.
15944 * Gets the first connection that @interface_ is exported on, if any.
15946 * Returns: (transfer none): A #GDBusConnection or %NULL if @interface_ is
15947 * not exported anywhere. Do not free, the object belongs to @interface_.
15953 * g_dbus_interface_skeleton_get_connections:
15954 * @interface_: A #GDBusInterfaceSkeleton.
15956 * Gets a list of the connections that @interface_ is exported on.
15958 * Returns: (element-type GDBusConnection) (transfer full): A list of
15959 * all the connections that @interface_ is exported on. The returned
15960 * list should be freed with g_list_free() after each element has
15961 * been freed with g_object_unref().
15967 * g_dbus_interface_skeleton_get_flags:
15968 * @interface_: A #GDBusInterfaceSkeleton.
15970 * Gets the #GDBusInterfaceSkeletonFlags that describes what the behavior
15973 * Returns: One or more flags from the #GDBusInterfaceSkeletonFlags enumeration.
15979 * g_dbus_interface_skeleton_get_info:
15980 * @interface_: A #GDBusInterfaceSkeleton.
15982 * Gets D-Bus introspection information for the D-Bus interface
15983 * implemented by @interface_.
15985 * Returns: (transfer none): A #GDBusInterfaceInfo (never %NULL). Do not free.
15991 * g_dbus_interface_skeleton_get_object_path:
15992 * @interface_: A #GDBusInterfaceSkeleton.
15994 * Gets the object path that @interface_ is exported on, if any.
15996 * Returns: A string owned by @interface_ or %NULL if @interface_ is not exported
15997 * anywhere. Do not free, the string belongs to @interface_.
16003 * g_dbus_interface_skeleton_get_properties:
16004 * @interface_: A #GDBusInterfaceSkeleton.
16006 * Gets all D-Bus properties for @interface_.
16008 * Returns: (transfer full): A #GVariant of type
16009 * ['a{sv}'][G-VARIANT-TYPE-VARDICT:CAPS].
16010 * Free with g_variant_unref().
16016 * g_dbus_interface_skeleton_get_vtable: (skip)
16017 * @interface_: A #GDBusInterfaceSkeleton.
16019 * Gets the interface vtable for the D-Bus interface implemented by
16020 * @interface_. The returned function pointers should expect @interface_
16021 * itself to be passed as @user_data.
16023 * Returns: A #GDBusInterfaceVTable (never %NULL).
16029 * g_dbus_interface_skeleton_has_connection:
16030 * @interface_: A #GDBusInterfaceSkeleton.
16031 * @connection: A #GDBusConnection.
16033 * Checks if @interface_ is exported on @connection.
16035 * Returns: %TRUE if @interface_ is exported on @connection, %FALSE otherwise.
16041 * g_dbus_interface_skeleton_set_flags:
16042 * @interface_: A #GDBusInterfaceSkeleton.
16043 * @flags: Flags from the #GDBusInterfaceSkeletonFlags enumeration.
16045 * Sets flags describing what the behavior of @skeleton should be.
16052 * g_dbus_interface_skeleton_unexport:
16053 * @interface_: A #GDBusInterfaceSkeleton.
16055 * Stops exporting @interface_ on all connections it is exported on.
16057 * To unexport @interface_ from only a single connection, use
16058 * g_dbus_interface_skeleton_unexport_from_connection()
16065 * g_dbus_interface_skeleton_unexport_from_connection:
16066 * @interface_: A #GDBusInterfaceSkeleton.
16067 * @connection: A #GDBusConnection.
16069 * Stops exporting @interface_ on @connection.
16071 * To stop exporting on all connections the interface is exported on,
16072 * use g_dbus_interface_skeleton_unexport().
16079 * g_dbus_is_address:
16080 * @string: A string.
16082 * Checks if @string is a D-Bus address.
16084 * This doesn't check if @string is actually supported by #GDBusServer
16085 * or #GDBusConnection - use g_dbus_is_supported_address() to do more
16088 * Returns: %TRUE if @string is a valid D-Bus address, %FALSE otherwise.
16095 * @string: The string to check.
16097 * Checks if @string is a D-Bus GUID.
16099 * See the D-Bus specification regarding what strings are valid D-Bus
16100 * GUID (for example, D-Bus GUIDs are not RFC-4122 compliant).
16102 * Returns: %TRUE if @string is a guid, %FALSE otherwise.
16108 * g_dbus_is_interface_name:
16109 * @string: The string to check.
16111 * Checks if @string is a valid D-Bus interface name.
16113 * Returns: %TRUE if valid, %FALSE otherwise.
16119 * g_dbus_is_member_name:
16120 * @string: The string to check.
16122 * Checks if @string is a valid D-Bus member (e.g. signal or method) name.
16124 * Returns: %TRUE if valid, %FALSE otherwise.
16131 * @string: The string to check.
16133 * Checks if @string is a valid D-Bus bus name (either unique or well-known).
16135 * Returns: %TRUE if valid, %FALSE otherwise.
16141 * g_dbus_is_supported_address:
16142 * @string: A string.
16143 * @error: Return location for error or %NULL.
16145 * Like g_dbus_is_address() but also checks if the library suppors the
16146 * transports in @string and that key/value pairs for each transport
16149 * Returns: %TRUE if @string is a valid D-Bus address that is
16150 * supported by this library, %FALSE if @error is set.
16156 * g_dbus_is_unique_name:
16157 * @string: The string to check.
16159 * Checks if @string is a valid D-Bus unique bus name.
16161 * Returns: %TRUE if valid, %FALSE otherwise.
16167 * g_dbus_menu_model_get:
16168 * @connection: a #GDBusConnection
16169 * @bus_name: the bus name which exports the menu model
16170 * @object_path: the object path at which the menu model is exported
16172 * Obtains a #GDBusMenuModel for the menu model which is exported
16173 * at the given @bus_name and @object_path.
16175 * The thread default main context is taken at the time of this call.
16176 * All signals on the menu model (and any linked models) are reported
16177 * with respect to this context. All calls on the returned menu model
16178 * (and linked models) must also originate from this same context, with
16179 * the thread default main context unchanged.
16181 * Returns: (transfer full): a #GDBusMenuModel object. Free with
16182 * g_object_unref().
16188 * g_dbus_message_bytes_needed:
16189 * @blob: (array length=blob_len) (element-type guint8): A blob represent a binary D-Bus message.
16190 * @blob_len: The length of @blob (must be at least 16).
16191 * @error: Return location for error or %NULL.
16193 * Utility function to calculate how many bytes are needed to
16194 * completely deserialize the D-Bus message stored at @blob.
16196 * Returns: Number of bytes needed or -1 if @error is set (e.g. if
16197 * @blob contains invalid data or not enough data is available to
16198 * determine the size).
16204 * g_dbus_message_copy:
16205 * @message: A #GDBusMessage.
16206 * @error: Return location for error or %NULL.
16208 * Copies @message. The copy is a deep copy and the returned
16209 * #GDBusMessage is completely identical except that it is guaranteed
16210 * to not be locked.
16212 * This operation can fail if e.g. @message contains file descriptors
16213 * and the per-process or system-wide open files limit is reached.
16215 * Returns: (transfer full): A new #GDBusMessage or %NULL if @error is set.
16216 * Free with g_object_unref().
16222 * g_dbus_message_get_arg0:
16223 * @message: A #GDBusMessage.
16225 * Convenience to get the first item in the body of @message.
16227 * Returns: The string item or %NULL if the first item in the body of
16228 * @message is not a string.
16234 * g_dbus_message_get_body:
16235 * @message: A #GDBusMessage.
16237 * Gets the body of a message.
16239 * Returns: (transfer none): A #GVariant or %NULL if the body is
16240 * empty. Do not free, it is owned by @message.
16246 * g_dbus_message_get_byte_order:
16247 * @message: A #GDBusMessage.
16249 * Gets the byte order of @message.
16251 * Returns: The byte order.
16256 * g_dbus_message_get_destination:
16257 * @message: A #GDBusMessage.
16259 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field.
16261 * Returns: The value.
16267 * g_dbus_message_get_error_name:
16268 * @message: A #GDBusMessage.
16270 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field.
16272 * Returns: The value.
16278 * g_dbus_message_get_flags:
16279 * @message: A #GDBusMessage.
16281 * Gets the flags for @message.
16283 * Returns: Flags that are set (typically values from the #GDBusMessageFlags enumeration bitwise ORed together).
16289 * g_dbus_message_get_header:
16290 * @message: A #GDBusMessage.
16291 * @header_field: A 8-bit unsigned integer (typically a value from the #GDBusMessageHeaderField enumeration)
16293 * Gets a header field on @message.
16295 * Returns: A #GVariant with the value if the header was found, %NULL
16296 * otherwise. Do not free, it is owned by @message.
16302 * g_dbus_message_get_header_fields:
16303 * @message: A #GDBusMessage.
16305 * Gets an array of all header fields on @message that are set.
16307 * Returns: (array zero-terminated=1): An array of header fields
16308 * terminated by %G_DBUS_MESSAGE_HEADER_FIELD_INVALID. Each element
16309 * is a #guchar. Free with g_free().
16315 * g_dbus_message_get_interface:
16316 * @message: A #GDBusMessage.
16318 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE header field.
16320 * Returns: The value.
16326 * g_dbus_message_get_locked:
16327 * @message: A #GDBusMessage.
16329 * Checks whether @message is locked. To monitor changes to this
16330 * value, conncet to the #GObject::notify signal to listen for changes
16331 * on the #GDBusMessage:locked property.
16333 * Returns: %TRUE if @message is locked, %FALSE otherwise.
16339 * g_dbus_message_get_member:
16340 * @message: A #GDBusMessage.
16342 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_MEMBER header field.
16344 * Returns: The value.
16350 * g_dbus_message_get_message_type:
16351 * @message: A #GDBusMessage.
16353 * Gets the type of @message.
16355 * Returns: A 8-bit unsigned integer (typically a value from the #GDBusMessageType enumeration).
16361 * g_dbus_message_get_num_unix_fds:
16362 * @message: A #GDBusMessage.
16364 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header field.
16366 * Returns: The value.
16372 * g_dbus_message_get_path:
16373 * @message: A #GDBusMessage.
16375 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_PATH header field.
16377 * Returns: The value.
16383 * g_dbus_message_get_reply_serial:
16384 * @message: A #GDBusMessage.
16386 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL header field.
16388 * Returns: The value.
16394 * g_dbus_message_get_sender:
16395 * @message: A #GDBusMessage.
16397 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_SENDER header field.
16399 * Returns: The value.
16405 * g_dbus_message_get_serial:
16406 * @message: A #GDBusMessage.
16408 * Gets the serial for @message.
16410 * Returns: A #guint32.
16416 * g_dbus_message_get_signature:
16417 * @message: A #GDBusMessage.
16419 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field.
16421 * Returns: The value.
16427 * g_dbus_message_get_unix_fd_list:
16428 * @message: A #GDBusMessage.
16430 * Gets the UNIX file descriptors associated with @message, if any.
16432 * This method is only available on UNIX.
16434 * Returns: (transfer none): A #GUnixFDList or %NULL if no file descriptors are
16435 * associated. Do not free, this object is owned by @message.
16441 * g_dbus_message_lock:
16442 * @message: A #GDBusMessage.
16444 * If @message is locked, does nothing. Otherwise locks the message.
16451 * g_dbus_message_new:
16453 * Creates a new empty #GDBusMessage.
16455 * Returns: A #GDBusMessage. Free with g_object_unref().
16461 * g_dbus_message_new_from_blob:
16462 * @blob: (array length=blob_len) (element-type guint8): A blob represent a binary D-Bus message.
16463 * @blob_len: The length of @blob.
16464 * @capabilities: A #GDBusCapabilityFlags describing what protocol features are supported.
16465 * @error: Return location for error or %NULL.
16467 * Creates a new #GDBusMessage from the data stored at @blob. The byte
16468 * order that the message was in can be retrieved using
16469 * g_dbus_message_get_byte_order().
16471 * Returns: A new #GDBusMessage or %NULL if @error is set. Free with
16472 * g_object_unref().
16478 * g_dbus_message_new_method_call:
16479 * @name: (allow-none): A valid D-Bus name or %NULL.
16480 * @path: A valid object path.
16481 * @interface_: (allow-none): A valid D-Bus interface name or %NULL.
16482 * @method: A valid method name.
16484 * Creates a new #GDBusMessage for a method call.
16486 * Returns: A #GDBusMessage. Free with g_object_unref().
16492 * g_dbus_message_new_method_error:
16493 * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to
16494 * create a reply message to.
16495 * @error_name: A valid D-Bus error name.
16496 * @error_message_format: The D-Bus error message in a printf() format.
16497 * @...: Arguments for @error_message_format.
16499 * Creates a new #GDBusMessage that is an error reply to @method_call_message.
16501 * Returns: (transfer full): A #GDBusMessage. Free with g_object_unref().
16507 * g_dbus_message_new_method_error_literal:
16508 * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to
16509 * create a reply message to.
16510 * @error_name: A valid D-Bus error name.
16511 * @error_message: The D-Bus error message.
16513 * Creates a new #GDBusMessage that is an error reply to @method_call_message.
16515 * Returns: (transfer full): A #GDBusMessage. Free with g_object_unref().
16521 * g_dbus_message_new_method_error_valist:
16522 * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to
16523 * create a reply message to.
16524 * @error_name: A valid D-Bus error name.
16525 * @error_message_format: The D-Bus error message in a printf() format.
16526 * @var_args: Arguments for @error_message_format.
16528 * Like g_dbus_message_new_method_error() but intended for language bindings.
16530 * Returns: (transfer full): A #GDBusMessage. Free with g_object_unref().
16536 * g_dbus_message_new_method_reply:
16537 * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to
16538 * create a reply message to.
16540 * Creates a new #GDBusMessage that is a reply to @method_call_message.
16542 * Returns: (transfer full): #GDBusMessage. Free with g_object_unref().
16548 * g_dbus_message_new_signal:
16549 * @path: A valid object path.
16550 * @interface_: A valid D-Bus interface name.
16551 * @signal: A valid signal name.
16553 * Creates a new #GDBusMessage for a signal emission.
16555 * Returns: A #GDBusMessage. Free with g_object_unref().
16561 * g_dbus_message_print: (type method-return)
16562 * @message: A #GDBusMessage.
16563 * @indent: Indentation level.
16565 * Produces a human-readable multi-line description of @message.
16567 * The contents of the description has no ABI guarantees, the contents
16568 * and formatting is subject to change at any time. Typical output
16569 * looks something like this:
16575 * path -> objectpath '/org/gtk/GDBus/TestObject'
16576 * interface -> 'org.gtk.GDBus.TestInterface'
16577 * member -> 'GimmeStdout'
16578 * destination -> ':1.146'
16580 * UNIX File Descriptors:
16585 * Flags: no-reply-expected
16589 * reply-serial -> uint32 4
16590 * destination -> ':1.159'
16591 * sender -> ':1.146'
16592 * num-unix-fds -> uint32 1
16594 * UNIX File Descriptors:
16595 * fd 12: dev=0:10,mode=020620,ino=5,uid=500,gid=5,rdev=136:2,size=0,atime=1273085037,mtime=1273085851,ctime=1272982635
16598 * Returns: A string that should be freed with g_free().
16604 * g_dbus_message_set_body:
16605 * @message: A #GDBusMessage.
16606 * @body: Either %NULL or a #GVariant that is a tuple.
16608 * Sets the body @message. As a side-effect the
16609 * %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field is set to the
16610 * type string of @body (or cleared if @body is %NULL).
16612 * If @body is floating, @message assumes ownership of @body.
16619 * g_dbus_message_set_byte_order:
16620 * @message: A #GDBusMessage.
16621 * @byte_order: The byte order.
16623 * Sets the byte order of @message.
16628 * g_dbus_message_set_destination:
16629 * @message: A #GDBusMessage.
16630 * @value: The value to set.
16632 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field.
16639 * g_dbus_message_set_error_name:
16640 * @message: A #GDBusMessage.
16641 * @value: The value to set.
16643 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field.
16650 * g_dbus_message_set_flags:
16651 * @message: A #GDBusMessage.
16652 * @flags: Flags for @message that are set (typically values from the #GDBusMessageFlags
16653 * enumeration bitwise ORed together).
16655 * Sets the flags to set on @message.
16662 * g_dbus_message_set_header:
16663 * @message: A #GDBusMessage.
16664 * @header_field: A 8-bit unsigned integer (typically a value from the #GDBusMessageHeaderField enumeration)
16665 * @value: (allow-none): A #GVariant to set the header field or %NULL to clear the header field.
16667 * Sets a header field on @message.
16669 * If @value is floating, @message assumes ownership of @value.
16676 * g_dbus_message_set_interface:
16677 * @message: A #GDBusMessage.
16678 * @value: The value to set.
16680 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE header field.
16687 * g_dbus_message_set_member:
16688 * @message: A #GDBusMessage.
16689 * @value: The value to set.
16691 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_MEMBER header field.
16698 * g_dbus_message_set_message_type:
16699 * @message: A #GDBusMessage.
16700 * @type: A 8-bit unsigned integer (typically a value from the #GDBusMessageType enumeration).
16702 * Sets @message to be of @type.
16709 * g_dbus_message_set_num_unix_fds:
16710 * @message: A #GDBusMessage.
16711 * @value: The value to set.
16713 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header field.
16720 * g_dbus_message_set_path:
16721 * @message: A #GDBusMessage.
16722 * @value: The value to set.
16724 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_PATH header field.
16731 * g_dbus_message_set_reply_serial:
16732 * @message: A #GDBusMessage.
16733 * @value: The value to set.
16735 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL header field.
16742 * g_dbus_message_set_sender:
16743 * @message: A #GDBusMessage.
16744 * @value: The value to set.
16746 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_SENDER header field.
16753 * g_dbus_message_set_serial:
16754 * @message: A #GDBusMessage.
16755 * @serial: A #guint32.
16757 * Sets the serial for @message.
16764 * g_dbus_message_set_signature:
16765 * @message: A #GDBusMessage.
16766 * @value: The value to set.
16768 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field.
16775 * g_dbus_message_set_unix_fd_list:
16776 * @message: A #GDBusMessage.
16777 * @fd_list: (allow-none): A #GUnixFDList or %NULL.
16779 * Sets the UNIX file descriptors associated with @message. As a
16780 * side-effect the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header
16781 * field is set to the number of fds in @fd_list (or cleared if
16782 * @fd_list is %NULL).
16784 * This method is only available on UNIX.
16791 * g_dbus_message_to_blob:
16792 * @message: A #GDBusMessage.
16793 * @out_size: Return location for size of generated blob.
16794 * @capabilities: A #GDBusCapabilityFlags describing what protocol features are supported.
16795 * @error: Return location for error.
16797 * Serializes @message to a blob. The byte order returned by
16798 * g_dbus_message_get_byte_order() will be used.
16800 * Returns: (array length=out_size) (transfer full): A pointer to a
16801 * valid binary D-Bus message of @out_size bytes generated by @message
16802 * or %NULL if @error is set. Free with g_free().
16808 * g_dbus_message_to_gerror:
16809 * @message: A #GDBusMessage.
16810 * @error: The #GError to set.
16812 * If @message is not of type %G_DBUS_MESSAGE_TYPE_ERROR does
16813 * nothing and returns %FALSE.
16815 * Otherwise this method encodes the error in @message as a #GError
16816 * using g_dbus_error_set_dbus_error() using the information in the
16817 * %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field of @message as
16818 * well as the first string item in @message's body.
16820 * Returns: %TRUE if @error was set, %FALSE otherwise.
16826 * g_dbus_method_info_ref:
16827 * @info: A #GDBusMethodInfo
16829 * If @info is statically allocated does nothing. Otherwise increases
16830 * the reference count.
16832 * Returns: The same @info.
16838 * g_dbus_method_info_unref:
16839 * @info: A #GDBusMethodInfo.
16841 * If @info is statically allocated, does nothing. Otherwise decreases
16842 * the reference count of @info. When its reference count drops to 0,
16843 * the memory used is freed.
16850 * g_dbus_method_invocation_get_connection:
16851 * @invocation: A #GDBusMethodInvocation.
16853 * Gets the #GDBusConnection the method was invoked on.
16855 * Returns: (transfer none): A #GDBusConnection. Do not free, it is owned by @invocation.
16861 * g_dbus_method_invocation_get_interface_name:
16862 * @invocation: A #GDBusMethodInvocation.
16864 * Gets the name of the D-Bus interface the method was invoked on.
16866 * If this method call is a property Get, Set or GetAll call that has
16867 * been redirected to the method call handler then
16868 * "org.freedesktop.DBus.Properties" will be returned. See
16869 * #GDBusInterfaceVTable for more information.
16871 * Returns: A string. Do not free, it is owned by @invocation.
16877 * g_dbus_method_invocation_get_message:
16878 * @invocation: A #GDBusMethodInvocation.
16880 * Gets the #GDBusMessage for the method invocation. This is useful if
16881 * you need to use low-level protocol features, such as UNIX file
16882 * descriptor passing, that cannot be properly expressed in the
16885 * See this [server][gdbus-server] and [client][gdbus-unix-fd-client]
16886 * for an example of how to use this low-level API to send and receive
16887 * UNIX file descriptors.
16889 * Returns: (transfer none): #GDBusMessage. Do not free, it is owned by @invocation.
16895 * g_dbus_method_invocation_get_method_info:
16896 * @invocation: A #GDBusMethodInvocation.
16898 * Gets information about the method call, if any.
16900 * If this method invocation is a property Get, Set or GetAll call that
16901 * has been redirected to the method call handler then %NULL will be
16902 * returned. See g_dbus_method_invocation_get_property_info() and
16903 * #GDBusInterfaceVTable for more information.
16905 * Returns: A #GDBusMethodInfo or %NULL. Do not free, it is owned by @invocation.
16911 * g_dbus_method_invocation_get_method_name:
16912 * @invocation: A #GDBusMethodInvocation.
16914 * Gets the name of the method that was invoked.
16916 * Returns: A string. Do not free, it is owned by @invocation.
16922 * g_dbus_method_invocation_get_object_path:
16923 * @invocation: A #GDBusMethodInvocation.
16925 * Gets the object path the method was invoked on.
16927 * Returns: A string. Do not free, it is owned by @invocation.
16933 * g_dbus_method_invocation_get_parameters:
16934 * @invocation: A #GDBusMethodInvocation.
16936 * Gets the parameters of the method invocation. If there are no input
16937 * parameters then this will return a GVariant with 0 children rather than NULL.
16939 * Returns: (transfer none): A #GVariant tuple. Do not unref this because it is owned by @invocation.
16945 * g_dbus_method_invocation_get_property_info:
16946 * @invocation: A #GDBusMethodInvocation
16948 * Gets information about the property that this method call is for, if
16951 * This will only be set in the case of an invocation in response to a
16952 * property Get or Set call that has been directed to the method call
16953 * handler for an object on account of its property_get() or
16954 * property_set() vtable pointers being unset.
16956 * See #GDBusInterfaceVTable for more information.
16958 * If the call was GetAll, %NULL will be returned.
16960 * Returns: (transfer none): a #GDBusPropertyInfo or %NULL
16966 * g_dbus_method_invocation_get_sender:
16967 * @invocation: A #GDBusMethodInvocation.
16969 * Gets the bus name that invoked the method.
16971 * Returns: A string. Do not free, it is owned by @invocation.
16977 * g_dbus_method_invocation_get_user_data: (skip)
16978 * @invocation: A #GDBusMethodInvocation.
16980 * Gets the @user_data #gpointer passed to g_dbus_connection_register_object().
16982 * Returns: A #gpointer.
16988 * g_dbus_method_invocation_return_dbus_error:
16989 * @invocation: (transfer full): A #GDBusMethodInvocation.
16990 * @error_name: A valid D-Bus error name.
16991 * @error_message: A valid D-Bus error message.
16993 * Finishes handling a D-Bus method call by returning an error.
16995 * This method will free @invocation, you cannot use it afterwards.
17002 * g_dbus_method_invocation_return_error:
17003 * @invocation: (transfer full): A #GDBusMethodInvocation.
17004 * @domain: A #GQuark for the #GError error domain.
17005 * @code: The error code.
17006 * @format: printf()-style format.
17007 * @...: Parameters for @format.
17009 * Finishes handling a D-Bus method call by returning an error.
17011 * See g_dbus_error_encode_gerror() for details about what error name
17012 * will be returned on the wire. In a nutshell, if the given error is
17013 * registered using g_dbus_error_register_error() the name given
17014 * during registration is used. Otherwise, a name of the form
17015 * `org.gtk.GDBus.UnmappedGError.Quark...` is used. This provides
17016 * transparent mapping of #GError between applications using GDBus.
17018 * If you are writing an application intended to be portable,
17019 * always register errors with g_dbus_error_register_error()
17020 * or use g_dbus_method_invocation_return_dbus_error().
17022 * This method will free @invocation, you cannot use it afterwards.
17029 * g_dbus_method_invocation_return_error_literal:
17030 * @invocation: (transfer full): A #GDBusMethodInvocation.
17031 * @domain: A #GQuark for the #GError error domain.
17032 * @code: The error code.
17033 * @message: The error message.
17035 * Like g_dbus_method_invocation_return_error() but without printf()-style formatting.
17037 * This method will free @invocation, you cannot use it afterwards.
17044 * g_dbus_method_invocation_return_error_valist:
17045 * @invocation: (transfer full): A #GDBusMethodInvocation.
17046 * @domain: A #GQuark for the #GError error domain.
17047 * @code: The error code.
17048 * @format: printf()-style format.
17049 * @var_args: #va_list of parameters for @format.
17051 * Like g_dbus_method_invocation_return_error() but intended for
17052 * language bindings.
17054 * This method will free @invocation, you cannot use it afterwards.
17061 * g_dbus_method_invocation_return_gerror:
17062 * @invocation: (transfer full): A #GDBusMethodInvocation.
17063 * @error: A #GError.
17065 * Like g_dbus_method_invocation_return_error() but takes a #GError
17066 * instead of the error domain, error code and message.
17068 * This method will free @invocation, you cannot use it afterwards.
17075 * g_dbus_method_invocation_return_value:
17076 * @invocation: (transfer full): A #GDBusMethodInvocation.
17077 * @parameters: (allow-none): A #GVariant tuple with out parameters for the method or %NULL if not passing any parameters.
17079 * Finishes handling a D-Bus method call by returning @parameters.
17080 * If the @parameters GVariant is floating, it is consumed.
17082 * It is an error if @parameters is not of the right format.
17084 * This method will free @invocation, you cannot use it afterwards.
17091 * g_dbus_method_invocation_return_value_with_unix_fd_list:
17092 * @invocation: (transfer full): A #GDBusMethodInvocation.
17093 * @parameters: (allow-none): A #GVariant tuple with out parameters for the method or %NULL if not passing any parameters.
17094 * @fd_list: (allow-none): A #GUnixFDList or %NULL.
17096 * Like g_dbus_method_invocation_return_value() but also takes a #GUnixFDList.
17098 * This method is only available on UNIX.
17100 * This method will free @invocation, you cannot use it afterwards.
17107 * g_dbus_method_invocation_take_error: (skip)
17108 * @invocation: (transfer full): A #GDBusMethodInvocation.
17109 * @error: (transfer full): A #GError.
17111 * Like g_dbus_method_invocation_return_gerror() but takes ownership
17112 * of @error so the caller does not need to free it.
17114 * This method will free @invocation, you cannot use it afterwards.
17121 * g_dbus_node_info_generate_xml:
17122 * @info: A #GDBusNodeInfo.
17123 * @indent: Indentation level.
17124 * @string_builder: (out): A #GString to to append XML data to.
17126 * Appends an XML representation of @info (and its children) to @string_builder.
17128 * This function is typically used for generating introspection XML documents at run-time for
17129 * handling the `org.freedesktop.DBus.Introspectable.Introspect` method.
17136 * g_dbus_node_info_lookup_interface:
17137 * @info: A #GDBusNodeInfo.
17138 * @name: A D-Bus interface name.
17140 * Looks up information about an interface.
17142 * The cost of this function is O(n) in number of interfaces.
17144 * Returns: (transfer none): A #GDBusInterfaceInfo or %NULL if not found. Do not free, it is owned by @info.
17150 * g_dbus_node_info_new_for_xml:
17151 * @xml_data: Valid D-Bus introspection XML.
17152 * @error: Return location for error.
17154 * Parses @xml_data and returns a #GDBusNodeInfo representing the data.
17156 * The introspection XML must contain exactly one top-level
17159 * Note that this routine is using a
17160 * [GMarkup][glib-Simple-XML-Subset-Parser.description]-based
17161 * parser that only accepts a subset of valid XML documents.
17163 * Returns: A #GDBusNodeInfo structure or %NULL if @error is set. Free
17164 * with g_dbus_node_info_unref().
17170 * g_dbus_node_info_ref:
17171 * @info: A #GDBusNodeInfo
17173 * If @info is statically allocated does nothing. Otherwise increases
17174 * the reference count.
17176 * Returns: The same @info.
17182 * g_dbus_node_info_unref:
17183 * @info: A #GDBusNodeInfo.
17185 * If @info is statically allocated, does nothing. Otherwise decreases
17186 * the reference count of @info. When its reference count drops to 0,
17187 * the memory used is freed.
17194 * g_dbus_object_get_interface:
17195 * @object: A #GDBusObject.
17196 * @interface_name: A D-Bus interface name.
17198 * Gets the D-Bus interface with name @interface_name associated with
17201 * Returns: (transfer full): %NULL if not found, otherwise a
17202 * #GDBusInterface that must be freed with g_object_unref().
17208 * g_dbus_object_get_interfaces:
17209 * @object: A #GDBusObject.
17211 * Gets the D-Bus interfaces associated with @object.
17213 * Returns: (element-type GDBusInterface) (transfer full): A list of #GDBusInterface instances.
17214 * The returned list must be freed by g_list_free() after each element has been freed
17215 * with g_object_unref().
17221 * g_dbus_object_get_object_path:
17222 * @object: A #GDBusObject.
17224 * Gets the object path for @object.
17226 * Returns: A string owned by @object. Do not free.
17232 * g_dbus_object_manager_client_get_connection:
17233 * @manager: A #GDBusObjectManagerClient
17235 * Gets the #GDBusConnection used by @manager.
17237 * Returns: (transfer none): A #GDBusConnection object. Do not free,
17238 * the object belongs to @manager.
17244 * g_dbus_object_manager_client_get_flags:
17245 * @manager: A #GDBusObjectManagerClient
17247 * Gets the flags that @manager was constructed with.
17249 * Returns: Zero of more flags from the #GDBusObjectManagerClientFlags
17256 * g_dbus_object_manager_client_get_name:
17257 * @manager: A #GDBusObjectManagerClient
17259 * Gets the name that @manager is for, or %NULL if not a message bus
17262 * Returns: A unique or well-known name. Do not free, the string
17263 * belongs to @manager.
17269 * g_dbus_object_manager_client_get_name_owner:
17270 * @manager: A #GDBusObjectManagerClient.
17272 * The unique name that owns the name that @manager is for or %NULL if
17273 * no-one currently owns that name. You can connect to the
17274 * #GObject::notify signal to track changes to the
17275 * #GDBusObjectManagerClient:name-owner property.
17277 * Returns: (nullable): The name owner or %NULL if no name owner
17278 * exists. Free with g_free().
17284 * g_dbus_object_manager_client_new:
17285 * @connection: A #GDBusConnection.
17286 * @flags: Zero or more flags from the #GDBusObjectManagerClientFlags enumeration.
17287 * @name: The owner of the control object (unique or well-known name).
17288 * @object_path: The object path of the control object.
17289 * @get_proxy_type_func: (allow-none): A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies.
17290 * @get_proxy_type_user_data: User data to pass to @get_proxy_type_func.
17291 * @get_proxy_type_destroy_notify: (allow-none): Free function for @get_proxy_type_user_data or %NULL.
17292 * @cancellable: (allow-none): A #GCancellable or %NULL
17293 * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
17294 * @user_data: The data to pass to @callback.
17296 * Asynchronously creates a new #GDBusObjectManagerClient object.
17298 * This is an asynchronous failable constructor. When the result is
17299 * ready, @callback will be invoked in the
17300 * [thread-default main context][g-main-context-push-thread-default]
17301 * of the thread you are calling this method from. You can
17302 * then call g_dbus_object_manager_client_new_finish() to get the result. See
17303 * g_dbus_object_manager_client_new_sync() for the synchronous version.
17310 * g_dbus_object_manager_client_new_finish:
17311 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_object_manager_client_new().
17312 * @error: Return location for error or %NULL.
17314 * Finishes an operation started with g_dbus_object_manager_client_new().
17316 * Returns: (transfer full) (type GDBusObjectManagerClient): A
17317 * #GDBusObjectManagerClient object or %NULL if @error is set. Free
17318 * with g_object_unref().
17324 * g_dbus_object_manager_client_new_for_bus:
17325 * @bus_type: A #GBusType.
17326 * @flags: Zero or more flags from the #GDBusObjectManagerClientFlags enumeration.
17327 * @name: The owner of the control object (unique or well-known name).
17328 * @object_path: The object path of the control object.
17329 * @get_proxy_type_func: (allow-none): A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies.
17330 * @get_proxy_type_user_data: User data to pass to @get_proxy_type_func.
17331 * @get_proxy_type_destroy_notify: (allow-none): Free function for @get_proxy_type_user_data or %NULL.
17332 * @cancellable: (allow-none): A #GCancellable or %NULL
17333 * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
17334 * @user_data: The data to pass to @callback.
17336 * Like g_dbus_object_manager_client_new() but takes a #GBusType instead of a
17337 * #GDBusConnection.
17339 * This is an asynchronous failable constructor. When the result is
17340 * ready, @callback will be invoked in the
17341 * [thread-default main loop][g-main-context-push-thread-default]
17342 * of the thread you are calling this method from. You can
17343 * then call g_dbus_object_manager_client_new_for_bus_finish() to get the result. See
17344 * g_dbus_object_manager_client_new_for_bus_sync() for the synchronous version.
17351 * g_dbus_object_manager_client_new_for_bus_finish:
17352 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_object_manager_client_new_for_bus().
17353 * @error: Return location for error or %NULL.
17355 * Finishes an operation started with g_dbus_object_manager_client_new_for_bus().
17357 * Returns: (transfer full) (type GDBusObjectManagerClient): A
17358 * #GDBusObjectManagerClient object or %NULL if @error is set. Free
17359 * with g_object_unref().
17365 * g_dbus_object_manager_client_new_for_bus_sync:
17366 * @bus_type: A #GBusType.
17367 * @flags: Zero or more flags from the #GDBusObjectManagerClientFlags enumeration.
17368 * @name: The owner of the control object (unique or well-known name).
17369 * @object_path: The object path of the control object.
17370 * @get_proxy_type_func: (allow-none): A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies.
17371 * @get_proxy_type_user_data: User data to pass to @get_proxy_type_func.
17372 * @get_proxy_type_destroy_notify: (allow-none): Free function for @get_proxy_type_user_data or %NULL.
17373 * @cancellable: (allow-none): A #GCancellable or %NULL
17374 * @error: Return location for error or %NULL.
17376 * Like g_dbus_object_manager_client_new_sync() but takes a #GBusType instead
17377 * of a #GDBusConnection.
17379 * This is a synchronous failable constructor - the calling thread is
17380 * blocked until a reply is received. See g_dbus_object_manager_client_new_for_bus()
17381 * for the asynchronous version.
17383 * Returns: (transfer full) (type GDBusObjectManagerClient): A
17384 * #GDBusObjectManagerClient object or %NULL if @error is set. Free
17385 * with g_object_unref().
17391 * g_dbus_object_manager_client_new_sync:
17392 * @connection: A #GDBusConnection.
17393 * @flags: Zero or more flags from the #GDBusObjectManagerClientFlags enumeration.
17394 * @name: (allow-none): The owner of the control object (unique or well-known name), or %NULL when not using a message bus connection.
17395 * @object_path: The object path of the control object.
17396 * @get_proxy_type_func: (allow-none): A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies.
17397 * @get_proxy_type_user_data: User data to pass to @get_proxy_type_func.
17398 * @get_proxy_type_destroy_notify: (allow-none): Free function for @get_proxy_type_user_data or %NULL.
17399 * @cancellable: (allow-none): A #GCancellable or %NULL
17400 * @error: Return location for error or %NULL.
17402 * Creates a new #GDBusObjectManagerClient object.
17404 * This is a synchronous failable constructor - the calling thread is
17405 * blocked until a reply is received. See g_dbus_object_manager_client_new()
17406 * for the asynchronous version.
17408 * Returns: (transfer full) (type GDBusObjectManagerClient): A
17409 * #GDBusObjectManagerClient object or %NULL if @error is set. Free
17410 * with g_object_unref().
17416 * g_dbus_object_manager_get_interface:
17417 * @manager: A #GDBusObjectManager.
17418 * @object_path: Object path to lookup.
17419 * @interface_name: D-Bus interface name to lookup.
17421 * Gets the interface proxy for @interface_name at @object_path, if
17424 * Returns: (transfer full): A #GDBusInterface instance or %NULL. Free
17425 * with g_object_unref().
17431 * g_dbus_object_manager_get_object:
17432 * @manager: A #GDBusObjectManager.
17433 * @object_path: Object path to lookup.
17435 * Gets the #GDBusObjectProxy at @object_path, if any.
17437 * Returns: (transfer full): A #GDBusObject or %NULL. Free with
17438 * g_object_unref().
17444 * g_dbus_object_manager_get_object_path:
17445 * @manager: A #GDBusObjectManager.
17447 * Gets the object path that @manager is for.
17449 * Returns: A string owned by @manager. Do not free.
17455 * g_dbus_object_manager_get_objects:
17456 * @manager: A #GDBusObjectManager.
17458 * Gets all #GDBusObject objects known to @manager.
17460 * Returns: (transfer full) (element-type GDBusObject): A list of
17461 * #GDBusObject objects. The returned list should be freed with
17462 * g_list_free() after each element has been freed with
17463 * g_object_unref().
17469 * g_dbus_object_manager_server_export:
17470 * @manager: A #GDBusObjectManagerServer.
17471 * @object: A #GDBusObjectSkeleton.
17473 * Exports @object on @manager.
17475 * If there is already a #GDBusObject exported at the object path,
17476 * then the old object is removed.
17478 * The object path for @object must be in the hierarchy rooted by the
17479 * object path for @manager.
17481 * Note that @manager will take a reference on @object for as long as
17489 * g_dbus_object_manager_server_export_uniquely:
17490 * @manager: A #GDBusObjectManagerServer.
17491 * @object: An object.
17493 * Like g_dbus_object_manager_server_export() but appends a string of
17494 * the form _N (with N being a natural number) to @object's object path
17495 * if an object with the given path already exists. As such, the
17496 * #GDBusObjectProxy:g-object-path property of @object may be modified.
17503 * g_dbus_object_manager_server_get_connection:
17504 * @manager: A #GDBusObjectManagerServer
17506 * Gets the #GDBusConnection used by @manager.
17508 * Returns: (transfer full): A #GDBusConnection object or %NULL if
17509 * @manager isn't exported on a connection. The returned object should
17510 * be freed with g_object_unref().
17516 * g_dbus_object_manager_server_is_exported:
17517 * @manager: A #GDBusObjectManagerServer.
17518 * @object: An object.
17520 * Returns whether @object is currently exported on @manager.
17522 * Returns: %TRUE if @object is exported
17528 * g_dbus_object_manager_server_new:
17529 * @object_path: The object path to export the manager object at.
17531 * Creates a new #GDBusObjectManagerServer object.
17533 * The returned server isn't yet exported on any connection. To do so,
17534 * use g_dbus_object_manager_server_set_connection(). Normally you
17535 * want to export all of your objects before doing so to avoid <ulink
17536 * url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager">InterfacesAdded</ulink>
17537 * signals being emitted.
17539 * Returns: A #GDBusObjectManagerServer object. Free with g_object_unref().
17545 * g_dbus_object_manager_server_set_connection:
17546 * @manager: A #GDBusObjectManagerServer.
17547 * @connection: (allow-none): A #GDBusConnection or %NULL.
17549 * Exports all objects managed by @manager on @connection. If
17550 * @connection is %NULL, stops exporting objects.
17555 * g_dbus_object_manager_server_unexport:
17556 * @manager: A #GDBusObjectManagerServer.
17557 * @object_path: An object path.
17559 * If @manager has an object at @path, removes the object. Otherwise
17562 * Note that @object_path must be in the hierarchy rooted by the
17563 * object path for @manager.
17565 * Returns: %TRUE if object at @object_path was removed, %FALSE otherwise.
17571 * g_dbus_object_proxy_get_connection:
17572 * @proxy: a #GDBusObjectProxy
17574 * Gets the connection that @proxy is for.
17576 * Returns: (transfer none): A #GDBusConnection. Do not free, the
17577 * object is owned by @proxy.
17583 * g_dbus_object_proxy_new:
17584 * @connection: a #GDBusConnection
17585 * @object_path: the object path
17587 * Creates a new #GDBusObjectProxy for the given connection and
17590 * Returns: a new #GDBusObjectProxy
17596 * g_dbus_object_skeleton_add_interface:
17597 * @object: A #GDBusObjectSkeleton.
17598 * @interface_: A #GDBusInterfaceSkeleton.
17600 * Adds @interface_ to @object.
17602 * If @object already contains a #GDBusInterfaceSkeleton with the same
17603 * interface name, it is removed before @interface_ is added.
17605 * Note that @object takes its own reference on @interface_ and holds
17606 * it until removed.
17613 * g_dbus_object_skeleton_flush:
17614 * @object: A #GDBusObjectSkeleton.
17616 * This method simply calls g_dbus_interface_skeleton_flush() on all
17617 * interfaces belonging to @object. See that method for when flushing
17625 * g_dbus_object_skeleton_new:
17626 * @object_path: An object path.
17628 * Creates a new #GDBusObjectSkeleton.
17630 * Returns: A #GDBusObjectSkeleton. Free with g_object_unref().
17636 * g_dbus_object_skeleton_remove_interface:
17637 * @object: A #GDBusObjectSkeleton.
17638 * @interface_: A #GDBusInterfaceSkeleton.
17640 * Removes @interface_ from @object.
17647 * g_dbus_object_skeleton_remove_interface_by_name:
17648 * @object: A #GDBusObjectSkeleton.
17649 * @interface_name: A D-Bus interface name.
17651 * Removes the #GDBusInterface with @interface_name from @object.
17653 * If no D-Bus interface of the given interface exists, this function
17661 * g_dbus_object_skeleton_set_object_path:
17662 * @object: A #GDBusObjectSkeleton.
17663 * @object_path: A valid D-Bus object path.
17665 * Sets the object path for @object.
17672 * g_dbus_property_info_ref:
17673 * @info: A #GDBusPropertyInfo
17675 * If @info is statically allocated does nothing. Otherwise increases
17676 * the reference count.
17678 * Returns: The same @info.
17684 * g_dbus_property_info_unref:
17685 * @info: A #GDBusPropertyInfo.
17687 * If @info is statically allocated, does nothing. Otherwise decreases
17688 * the reference count of @info. When its reference count drops to 0,
17689 * the memory used is freed.
17696 * g_dbus_proxy_call:
17697 * @proxy: A #GDBusProxy.
17698 * @method_name: Name of method to invoke.
17699 * @parameters: (allow-none): A #GVariant tuple with parameters for the signal or %NULL if not passing parameters.
17700 * @flags: Flags from the #GDBusCallFlags enumeration.
17701 * @timeout_msec: The timeout in milliseconds (with %G_MAXINT meaning
17702 * "infinite") or -1 to use the proxy default timeout.
17703 * @cancellable: (allow-none): A #GCancellable or %NULL.
17704 * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't
17705 * care about the result of the method invocation.
17706 * @user_data: The data to pass to @callback.
17708 * Asynchronously invokes the @method_name method on @proxy.
17710 * If @method_name contains any dots, then @name is split into interface and
17711 * method name parts. This allows using @proxy for invoking methods on
17712 * other interfaces.
17714 * If the #GDBusConnection associated with @proxy is closed then
17715 * the operation will fail with %G_IO_ERROR_CLOSED. If
17716 * @cancellable is canceled, the operation will fail with
17717 * %G_IO_ERROR_CANCELLED. If @parameters contains a value not
17718 * compatible with the D-Bus protocol, the operation fails with
17719 * %G_IO_ERROR_INVALID_ARGUMENT.
17721 * If the @parameters #GVariant is floating, it is consumed. This allows
17722 * convenient 'inline' use of g_variant_new(), e.g.:
17723 * |[<!-- language="C" -->
17724 * g_dbus_proxy_call (proxy,
17726 * g_variant_new ("(ss)",
17729 * G_DBUS_CALL_FLAGS_NONE,
17732 * (GAsyncReadyCallback) two_strings_done,
17736 * If @proxy has an expected interface (see
17737 * #GDBusProxy:g-interface-info) and @method_name is referenced by it,
17738 * then the return value is checked against the return type.
17740 * This is an asynchronous method. When the operation is finished,
17741 * @callback will be invoked in the
17742 * [thread-default main context][g-main-context-push-thread-default]
17743 * of the thread you are calling this method from.
17744 * You can then call g_dbus_proxy_call_finish() to get the result of
17745 * the operation. See g_dbus_proxy_call_sync() for the synchronous
17746 * version of this method.
17748 * If @callback is %NULL then the D-Bus method call message will be sent with
17749 * the %G_DBUS_MESSAGE_FLAGS_NO_REPLY_EXPECTED flag set.
17756 * g_dbus_proxy_call_finish:
17757 * @proxy: A #GDBusProxy.
17758 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_proxy_call().
17759 * @error: Return location for error or %NULL.
17761 * Finishes an operation started with g_dbus_proxy_call().
17763 * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
17764 * return values. Free with g_variant_unref().
17770 * g_dbus_proxy_call_sync:
17771 * @proxy: A #GDBusProxy.
17772 * @method_name: Name of method to invoke.
17773 * @parameters: (allow-none): A #GVariant tuple with parameters for the signal
17774 * or %NULL if not passing parameters.
17775 * @flags: Flags from the #GDBusCallFlags enumeration.
17776 * @timeout_msec: The timeout in milliseconds (with %G_MAXINT meaning
17777 * "infinite") or -1 to use the proxy default timeout.
17778 * @cancellable: (allow-none): A #GCancellable or %NULL.
17779 * @error: Return location for error or %NULL.
17781 * Synchronously invokes the @method_name method on @proxy.
17783 * If @method_name contains any dots, then @name is split into interface and
17784 * method name parts. This allows using @proxy for invoking methods on
17785 * other interfaces.
17787 * If the #GDBusConnection associated with @proxy is disconnected then
17788 * the operation will fail with %G_IO_ERROR_CLOSED. If
17789 * @cancellable is canceled, the operation will fail with
17790 * %G_IO_ERROR_CANCELLED. If @parameters contains a value not
17791 * compatible with the D-Bus protocol, the operation fails with
17792 * %G_IO_ERROR_INVALID_ARGUMENT.
17794 * If the @parameters #GVariant is floating, it is consumed. This allows
17795 * convenient 'inline' use of g_variant_new(), e.g.:
17796 * |[<!-- language="C" -->
17797 * g_dbus_proxy_call_sync (proxy,
17799 * g_variant_new ("(ss)",
17802 * G_DBUS_CALL_FLAGS_NONE,
17808 * The calling thread is blocked until a reply is received. See
17809 * g_dbus_proxy_call() for the asynchronous version of this
17812 * If @proxy has an expected interface (see
17813 * #GDBusProxy:g-interface-info) and @method_name is referenced by it,
17814 * then the return value is checked against the return type.
17816 * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
17817 * return values. Free with g_variant_unref().
17823 * g_dbus_proxy_call_with_unix_fd_list:
17824 * @proxy: A #GDBusProxy.
17825 * @method_name: Name of method to invoke.
17826 * @parameters: (allow-none): A #GVariant tuple with parameters for the signal or %NULL if not passing parameters.
17827 * @flags: Flags from the #GDBusCallFlags enumeration.
17828 * @timeout_msec: The timeout in milliseconds (with %G_MAXINT meaning
17829 * "infinite") or -1 to use the proxy default timeout.
17830 * @fd_list: (allow-none): A #GUnixFDList or %NULL.
17831 * @cancellable: (allow-none): A #GCancellable or %NULL.
17832 * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't
17833 * care about the result of the method invocation.
17834 * @user_data: The data to pass to @callback.
17836 * Like g_dbus_proxy_call() but also takes a #GUnixFDList object.
17838 * This method is only available on UNIX.
17845 * g_dbus_proxy_call_with_unix_fd_list_finish:
17846 * @proxy: A #GDBusProxy.
17847 * @out_fd_list: (out) (allow-none): Return location for a #GUnixFDList or %NULL.
17848 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_proxy_call_with_unix_fd_list().
17849 * @error: Return location for error or %NULL.
17851 * Finishes an operation started with g_dbus_proxy_call_with_unix_fd_list().
17853 * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
17854 * return values. Free with g_variant_unref().
17860 * g_dbus_proxy_call_with_unix_fd_list_sync:
17861 * @proxy: A #GDBusProxy.
17862 * @method_name: Name of method to invoke.
17863 * @parameters: (allow-none): A #GVariant tuple with parameters for the signal
17864 * or %NULL if not passing parameters.
17865 * @flags: Flags from the #GDBusCallFlags enumeration.
17866 * @timeout_msec: The timeout in milliseconds (with %G_MAXINT meaning
17867 * "infinite") or -1 to use the proxy default timeout.
17868 * @fd_list: (allow-none): A #GUnixFDList or %NULL.
17869 * @out_fd_list: (out) (allow-none): Return location for a #GUnixFDList or %NULL.
17870 * @cancellable: (allow-none): A #GCancellable or %NULL.
17871 * @error: Return location for error or %NULL.
17873 * Like g_dbus_proxy_call_sync() but also takes and returns #GUnixFDList objects.
17875 * This method is only available on UNIX.
17877 * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
17878 * return values. Free with g_variant_unref().
17884 * g_dbus_proxy_get_cached_property:
17885 * @proxy: A #GDBusProxy.
17886 * @property_name: Property name.
17888 * Looks up the value for a property from the cache. This call does no
17891 * If @proxy has an expected interface (see
17892 * #GDBusProxy:g-interface-info) and @property_name is referenced by
17893 * it, then @value is checked against the type of the property.
17895 * Returns: A reference to the #GVariant instance that holds the value
17896 * for @property_name or %NULL if the value is not in the cache. The
17897 * returned reference must be freed with g_variant_unref().
17903 * g_dbus_proxy_get_cached_property_names:
17904 * @proxy: A #GDBusProxy.
17906 * Gets the names of all cached properties on @proxy.
17908 * Returns: (transfer full): A %NULL-terminated array of strings or %NULL if
17909 * @proxy has no cached properties. Free the returned array with
17916 * g_dbus_proxy_get_connection:
17917 * @proxy: A #GDBusProxy.
17919 * Gets the connection @proxy is for.
17921 * Returns: (transfer none): A #GDBusConnection owned by @proxy. Do not free.
17927 * g_dbus_proxy_get_default_timeout:
17928 * @proxy: A #GDBusProxy.
17930 * Gets the timeout to use if -1 (specifying default timeout) is
17931 * passed as @timeout_msec in the g_dbus_proxy_call() and
17932 * g_dbus_proxy_call_sync() functions.
17934 * See the #GDBusProxy:g-default-timeout property for more details.
17936 * Returns: Timeout to use for @proxy.
17942 * g_dbus_proxy_get_flags:
17943 * @proxy: A #GDBusProxy.
17945 * Gets the flags that @proxy was constructed with.
17947 * Returns: Flags from the #GDBusProxyFlags enumeration.
17953 * g_dbus_proxy_get_interface_info:
17954 * @proxy: A #GDBusProxy
17956 * Returns the #GDBusInterfaceInfo, if any, specifying the interface
17957 * that @proxy conforms to. See the #GDBusProxy:g-interface-info
17958 * property for more details.
17960 * Returns: A #GDBusInterfaceInfo or %NULL. Do not unref the returned
17961 * object, it is owned by @proxy.
17967 * g_dbus_proxy_get_interface_name:
17968 * @proxy: A #GDBusProxy.
17970 * Gets the D-Bus interface name @proxy is for.
17972 * Returns: A string owned by @proxy. Do not free.
17978 * g_dbus_proxy_get_name:
17979 * @proxy: A #GDBusProxy.
17981 * Gets the name that @proxy was constructed for.
17983 * Returns: A string owned by @proxy. Do not free.
17989 * g_dbus_proxy_get_name_owner:
17990 * @proxy: A #GDBusProxy.
17992 * The unique name that owns the name that @proxy is for or %NULL if
17993 * no-one currently owns that name. You may connect to the
17994 * #GObject::notify signal to track changes to the
17995 * #GDBusProxy:g-name-owner property.
17997 * Returns: The name owner or %NULL if no name owner exists. Free with g_free().
18003 * g_dbus_proxy_get_object_path:
18004 * @proxy: A #GDBusProxy.
18006 * Gets the object path @proxy is for.
18008 * Returns: A string owned by @proxy. Do not free.
18014 * g_dbus_proxy_new:
18015 * @connection: A #GDBusConnection.
18016 * @flags: Flags used when constructing the proxy.
18017 * @info: (allow-none): A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL.
18018 * @name: (allow-none): A bus name (well-known or unique) or %NULL if @connection is not a message bus connection.
18019 * @object_path: An object path.
18020 * @interface_name: A D-Bus interface name.
18021 * @cancellable: (allow-none): A #GCancellable or %NULL.
18022 * @callback: Callback function to invoke when the proxy is ready.
18023 * @user_data: User data to pass to @callback.
18025 * Creates a proxy for accessing @interface_name on the remote object
18026 * at @object_path owned by @name at @connection and asynchronously
18027 * loads D-Bus properties unless the
18028 * %G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES flag is used. Connect to
18029 * the #GDBusProxy::g-properties-changed signal to get notified about
18030 * property changes.
18032 * If the %G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS flag is not set, also sets up
18033 * match rules for signals. Connect to the #GDBusProxy::g-signal signal
18034 * to handle signals from the remote object.
18036 * If @name is a well-known name and the
18037 * %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START and %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START_AT_CONSTRUCTION
18038 * flags aren't set and no name owner currently exists, the message bus
18039 * will be requested to launch a name owner for the name.
18041 * This is a failable asynchronous constructor - when the proxy is
18042 * ready, @callback will be invoked and you can use
18043 * g_dbus_proxy_new_finish() to get the result.
18045 * See g_dbus_proxy_new_sync() and for a synchronous version of this constructor.
18047 * #GDBusProxy is used in this [example][gdbus-wellknown-proxy].
18054 * g_dbus_proxy_new_finish:
18055 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback function passed to g_dbus_proxy_new().
18056 * @error: Return location for error or %NULL.
18058 * Finishes creating a #GDBusProxy.
18060 * Returns: A #GDBusProxy or %NULL if @error is set. Free with g_object_unref().
18066 * g_dbus_proxy_new_for_bus:
18067 * @bus_type: A #GBusType.
18068 * @flags: Flags used when constructing the proxy.
18069 * @info: (allow-none): A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL.
18070 * @name: A bus name (well-known or unique).
18071 * @object_path: An object path.
18072 * @interface_name: A D-Bus interface name.
18073 * @cancellable: (allow-none): A #GCancellable or %NULL.
18074 * @callback: Callback function to invoke when the proxy is ready.
18075 * @user_data: User data to pass to @callback.
18077 * Like g_dbus_proxy_new() but takes a #GBusType instead of a #GDBusConnection.
18079 * #GDBusProxy is used in this [example][gdbus-wellknown-proxy].
18086 * g_dbus_proxy_new_for_bus_finish:
18087 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback function passed to g_dbus_proxy_new_for_bus().
18088 * @error: Return location for error or %NULL.
18090 * Finishes creating a #GDBusProxy.
18092 * Returns: A #GDBusProxy or %NULL if @error is set. Free with g_object_unref().
18098 * g_dbus_proxy_new_for_bus_sync:
18099 * @bus_type: A #GBusType.
18100 * @flags: Flags used when constructing the proxy.
18101 * @info: (allow-none): A #GDBusInterfaceInfo specifying the minimal interface
18102 * that @proxy conforms to or %NULL.
18103 * @name: A bus name (well-known or unique).
18104 * @object_path: An object path.
18105 * @interface_name: A D-Bus interface name.
18106 * @cancellable: (allow-none): A #GCancellable or %NULL.
18107 * @error: Return location for error or %NULL.
18109 * Like g_dbus_proxy_new_sync() but takes a #GBusType instead of a #GDBusConnection.
18111 * #GDBusProxy is used in this [example][gdbus-wellknown-proxy].
18113 * Returns: A #GDBusProxy or %NULL if error is set. Free with g_object_unref().
18119 * g_dbus_proxy_new_sync:
18120 * @connection: A #GDBusConnection.
18121 * @flags: Flags used when constructing the proxy.
18122 * @info: (allow-none): A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL.
18123 * @name: (allow-none): A bus name (well-known or unique) or %NULL if @connection is not a message bus connection.
18124 * @object_path: An object path.
18125 * @interface_name: A D-Bus interface name.
18126 * @cancellable: (allow-none): A #GCancellable or %NULL.
18127 * @error: (allow-none): Return location for error or %NULL.
18129 * Creates a proxy for accessing @interface_name on the remote object
18130 * at @object_path owned by @name at @connection and synchronously
18131 * loads D-Bus properties unless the
18132 * %G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES flag is used.
18134 * If the %G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS flag is not set, also sets up
18135 * match rules for signals. Connect to the #GDBusProxy::g-signal signal
18136 * to handle signals from the remote object.
18138 * If @name is a well-known name and the
18139 * %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START and %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START_AT_CONSTRUCTION
18140 * flags aren't set and no name owner currently exists, the message bus
18141 * will be requested to launch a name owner for the name.
18143 * This is a synchronous failable constructor. See g_dbus_proxy_new()
18144 * and g_dbus_proxy_new_finish() for the asynchronous version.
18146 * #GDBusProxy is used in this [example][gdbus-wellknown-proxy].
18148 * Returns: A #GDBusProxy or %NULL if error is set. Free with g_object_unref().
18154 * g_dbus_proxy_set_cached_property:
18155 * @proxy: A #GDBusProxy
18156 * @property_name: Property name.
18157 * @value: (allow-none): Value for the property or %NULL to remove it from the cache.
18159 * If @value is not %NULL, sets the cached value for the property with
18160 * name @property_name to the value in @value.
18162 * If @value is %NULL, then the cached value is removed from the
18165 * If @proxy has an expected interface (see
18166 * #GDBusProxy:g-interface-info) and @property_name is referenced by
18167 * it, then @value is checked against the type of the property.
18169 * If the @value #GVariant is floating, it is consumed. This allows
18170 * convenient 'inline' use of g_variant_new(), e.g.
18171 * |[<!-- language="C" -->
18172 * g_dbus_proxy_set_cached_property (proxy,
18174 * g_variant_new ("(si)",
18179 * Normally you will not need to use this method since @proxy
18180 * is tracking changes using the
18181 * `org.freedesktop.DBus.Properties.PropertiesChanged`
18182 * D-Bus signal. However, for performance reasons an object may
18183 * decide to not use this signal for some properties and instead
18184 * use a proprietary out-of-band mechanism to transmit changes.
18186 * As a concrete example, consider an object with a property
18187 * `ChatroomParticipants` which is an array of strings. Instead of
18188 * transmitting the same (long) array every time the property changes,
18189 * it is more efficient to only transmit the delta using e.g. signals
18190 * `ChatroomParticipantJoined(String name)` and
18191 * `ChatroomParticipantParted(String name)`.
18198 * g_dbus_proxy_set_default_timeout:
18199 * @proxy: A #GDBusProxy.
18200 * @timeout_msec: Timeout in milliseconds.
18202 * Sets the timeout to use if -1 (specifying default timeout) is
18203 * passed as @timeout_msec in the g_dbus_proxy_call() and
18204 * g_dbus_proxy_call_sync() functions.
18206 * See the #GDBusProxy:g-default-timeout property for more details.
18213 * g_dbus_proxy_set_interface_info:
18214 * @proxy: A #GDBusProxy
18215 * @info: (allow-none): Minimum interface this proxy conforms to or %NULL to unset.
18217 * Ensure that interactions with @proxy conform to the given
18218 * interface. See the #GDBusProxy:g-interface-info property for more
18226 * g_dbus_server_get_client_address:
18227 * @server: A #GDBusServer.
18229 * Gets a D-Bus address string that can be used by clients to connect
18232 * Returns: A D-Bus address string. Do not free, the string is owned
18239 * g_dbus_server_get_flags:
18240 * @server: A #GDBusServer.
18242 * Gets the flags for @server.
18244 * Returns: A set of flags from the #GDBusServerFlags enumeration.
18250 * g_dbus_server_get_guid:
18251 * @server: A #GDBusServer.
18253 * Gets the GUID for @server.
18255 * Returns: A D-Bus GUID. Do not free this string, it is owned by @server.
18261 * g_dbus_server_is_active:
18262 * @server: A #GDBusServer.
18264 * Gets whether @server is active.
18266 * Returns: %TRUE if server is active, %FALSE otherwise.
18272 * g_dbus_server_new_sync:
18273 * @address: A D-Bus address.
18274 * @flags: Flags from the #GDBusServerFlags enumeration.
18275 * @guid: A D-Bus GUID.
18276 * @observer: (allow-none): A #GDBusAuthObserver or %NULL.
18277 * @cancellable: (allow-none): A #GCancellable or %NULL.
18278 * @error: Return location for server or %NULL.
18280 * Creates a new D-Bus server that listens on the first address in
18281 * @address that works.
18283 * Once constructed, you can use g_dbus_server_get_client_address() to
18284 * get a D-Bus address string that clients can use to connect.
18286 * Connect to the #GDBusServer::new-connection signal to handle
18287 * incoming connections.
18289 * The returned #GDBusServer isn't active - you have to start it with
18290 * g_dbus_server_start().
18292 * #GDBusServer is used in this [example][gdbus-peer-to-peer].
18294 * This is a synchronous failable constructor. See
18295 * g_dbus_server_new() for the asynchronous version.
18297 * Returns: A #GDBusServer or %NULL if @error is set. Free with
18298 * g_object_unref().
18304 * g_dbus_server_start:
18305 * @server: A #GDBusServer.
18314 * g_dbus_server_stop:
18315 * @server: A #GDBusServer.
18324 * g_dbus_signal_info_ref:
18325 * @info: A #GDBusSignalInfo
18327 * If @info is statically allocated does nothing. Otherwise increases
18328 * the reference count.
18330 * Returns: The same @info.
18336 * g_dbus_signal_info_unref:
18337 * @info: A #GDBusSignalInfo.
18339 * If @info is statically allocated, does nothing. Otherwise decreases
18340 * the reference count of @info. When its reference count drops to 0,
18341 * the memory used is freed.
18348 * g_desktop_app_info_get_action_name:
18349 * @info: a #GDesktopAppInfo
18350 * @action_name: the name of the action as from
18351 * g_desktop_app_info_list_actions()
18353 * Gets the user-visible display name of the "additional application
18354 * action" specified by @action_name.
18356 * This corresponds to the "Name" key within the keyfile group for the
18359 * Returns: (transfer full): the locale-specific action name
18365 * g_desktop_app_info_get_boolean:
18366 * @info: a #GDesktopAppInfo
18367 * @key: the key to look up
18369 * Looks up a boolean value in the keyfile backing @info.
18371 * The @key is looked up in the "Desktop Entry" group.
18373 * Returns: the boolean value, or %FALSE if the key
18380 * g_desktop_app_info_get_categories:
18381 * @info: a #GDesktopAppInfo
18383 * Gets the categories from the desktop file.
18385 * Returns: The unparsed Categories key from the desktop file;
18386 * i.e. no attempt is made to split it by ';' or validate it.
18391 * g_desktop_app_info_get_filename:
18392 * @info: a #GDesktopAppInfo
18394 * When @info was created from a known filename, return it. In some
18395 * situations such as the #GDesktopAppInfo returned from
18396 * g_desktop_app_info_new_from_keyfile(), this function will return %NULL.
18398 * Returns: The full path to the file for @info, or %NULL if not known.
18404 * g_desktop_app_info_get_generic_name:
18405 * @info: a #GDesktopAppInfo
18407 * Gets the generic name from the destkop file.
18409 * Returns: The value of the GenericName key
18414 * g_desktop_app_info_get_implementations:
18415 * @interface: the name of the interface
18417 * Gets all applications that implement @interface.
18419 * An application implements an interface if that interface is listed in
18420 * the Implements= line of the desktop file of the application.
18427 * g_desktop_app_info_get_is_hidden:
18428 * @info: a #GDesktopAppInfo.
18430 * A desktop file is hidden if the Hidden key in it is
18433 * Returns: %TRUE if hidden, %FALSE otherwise.
18438 * g_desktop_app_info_get_keywords:
18439 * @info: a #GDesktopAppInfo
18441 * Gets the keywords from the desktop file.
18443 * Returns: (transfer none): The value of the Keywords key
18449 * g_desktop_app_info_get_nodisplay:
18450 * @info: a #GDesktopAppInfo
18452 * Gets the value of the NoDisplay key, which helps determine if the
18453 * application info should be shown in menus. See
18454 * #G_KEY_FILE_DESKTOP_KEY_NO_DISPLAY and g_app_info_should_show().
18456 * Returns: The value of the NoDisplay key
18462 * g_desktop_app_info_get_show_in:
18463 * @info: a #GDesktopAppInfo
18464 * @desktop_env: (nullable): a string specifying a desktop name
18466 * Checks if the application info should be shown in menus that list available
18467 * applications for a specific name of the desktop, based on the
18468 * `OnlyShowIn` and `NotShowIn` keys.
18470 * @desktop_env should typically be given as %NULL, in which case the
18471 * `XDG_CURRENT_DESKTOP` environment variable is consulted. If you want
18472 * to override the default mechanism then you may specify @desktop_env,
18473 * but this is not recommended.
18475 * Note that g_app_info_should_show() for @info will include this check (with
18476 * %NULL for @desktop_env) as well as additional checks.
18478 * Returns: %TRUE if the @info should be shown in @desktop_env according to the
18479 * `OnlyShowIn` and `NotShowIn` keys, %FALSE
18486 * g_desktop_app_info_get_startup_wm_class:
18487 * @info: a #GDesktopAppInfo that supports startup notify
18489 * Retrieves the StartupWMClass field from @info. This represents the
18490 * WM_CLASS property of the main window of the application, if launched
18493 * Returns: (transfer none): the startup WM class, or %NULL if none is set
18494 * in the desktop file.
18500 * g_desktop_app_info_get_string:
18501 * @info: a #GDesktopAppInfo
18502 * @key: the key to look up
18504 * Looks up a string value in the keyfile backing @info.
18506 * The @key is looked up in the "Desktop Entry" group.
18508 * Returns: a newly allocated string, or %NULL if the key
18515 * g_desktop_app_info_has_key:
18516 * @info: a #GDesktopAppInfo
18517 * @key: the key to look up
18519 * Returns whether @key exists in the "Desktop Entry" group
18520 * of the keyfile backing @info.
18522 * Returns: %TRUE if the @key exists
18528 * g_desktop_app_info_launch_action:
18529 * @info: a #GDesktopAppInfo
18530 * @action_name: the name of the action as from
18531 * g_desktop_app_info_list_actions()
18532 * @launch_context: (allow-none): a #GAppLaunchContext
18534 * Activates the named application action.
18536 * You may only call this function on action names that were
18537 * returned from g_desktop_app_info_list_actions().
18539 * Note that if the main entry of the desktop file indicates that the
18540 * application supports startup notification, and @launch_context is
18541 * non-%NULL, then startup notification will be used when activating the
18542 * action (and as such, invocation of the action on the receiving side
18543 * must signal the end of startup notification when it is completed).
18544 * This is the expected behaviour of applications declaring additional
18545 * actions, as per the desktop file specification.
18547 * As with g_app_info_launch() there is no way to detect failures that
18548 * occur while using this function.
18555 * g_desktop_app_info_launch_uris_as_manager:
18556 * @appinfo: a #GDesktopAppInfo
18557 * @uris: (element-type utf8): List of URIs
18558 * @launch_context: (allow-none): a #GAppLaunchContext
18559 * @spawn_flags: #GSpawnFlags, used for each process
18560 * @user_setup: (scope call) (allow-none): a #GSpawnChildSetupFunc, used once
18561 * for each process.
18562 * @user_setup_data: (closure user_setup) (allow-none): User data for @user_setup
18563 * @pid_callback: (scope call) (allow-none): Callback for child processes
18564 * @pid_callback_data: (closure pid_callback) (allow-none): User data for @callback
18565 * @error: return location for a #GError, or %NULL
18567 * This function performs the equivalent of g_app_info_launch_uris(),
18568 * but is intended primarily for operating system components that
18569 * launch applications. Ordinary applications should use
18570 * g_app_info_launch_uris().
18572 * If the application is launched via traditional UNIX fork()/exec()
18573 * then @spawn_flags, @user_setup and @user_setup_data are used for the
18574 * call to g_spawn_async(). Additionally, @pid_callback (with
18575 * @pid_callback_data) will be called to inform about the PID of the
18578 * If application launching occurs via some other mechanism (eg: D-Bus
18579 * activation) then @spawn_flags, @user_setup, @user_setup_data,
18580 * @pid_callback and @pid_callback_data are ignored.
18582 * Returns: %TRUE on successful launch, %FALSE otherwise.
18587 * g_desktop_app_info_list_actions:
18588 * @info: a #GDesktopAppInfo
18590 * Returns the list of "additional application actions" supported on the
18591 * desktop file, as per the desktop file specification.
18593 * As per the specification, this is the list of actions that are
18594 * explicitly listed in the "Actions" key of the [Desktop Entry] group.
18596 * Returns: (array zero-terminated=1) (element-type utf8) (transfer none): a list of strings, always non-%NULL
18602 * g_desktop_app_info_lookup_get_default_for_uri_scheme:
18603 * @lookup: a #GDesktopAppInfoLookup
18604 * @uri_scheme: a string containing a URI scheme.
18606 * Gets the default application for launching applications
18607 * using this URI scheme for a particular GDesktopAppInfoLookup
18610 * The GDesktopAppInfoLookup interface and this function is used
18611 * to implement g_app_info_get_default_for_uri_scheme() backends
18612 * in a GIO module. There is no reason for applications to use it
18613 * directly. Applications should use g_app_info_get_default_for_uri_scheme().
18615 * Returns: (transfer full): #GAppInfo for given @uri_scheme or %NULL on error.
18616 * Deprecated: The #GDesktopAppInfoLookup interface is deprecated and unused by gio.
18621 * g_desktop_app_info_new:
18622 * @desktop_id: the desktop file id
18624 * Creates a new #GDesktopAppInfo based on a desktop file id.
18626 * A desktop file id is the basename of the desktop file, including the
18627 * .desktop extension. GIO is looking for a desktop file with this name
18628 * in the `applications` subdirectories of the XDG
18629 * data directories (i.e. the directories specified in the `XDG_DATA_HOME`
18630 * and `XDG_DATA_DIRS` environment variables). GIO also supports the
18631 * prefix-to-subdirectory mapping that is described in the
18632 * [Menu Spec](http://standards.freedesktop.org/menu-spec/latest/)
18633 * (i.e. a desktop id of kde-foo.desktop will match
18634 * `/usr/share/applications/kde/foo.desktop`).
18636 * Returns: a new #GDesktopAppInfo, or %NULL if no desktop file with that id
18641 * g_desktop_app_info_new_from_filename:
18642 * @filename: the path of a desktop file, in the GLib filename encoding
18644 * Creates a new #GDesktopAppInfo.
18646 * Returns: a new #GDesktopAppInfo or %NULL on error.
18651 * g_desktop_app_info_new_from_keyfile:
18652 * @key_file: an opened #GKeyFile
18654 * Creates a new #GDesktopAppInfo.
18656 * Returns: a new #GDesktopAppInfo or %NULL on error.
18662 * g_desktop_app_info_search:
18663 * @search_string: the search string to use
18665 * Searches desktop files for ones that match @search_string.
18667 * The return value is an array of strvs. Each strv contains a list of
18668 * applications that matched @search_string with an equal score. The
18669 * outer list is sorted by score so that the first strv contains the
18670 * best-matching applications, and so on.
18671 * The algorithm for determining matches is undefined and may change at
18674 * Returns: (array zero-terminated=1) (element-type GStrv) (transfer full): a
18675 * list of strvs. Free each item with g_strfreev() and free the outer
18676 * list with g_free().
18681 * g_desktop_app_info_set_desktop_env:
18682 * @desktop_env: a string specifying what desktop this is
18684 * Sets the name of the desktop that the application is running in.
18685 * This is used by g_app_info_should_show() and
18686 * g_desktop_app_info_get_show_in() to evaluate the
18687 * `OnlyShowIn` and `NotShowIn`
18688 * desktop entry fields.
18690 * Should be called only once; subsequent calls are ignored.
18692 * Deprecated: 2.42: do not use this API. Since 2.42 the value of the
18693 * `XDG_CURRENT_DESKTOP` environment variable will be used.
18698 * g_drive_can_eject:
18699 * @drive: a #GDrive.
18701 * Checks if a drive can be ejected.
18703 * Returns: %TRUE if the @drive can be ejected, %FALSE otherwise.
18708 * g_drive_can_poll_for_media:
18709 * @drive: a #GDrive.
18711 * Checks if a drive can be polled for media changes.
18713 * Returns: %TRUE if the @drive can be polled for media changes,
18714 * %FALSE otherwise.
18719 * g_drive_can_start:
18720 * @drive: a #GDrive.
18722 * Checks if a drive can be started.
18724 * Returns: %TRUE if the @drive can be started, %FALSE otherwise.
18730 * g_drive_can_start_degraded:
18731 * @drive: a #GDrive.
18733 * Checks if a drive can be started degraded.
18735 * Returns: %TRUE if the @drive can be started degraded, %FALSE otherwise.
18741 * g_drive_can_stop:
18742 * @drive: a #GDrive.
18744 * Checks if a drive can be stopped.
18746 * Returns: %TRUE if the @drive can be stopped, %FALSE otherwise.
18753 * @drive: a #GDrive.
18754 * @flags: flags affecting the unmount if required for eject
18755 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
18756 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
18757 * @user_data: user data to pass to @callback
18759 * Asynchronously ejects a drive.
18761 * When the operation is finished, @callback will be called.
18762 * You can then call g_drive_eject_finish() to obtain the
18763 * result of the operation.
18765 * Deprecated: 2.22: Use g_drive_eject_with_operation() instead.
18770 * g_drive_eject_finish:
18771 * @drive: a #GDrive.
18772 * @result: a #GAsyncResult.
18773 * @error: a #GError, or %NULL
18775 * Finishes ejecting a drive.
18777 * Returns: %TRUE if the drive has been ejected successfully,
18778 * %FALSE otherwise.
18779 * Deprecated: 2.22: Use g_drive_eject_with_operation_finish() instead.
18784 * g_drive_eject_with_operation:
18785 * @drive: a #GDrive.
18786 * @flags: flags affecting the unmount if required for eject
18787 * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid
18788 * user interaction.
18789 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
18790 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
18791 * @user_data: user data passed to @callback.
18793 * Ejects a drive. This is an asynchronous operation, and is
18794 * finished by calling g_drive_eject_with_operation_finish() with the @drive
18795 * and #GAsyncResult data returned in the @callback.
18802 * g_drive_eject_with_operation_finish:
18803 * @drive: a #GDrive.
18804 * @result: a #GAsyncResult.
18805 * @error: a #GError location to store the error occurring, or %NULL to
18808 * Finishes ejecting a drive. If any errors occurred during the operation,
18809 * @error will be set to contain the errors and %FALSE will be returned.
18811 * Returns: %TRUE if the drive was successfully ejected. %FALSE otherwise.
18817 * g_drive_enumerate_identifiers:
18818 * @drive: a #GDrive
18820 * Gets the kinds of identifiers that @drive has.
18821 * Use g_drive_get_identifier() to obtain the identifiers
18824 * Returns: (transfer full) (array zero-terminated=1): a %NULL-terminated
18825 * array of strings containing kinds of identifiers. Use g_strfreev()
18831 * g_drive_get_icon:
18832 * @drive: a #GDrive.
18834 * Gets the icon for @drive.
18836 * Returns: (transfer full): #GIcon for the @drive.
18837 * Free the returned object with g_object_unref().
18842 * g_drive_get_identifier:
18843 * @drive: a #GDrive
18844 * @kind: the kind of identifier to return
18846 * Gets the identifier of the given kind for @drive.
18848 * Returns: a newly allocated string containing the
18849 * requested identfier, or %NULL if the #GDrive
18850 * doesn't have this kind of identifier.
18855 * g_drive_get_name:
18856 * @drive: a #GDrive.
18858 * Gets the name of @drive.
18860 * Returns: a string containing @drive's name. The returned
18861 * string should be freed when no longer needed.
18866 * g_drive_get_sort_key:
18867 * @drive: A #GDrive.
18869 * Gets the sort key for @drive, if any.
18871 * Returns: Sorting key for @drive or %NULL if no such key is available.
18877 * g_drive_get_start_stop_type:
18878 * @drive: a #GDrive.
18880 * Gets a hint about how a drive can be started/stopped.
18882 * Returns: A value from the #GDriveStartStopType enumeration.
18888 * g_drive_get_symbolic_icon:
18889 * @drive: a #GDrive.
18891 * Gets the icon for @drive.
18893 * Returns: (transfer full): symbolic #GIcon for the @drive.
18894 * Free the returned object with g_object_unref().
18900 * g_drive_get_volumes:
18901 * @drive: a #GDrive.
18903 * Get a list of mountable volumes for @drive.
18905 * The returned list should be freed with g_list_free(), after
18906 * its elements have been unreffed with g_object_unref().
18908 * Returns: (element-type GVolume) (transfer full): #GList containing any #GVolume objects on the given @drive.
18913 * g_drive_has_media:
18914 * @drive: a #GDrive.
18916 * Checks if the @drive has media. Note that the OS may not be polling
18917 * the drive for media changes; see g_drive_is_media_check_automatic()
18918 * for more details.
18920 * Returns: %TRUE if @drive has media, %FALSE otherwise.
18925 * g_drive_has_volumes:
18926 * @drive: a #GDrive.
18928 * Check if @drive has any mountable volumes.
18930 * Returns: %TRUE if the @drive contains volumes, %FALSE otherwise.
18935 * g_drive_is_media_check_automatic:
18936 * @drive: a #GDrive.
18938 * Checks if @drive is capabable of automatically detecting media changes.
18940 * Returns: %TRUE if the @drive is capabable of automatically detecting
18941 * media changes, %FALSE otherwise.
18946 * g_drive_is_media_removable:
18947 * @drive: a #GDrive.
18949 * Checks if the @drive supports removable media.
18951 * Returns: %TRUE if @drive supports removable media, %FALSE otherwise.
18956 * g_drive_poll_for_media:
18957 * @drive: a #GDrive.
18958 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
18959 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
18960 * @user_data: user data to pass to @callback
18962 * Asynchronously polls @drive to see if media has been inserted or removed.
18964 * When the operation is finished, @callback will be called.
18965 * You can then call g_drive_poll_for_media_finish() to obtain the
18966 * result of the operation.
18971 * g_drive_poll_for_media_finish:
18972 * @drive: a #GDrive.
18973 * @result: a #GAsyncResult.
18974 * @error: a #GError, or %NULL
18976 * Finishes an operation started with g_drive_poll_for_media() on a drive.
18978 * Returns: %TRUE if the drive has been poll_for_mediaed successfully,
18979 * %FALSE otherwise.
18985 * @drive: a #GDrive.
18986 * @flags: flags affecting the start operation.
18987 * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid
18988 * user interaction.
18989 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
18990 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
18991 * @user_data: user data to pass to @callback
18993 * Asynchronously starts a drive.
18995 * When the operation is finished, @callback will be called.
18996 * You can then call g_drive_start_finish() to obtain the
18997 * result of the operation.
19004 * g_drive_start_finish:
19005 * @drive: a #GDrive.
19006 * @result: a #GAsyncResult.
19007 * @error: a #GError, or %NULL
19009 * Finishes starting a drive.
19011 * Returns: %TRUE if the drive has been started successfully,
19012 * %FALSE otherwise.
19019 * @drive: a #GDrive.
19020 * @flags: flags affecting the unmount if required for stopping.
19021 * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid
19022 * user interaction.
19023 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
19024 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
19025 * @user_data: user data to pass to @callback
19027 * Asynchronously stops a drive.
19029 * When the operation is finished, @callback will be called.
19030 * You can then call g_drive_stop_finish() to obtain the
19031 * result of the operation.
19038 * g_drive_stop_finish:
19039 * @drive: a #GDrive.
19040 * @result: a #GAsyncResult.
19041 * @error: a #GError, or %NULL
19043 * Finishes stopping a drive.
19045 * Returns: %TRUE if the drive has been stopped successfully,
19046 * %FALSE otherwise.
19052 * g_emblem_get_icon:
19053 * @emblem: a #GEmblem from which the icon should be extracted.
19055 * Gives back the icon from @emblem.
19057 * Returns: (transfer none): a #GIcon. The returned object belongs to
19058 * the emblem and should not be modified or freed.
19064 * g_emblem_get_origin:
19065 * @emblem: a #GEmblem
19067 * Gets the origin of the emblem.
19069 * Returns: (transfer none): the origin of the emblem
19076 * @icon: a GIcon containing the icon.
19078 * Creates a new emblem for @icon.
19080 * Returns: a new #GEmblem.
19086 * g_emblem_new_with_origin:
19087 * @icon: a GIcon containing the icon.
19088 * @origin: a GEmblemOrigin enum defining the emblem's origin
19090 * Creates a new emblem for @icon.
19092 * Returns: a new #GEmblem.
19098 * g_emblemed_icon_add_emblem:
19099 * @emblemed: a #GEmblemedIcon
19100 * @emblem: a #GEmblem
19102 * Adds @emblem to the #GList of #GEmblems.
19109 * g_emblemed_icon_clear_emblems:
19110 * @emblemed: a #GEmblemedIcon
19112 * Removes all the emblems from @icon.
19119 * g_emblemed_icon_get_emblems:
19120 * @emblemed: a #GEmblemedIcon
19122 * Gets the list of emblems for the @icon.
19124 * Returns: (element-type Gio.Emblem) (transfer none): a #GList of
19125 * #GEmblems that is owned by @emblemed
19131 * g_emblemed_icon_get_icon:
19132 * @emblemed: a #GEmblemedIcon
19134 * Gets the main icon for @emblemed.
19136 * Returns: (transfer none): a #GIcon that is owned by @emblemed
19142 * g_emblemed_icon_new:
19144 * @emblem: (allow-none): a #GEmblem, or %NULL
19146 * Creates a new emblemed icon for @icon with the emblem @emblem.
19148 * Returns: (transfer full) (type GEmblemedIcon): a new #GIcon
19154 * g_file_append_to:
19155 * @file: input #GFile
19156 * @flags: a set of #GFileCreateFlags
19157 * @cancellable: (allow-none): optional #GCancellable object,
19159 * @error: a #GError, or %NULL
19161 * Gets an output stream for appending data to the file.
19162 * If the file doesn't already exist it is created.
19164 * By default files created are generally readable by everyone,
19165 * but if you pass #G_FILE_CREATE_PRIVATE in @flags the file
19166 * will be made readable only to the current user, to the level that
19167 * is supported on the target filesystem.
19169 * If @cancellable is not %NULL, then the operation can be cancelled
19170 * by triggering the cancellable object from another thread. If the
19171 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
19174 * Some file systems don't allow all file names, and may return an
19175 * %G_IO_ERROR_INVALID_FILENAME error. If the file is a directory the
19176 * %G_IO_ERROR_IS_DIRECTORY error will be returned. Other errors are
19177 * possible too, and depend on what kind of filesystem the file is on.
19179 * Returns: (transfer full): a #GFileOutputStream, or %NULL on error.
19180 * Free the returned object with g_object_unref().
19185 * g_file_append_to_async:
19186 * @file: input #GFile
19187 * @flags: a set of #GFileCreateFlags
19188 * @io_priority: the [I/O priority][io-priority] of the request
19189 * @cancellable: (allow-none): optional #GCancellable object,
19191 * @callback: (scope async): a #GAsyncReadyCallback to call
19192 * when the request is satisfied
19193 * @user_data: (closure): the data to pass to callback function
19195 * Asynchronously opens @file for appending.
19197 * For more details, see g_file_append_to() which is
19198 * the synchronous version of this call.
19200 * When the operation is finished, @callback will be called.
19201 * You can then call g_file_append_to_finish() to get the result
19202 * of the operation.
19207 * g_file_append_to_finish:
19208 * @file: input #GFile
19209 * @res: #GAsyncResult
19210 * @error: a #GError, or %NULL
19212 * Finishes an asynchronous file append operation started with
19213 * g_file_append_to_async().
19215 * Returns: (transfer full): a valid #GFileOutputStream
19216 * or %NULL on error.
19217 * Free the returned object with g_object_unref().
19222 * g_file_attribute_info_list_add:
19223 * @list: a #GFileAttributeInfoList.
19224 * @name: the name of the attribute to add.
19225 * @type: the #GFileAttributeType for the attribute.
19226 * @flags: #GFileAttributeInfoFlags for the attribute.
19228 * Adds a new attribute with @name to the @list, setting
19229 * its @type and @flags.
19234 * g_file_attribute_info_list_dup:
19235 * @list: a #GFileAttributeInfoList to duplicate.
19237 * Makes a duplicate of a file attribute info list.
19239 * Returns: a copy of the given @list.
19244 * g_file_attribute_info_list_lookup:
19245 * @list: a #GFileAttributeInfoList.
19246 * @name: the name of the attribute to lookup.
19248 * Gets the file attribute with the name @name from @list.
19250 * Returns: a #GFileAttributeInfo for the @name, or %NULL if an
19251 * attribute isn't found.
19256 * g_file_attribute_info_list_new:
19258 * Creates a new file attribute info list.
19260 * Returns: a #GFileAttributeInfoList.
19265 * g_file_attribute_info_list_ref:
19266 * @list: a #GFileAttributeInfoList to reference.
19268 * References a file attribute info list.
19270 * Returns: #GFileAttributeInfoList or %NULL on error.
19275 * g_file_attribute_info_list_unref:
19276 * @list: The #GFileAttributeInfoList to unreference.
19278 * Removes a reference from the given @list. If the reference count
19279 * falls to zero, the @list is deleted.
19284 * g_file_attribute_matcher_enumerate_namespace:
19285 * @matcher: a #GFileAttributeMatcher.
19286 * @ns: a string containing a file attribute namespace.
19288 * Checks if the matcher will match all of the keys in a given namespace.
19289 * This will always return %TRUE if a wildcard character is in use (e.g. if
19290 * matcher was created with "standard::*" and @ns is "standard", or if matcher was created
19291 * using "*" and namespace is anything.)
19293 * TODO: this is awkwardly worded.
19295 * Returns: %TRUE if the matcher matches all of the entries
19296 * in the given @ns, %FALSE otherwise.
19301 * g_file_attribute_matcher_enumerate_next:
19302 * @matcher: a #GFileAttributeMatcher.
19304 * Gets the next matched attribute from a #GFileAttributeMatcher.
19306 * Returns: a string containing the next attribute or %NULL if
19307 * no more attribute exist.
19312 * g_file_attribute_matcher_matches:
19313 * @matcher: a #GFileAttributeMatcher.
19314 * @attribute: a file attribute key.
19316 * Checks if an attribute will be matched by an attribute matcher. If
19317 * the matcher was created with the "*" matching string, this function
19318 * will always return %TRUE.
19320 * Returns: %TRUE if @attribute matches @matcher. %FALSE otherwise.
19325 * g_file_attribute_matcher_matches_only:
19326 * @matcher: a #GFileAttributeMatcher.
19327 * @attribute: a file attribute key.
19329 * Checks if a attribute matcher only matches a given attribute. Always
19330 * returns %FALSE if "*" was used when creating the matcher.
19332 * Returns: %TRUE if the matcher only matches @attribute. %FALSE otherwise.
19337 * g_file_attribute_matcher_new:
19338 * @attributes: an attribute string to match.
19340 * Creates a new file attribute matcher, which matches attributes
19341 * against a given string. #GFileAttributeMatchers are reference
19342 * counted structures, and are created with a reference count of 1. If
19343 * the number of references falls to 0, the #GFileAttributeMatcher is
19344 * automatically destroyed.
19346 * The @attribute string should be formatted with specific keys separated
19347 * from namespaces with a double colon. Several "namespace::key" strings may be
19348 * concatenated with a single comma (e.g. "standard::type,standard::is-hidden").
19349 * The wildcard "*" may be used to match all keys and namespaces, or
19350 * "namespace::*" will match all keys in a given namespace.
19352 * ## Examples of file attribute matcher strings and results
19354 * - `"*"`: matches all attributes.
19355 * - `"standard::is-hidden"`: matches only the key is-hidden in the
19356 * standard namespace.
19357 * - `"standard::type,unix::*"`: matches the type key in the standard
19358 * namespace and all keys in the unix namespace.
19360 * Returns: a #GFileAttributeMatcher
19365 * g_file_attribute_matcher_ref:
19366 * @matcher: a #GFileAttributeMatcher.
19368 * References a file attribute matcher.
19370 * Returns: a #GFileAttributeMatcher.
19375 * g_file_attribute_matcher_subtract:
19376 * @matcher: Matcher to subtract from
19377 * @subtract: The matcher to subtract
19379 * Subtracts all attributes of @subtract from @matcher and returns
19380 * a matcher that supports those attributes.
19382 * Note that currently it is not possible to remove a single
19383 * attribute when the @matcher matches the whole namespace - or remove
19384 * a namespace or attribute when the matcher matches everything. This
19385 * is a limitation of the current implementation, but may be fixed
19388 * Returns: A file attribute matcher matching all attributes of
19389 * @matcher that are not matched by @subtract
19394 * g_file_attribute_matcher_to_string:
19395 * @matcher: (allow-none): a #GFileAttributeMatcher.
19397 * Prints what the matcher is matching against. The format will be
19398 * equal to the format passed to g_file_attribute_matcher_new().
19399 * The output however, might not be identical, as the matcher may
19400 * decide to use a different order or omit needless parts.
19402 * Returns: a string describing the attributes the matcher matches
19403 * against or %NULL if @matcher was %NULL.
19409 * g_file_attribute_matcher_unref:
19410 * @matcher: a #GFileAttributeMatcher.
19412 * Unreferences @matcher. If the reference count falls below 1,
19413 * the @matcher is automatically freed.
19419 * @source: input #GFile
19420 * @destination: destination #GFile
19421 * @flags: set of #GFileCopyFlags
19422 * @cancellable: (allow-none): optional #GCancellable object,
19424 * @progress_callback: (allow-none) (scope call): function to callback with
19425 * progress information, or %NULL if progress information is not needed
19426 * @progress_callback_data: (closure): user data to pass to @progress_callback
19427 * @error: #GError to set on error, or %NULL
19429 * Copies the file @source to the location specified by @destination.
19430 * Can not handle recursive copies of directories.
19432 * If the flag #G_FILE_COPY_OVERWRITE is specified an already
19433 * existing @destination file is overwritten.
19435 * If the flag #G_FILE_COPY_NOFOLLOW_SYMLINKS is specified then symlinks
19436 * will be copied as symlinks, otherwise the target of the
19437 * @source symlink will be copied.
19439 * If @cancellable is not %NULL, then the operation can be cancelled by
19440 * triggering the cancellable object from another thread. If the operation
19441 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
19443 * If @progress_callback is not %NULL, then the operation can be monitored
19444 * by setting this to a #GFileProgressCallback function.
19445 * @progress_callback_data will be passed to this function. It is guaranteed
19446 * that this callback will be called after all data has been transferred with
19447 * the total number of bytes copied during the operation.
19449 * If the @source file does not exist, then the %G_IO_ERROR_NOT_FOUND error
19450 * is returned, independent on the status of the @destination.
19452 * If #G_FILE_COPY_OVERWRITE is not specified and the target exists, then
19453 * the error %G_IO_ERROR_EXISTS is returned.
19455 * If trying to overwrite a file over a directory, the %G_IO_ERROR_IS_DIRECTORY
19456 * error is returned. If trying to overwrite a directory with a directory the
19457 * %G_IO_ERROR_WOULD_MERGE error is returned.
19459 * If the source is a directory and the target does not exist, or
19460 * #G_FILE_COPY_OVERWRITE is specified and the target is a file, then the
19461 * %G_IO_ERROR_WOULD_RECURSE error is returned.
19463 * If you are interested in copying the #GFile object itself (not the on-disk
19464 * file), see g_file_dup().
19466 * Returns: %TRUE on success, %FALSE otherwise.
19471 * g_file_copy_async: (skip)
19472 * @source: input #GFile
19473 * @destination: destination #GFile
19474 * @flags: set of #GFileCopyFlags
19475 * @io_priority: the [I/O priority][io-priority] of the request
19476 * @cancellable: (allow-none): optional #GCancellable object,
19478 * @progress_callback: (allow-none): function to callback with progress
19479 * information, or %NULL if progress information is not needed
19480 * @progress_callback_data: (closure): user data to pass to @progress_callback
19481 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
19482 * @user_data: the data to pass to callback function
19484 * Copies the file @source to the location specified by @destination
19485 * asynchronously. For details of the behaviour, see g_file_copy().
19487 * If @progress_callback is not %NULL, then that function that will be called
19488 * just like in g_file_copy(). The callback will run in the default main context
19489 * of the thread calling g_file_copy_async() — the same context as @callback is
19492 * When the operation is finished, @callback will be called. You can then call
19493 * g_file_copy_finish() to get the result of the operation.
19498 * g_file_copy_attributes:
19499 * @source: a #GFile with attributes
19500 * @destination: a #GFile to copy attributes to
19501 * @flags: a set of #GFileCopyFlags
19502 * @cancellable: (allow-none): optional #GCancellable object,
19504 * @error: a #GError, %NULL to ignore
19506 * Copies the file attributes from @source to @destination.
19508 * Normally only a subset of the file attributes are copied,
19509 * those that are copies in a normal file copy operation
19510 * (which for instance does not include e.g. owner). However
19511 * if #G_FILE_COPY_ALL_METADATA is specified in @flags, then
19512 * all the metadata that is possible to copy is copied. This
19513 * is useful when implementing move by copy + delete source.
19515 * Returns: %TRUE if the attributes were copied successfully,
19516 * %FALSE otherwise.
19521 * g_file_copy_finish:
19522 * @file: input #GFile
19523 * @res: a #GAsyncResult
19524 * @error: a #GError, or %NULL
19526 * Finishes copying the file started with g_file_copy_async().
19528 * Returns: a %TRUE on success, %FALSE on error.
19534 * @file: input #GFile
19535 * @flags: a set of #GFileCreateFlags
19536 * @cancellable: (allow-none): optional #GCancellable object,
19538 * @error: a #GError, or %NULL
19540 * Creates a new file and returns an output stream for writing to it.
19541 * The file must not already exist.
19543 * By default files created are generally readable by everyone,
19544 * but if you pass #G_FILE_CREATE_PRIVATE in @flags the file
19545 * will be made readable only to the current user, to the level
19546 * that is supported on the target filesystem.
19548 * If @cancellable is not %NULL, then the operation can be cancelled
19549 * by triggering the cancellable object from another thread. If the
19550 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
19553 * If a file or directory with this name already exists the
19554 * %G_IO_ERROR_EXISTS error will be returned. Some file systems don't
19555 * allow all file names, and may return an %G_IO_ERROR_INVALID_FILENAME
19556 * error, and if the name is to long %G_IO_ERROR_FILENAME_TOO_LONG will
19557 * be returned. Other errors are possible too, and depend on what kind
19558 * of filesystem the file is on.
19560 * Returns: (transfer full): a #GFileOutputStream for the newly created
19561 * file, or %NULL on error.
19562 * Free the returned object with g_object_unref().
19567 * g_file_create_async:
19568 * @file: input #GFile
19569 * @flags: a set of #GFileCreateFlags
19570 * @io_priority: the [I/O priority][io-priority] of the request
19571 * @cancellable: (allow-none): optional #GCancellable object,
19573 * @callback: (scope async): a #GAsyncReadyCallback to call
19574 * when the request is satisfied
19575 * @user_data: (closure): the data to pass to callback function
19577 * Asynchronously creates a new file and returns an output stream
19578 * for writing to it. The file must not already exist.
19580 * For more details, see g_file_create() which is
19581 * the synchronous version of this call.
19583 * When the operation is finished, @callback will be called.
19584 * You can then call g_file_create_finish() to get the result
19585 * of the operation.
19590 * g_file_create_finish:
19591 * @file: input #GFile
19592 * @res: a #GAsyncResult
19593 * @error: a #GError, or %NULL
19595 * Finishes an asynchronous file create operation started with
19596 * g_file_create_async().
19598 * Returns: (transfer full): a #GFileOutputStream or %NULL on error.
19599 * Free the returned object with g_object_unref().
19604 * g_file_create_readwrite:
19606 * @flags: a set of #GFileCreateFlags
19607 * @cancellable: (allow-none): optional #GCancellable object,
19609 * @error: return location for a #GError, or %NULL
19611 * Creates a new file and returns a stream for reading and
19612 * writing to it. The file must not already exist.
19614 * By default files created are generally readable by everyone,
19615 * but if you pass #G_FILE_CREATE_PRIVATE in @flags the file
19616 * will be made readable only to the current user, to the level
19617 * that is supported on the target filesystem.
19619 * If @cancellable is not %NULL, then the operation can be cancelled
19620 * by triggering the cancellable object from another thread. If the
19621 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
19624 * If a file or directory with this name already exists, the
19625 * %G_IO_ERROR_EXISTS error will be returned. Some file systems don't
19626 * allow all file names, and may return an %G_IO_ERROR_INVALID_FILENAME
19627 * error, and if the name is too long, %G_IO_ERROR_FILENAME_TOO_LONG
19628 * will be returned. Other errors are possible too, and depend on what
19629 * kind of filesystem the file is on.
19631 * Note that in many non-local file cases read and write streams are
19632 * not supported, so make sure you really need to do read and write
19633 * streaming, rather than just opening for reading or writing.
19635 * Returns: (transfer full): a #GFileIOStream for the newly created
19636 * file, or %NULL on error.
19637 * Free the returned object with g_object_unref().
19643 * g_file_create_readwrite_async:
19644 * @file: input #GFile
19645 * @flags: a set of #GFileCreateFlags
19646 * @io_priority: the [I/O priority][io-priority] of the request
19647 * @cancellable: (allow-none): optional #GCancellable object,
19649 * @callback: (scope async): a #GAsyncReadyCallback to call
19650 * when the request is satisfied
19651 * @user_data: (closure): the data to pass to callback function
19653 * Asynchronously creates a new file and returns a stream
19654 * for reading and writing to it. The file must not already exist.
19656 * For more details, see g_file_create_readwrite() which is
19657 * the synchronous version of this call.
19659 * When the operation is finished, @callback will be called.
19660 * You can then call g_file_create_readwrite_finish() to get
19661 * the result of the operation.
19668 * g_file_create_readwrite_finish:
19669 * @file: input #GFile
19670 * @res: a #GAsyncResult
19671 * @error: a #GError, or %NULL
19673 * Finishes an asynchronous file create operation started with
19674 * g_file_create_readwrite_async().
19676 * Returns: (transfer full): a #GFileIOStream or %NULL on error.
19677 * Free the returned object with g_object_unref().
19683 * g_file_delete: (virtual delete_file)
19684 * @file: input #GFile
19685 * @cancellable: (allow-none): optional #GCancellable object,
19687 * @error: a #GError, or %NULL
19689 * Deletes a file. If the @file is a directory, it will only be
19690 * deleted if it is empty. This has the same semantics as g_unlink().
19692 * If @cancellable is not %NULL, then the operation can be cancelled by
19693 * triggering the cancellable object from another thread. If the operation
19694 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
19696 * Returns: %TRUE if the file was deleted. %FALSE otherwise.
19701 * g_file_delete_async: (virtual delete_file_async)
19702 * @file: input #GFile
19703 * @io_priority: the [I/O priority][io-priority] of the request
19704 * @cancellable: (allow-none): optional #GCancellable object,
19706 * @callback: a #GAsyncReadyCallback to call
19707 * when the request is satisfied
19708 * @user_data: the data to pass to callback function
19710 * Asynchronously delete a file. If the @file is a directory, it will
19711 * only be deleted if it is empty. This has the same semantics as
19719 * g_file_delete_finish: (virtual delete_file_finish)
19720 * @file: input #GFile
19721 * @result: a #GAsyncResult
19722 * @error: a #GError, or %NULL
19724 * Finishes deleting a file started with g_file_delete_async().
19726 * Returns: %TRUE if the file was deleted. %FALSE otherwise.
19732 * g_file_descriptor_based_get_fd:
19733 * @fd_based: a #GFileDescriptorBased.
19735 * Gets the underlying file descriptor.
19737 * Returns: The file descriptor
19744 * @file: input #GFile
19746 * Duplicates a #GFile handle. This operation does not duplicate
19747 * the actual file or directory represented by the #GFile; see
19748 * g_file_copy() if attempting to copy a file.
19750 * This call does no blocking I/O.
19752 * Returns: (transfer full): a new #GFile that is a duplicate
19753 * of the given #GFile.
19758 * g_file_eject_mountable:
19759 * @file: input #GFile
19760 * @flags: flags affecting the operation
19761 * @cancellable: (allow-none): optional #GCancellable object,
19763 * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call
19764 * when the request is satisfied, or %NULL
19765 * @user_data: (closure): the data to pass to callback function
19767 * Starts an asynchronous eject on a mountable.
19768 * When this operation has completed, @callback will be called with
19769 * @user_user data, and the operation can be finalized with
19770 * g_file_eject_mountable_finish().
19772 * If @cancellable is not %NULL, then the operation can be cancelled by
19773 * triggering the cancellable object from another thread. If the operation
19774 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
19776 * Deprecated: 2.22: Use g_file_eject_mountable_with_operation() instead.
19781 * g_file_eject_mountable_finish:
19782 * @file: input #GFile
19783 * @result: a #GAsyncResult
19784 * @error: a #GError, or %NULL
19786 * Finishes an asynchronous eject operation started by
19787 * g_file_eject_mountable().
19789 * Returns: %TRUE if the @file was ejected successfully.
19790 * %FALSE otherwise.
19791 * Deprecated: 2.22: Use g_file_eject_mountable_with_operation_finish()
19797 * g_file_eject_mountable_with_operation:
19798 * @file: input #GFile
19799 * @flags: flags affecting the operation
19800 * @mount_operation: (allow-none): a #GMountOperation,
19801 * or %NULL to avoid user interaction
19802 * @cancellable: (allow-none): optional #GCancellable object,
19804 * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call
19805 * when the request is satisfied, or %NULL
19806 * @user_data: (closure): the data to pass to callback function
19808 * Starts an asynchronous eject on a mountable.
19809 * When this operation has completed, @callback will be called with
19810 * @user_user data, and the operation can be finalized with
19811 * g_file_eject_mountable_with_operation_finish().
19813 * If @cancellable is not %NULL, then the operation can be cancelled by
19814 * triggering the cancellable object from another thread. If the operation
19815 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
19822 * g_file_eject_mountable_with_operation_finish:
19823 * @file: input #GFile
19824 * @result: a #GAsyncResult
19825 * @error: a #GError, or %NULL
19827 * Finishes an asynchronous eject operation started by
19828 * g_file_eject_mountable_with_operation().
19830 * Returns: %TRUE if the @file was ejected successfully.
19831 * %FALSE otherwise.
19837 * g_file_enumerate_children:
19838 * @file: input #GFile
19839 * @attributes: an attribute query string
19840 * @flags: a set of #GFileQueryInfoFlags
19841 * @cancellable: (allow-none): optional #GCancellable object,
19843 * @error: #GError for error reporting
19845 * Gets the requested information about the files in a directory.
19846 * The result is a #GFileEnumerator object that will give out
19847 * #GFileInfo objects for all the files in the directory.
19849 * The @attributes value is a string that specifies the file
19850 * attributes that should be gathered. It is not an error if
19851 * it's not possible to read a particular requested attribute
19852 * from a file - it just won't be set. @attributes should
19853 * be a comma-separated list of attributes or attribute wildcards.
19854 * The wildcard "*" means all attributes, and a wildcard like
19855 * "standard::*" means all attributes in the standard namespace.
19856 * An example attribute query be "standard::*,owner::user".
19857 * The standard attributes are available as defines, like
19858 * #G_FILE_ATTRIBUTE_STANDARD_NAME.
19860 * If @cancellable is not %NULL, then the operation can be cancelled
19861 * by triggering the cancellable object from another thread. If the
19862 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
19865 * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will
19866 * be returned. If the file is not a directory, the %G_IO_ERROR_NOT_DIRECTORY
19867 * error will be returned. Other errors are possible too.
19869 * Returns: (transfer full): A #GFileEnumerator if successful,
19870 * %NULL on error. Free the returned object with g_object_unref().
19875 * g_file_enumerate_children_async:
19876 * @file: input #GFile
19877 * @attributes: an attribute query string
19878 * @flags: a set of #GFileQueryInfoFlags
19879 * @io_priority: the [I/O priority][io-priority] of the request
19880 * @cancellable: (allow-none): optional #GCancellable object,
19882 * @callback: (scope async): a #GAsyncReadyCallback to call when the
19883 * request is satisfied
19884 * @user_data: (closure): the data to pass to callback function
19886 * Asynchronously gets the requested information about the files
19887 * in a directory. The result is a #GFileEnumerator object that will
19888 * give out #GFileInfo objects for all the files in the directory.
19890 * For more details, see g_file_enumerate_children() which is
19891 * the synchronous version of this call.
19893 * When the operation is finished, @callback will be called. You can
19894 * then call g_file_enumerate_children_finish() to get the result of
19900 * g_file_enumerate_children_finish:
19901 * @file: input #GFile
19902 * @res: a #GAsyncResult
19903 * @error: a #GError
19905 * Finishes an async enumerate children operation.
19906 * See g_file_enumerate_children_async().
19908 * Returns: (transfer full): a #GFileEnumerator or %NULL
19909 * if an error occurred.
19910 * Free the returned object with g_object_unref().
19915 * g_file_enumerator_close:
19916 * @enumerator: a #GFileEnumerator.
19917 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
19918 * @error: location to store the error occurring, or %NULL to ignore
19920 * Releases all resources used by this enumerator, making the
19921 * enumerator return %G_IO_ERROR_CLOSED on all calls.
19923 * This will be automatically called when the last reference
19924 * is dropped, but you might want to call this function to make
19925 * sure resources are released as early as possible.
19927 * Returns: #TRUE on success or #FALSE on error.
19932 * g_file_enumerator_close_async:
19933 * @enumerator: a #GFileEnumerator.
19934 * @io_priority: the [I/O priority][io-priority] of the request
19935 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
19936 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
19937 * @user_data: (closure): the data to pass to callback function
19939 * Asynchronously closes the file enumerator.
19941 * If @cancellable is not %NULL, then the operation can be cancelled by
19942 * triggering the cancellable object from another thread. If the operation
19943 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned in
19944 * g_file_enumerator_close_finish().
19949 * g_file_enumerator_close_finish:
19950 * @enumerator: a #GFileEnumerator.
19951 * @result: a #GAsyncResult.
19952 * @error: a #GError location to store the error occurring, or %NULL to
19955 * Finishes closing a file enumerator, started from g_file_enumerator_close_async().
19957 * If the file enumerator was already closed when g_file_enumerator_close_async()
19958 * was called, then this function will report %G_IO_ERROR_CLOSED in @error, and
19959 * return %FALSE. If the file enumerator had pending operation when the close
19960 * operation was started, then this function will report %G_IO_ERROR_PENDING, and
19961 * return %FALSE. If @cancellable was not %NULL, then the operation may have been
19962 * cancelled by triggering the cancellable object from another thread. If the operation
19963 * was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %FALSE will be
19966 * Returns: %TRUE if the close operation has finished successfully.
19971 * g_file_enumerator_get_child:
19972 * @enumerator: a #GFileEnumerator
19973 * @info: a #GFileInfo gotten from g_file_enumerator_next_file()
19974 * or the async equivalents.
19976 * Return a new #GFile which refers to the file named by @info in the source
19977 * directory of @enumerator. This function is primarily intended to be used
19978 * inside loops with g_file_enumerator_next_file().
19980 * This is a convenience method that's equivalent to:
19981 * |[<!-- language="C" -->
19982 * gchar *name = g_file_info_get_name (info);
19983 * GFile *child = g_file_get_child (g_file_enumerator_get_container (enumr),
19987 * Returns: (transfer full): a #GFile for the #GFileInfo passed it.
19993 * g_file_enumerator_get_container:
19994 * @enumerator: a #GFileEnumerator
19996 * Get the #GFile container which is being enumerated.
19998 * Returns: (transfer none): the #GFile which is being enumerated.
20004 * g_file_enumerator_has_pending:
20005 * @enumerator: a #GFileEnumerator.
20007 * Checks if the file enumerator has pending operations.
20009 * Returns: %TRUE if the @enumerator has pending operations.
20014 * g_file_enumerator_is_closed:
20015 * @enumerator: a #GFileEnumerator.
20017 * Checks if the file enumerator has been closed.
20019 * Returns: %TRUE if the @enumerator is closed.
20024 * g_file_enumerator_next_file:
20025 * @enumerator: a #GFileEnumerator.
20026 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
20027 * @error: location to store the error occurring, or %NULL to ignore
20029 * Returns information for the next file in the enumerated object.
20030 * Will block until the information is available. The #GFileInfo
20031 * returned from this function will contain attributes that match the
20032 * attribute string that was passed when the #GFileEnumerator was created.
20034 * See the documentation of #GFileEnumerator for information about the
20035 * order of returned files.
20037 * On error, returns %NULL and sets @error to the error. If the
20038 * enumerator is at the end, %NULL will be returned and @error will
20041 * Returns: (nullable) (transfer full): A #GFileInfo or %NULL on error
20042 * or end of enumerator. Free the returned object with
20043 * g_object_unref() when no longer needed.
20048 * g_file_enumerator_next_files_async:
20049 * @enumerator: a #GFileEnumerator.
20050 * @num_files: the number of file info objects to request
20051 * @io_priority: the [I/O priority][io-priority] of the request
20052 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
20053 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
20054 * @user_data: (closure): the data to pass to callback function
20056 * Request information for a number of files from the enumerator asynchronously.
20057 * When all i/o for the operation is finished the @callback will be called with
20058 * the requested information.
20060 * See the documentation of #GFileEnumerator for information about the
20061 * order of returned files.
20063 * The callback can be called with less than @num_files files in case of error
20064 * or at the end of the enumerator. In case of a partial error the callback will
20065 * be called with any succeeding items and no error, and on the next request the
20066 * error will be reported. If a request is cancelled the callback will be called
20067 * with %G_IO_ERROR_CANCELLED.
20069 * During an async request no other sync and async calls are allowed, and will
20070 * result in %G_IO_ERROR_PENDING errors.
20072 * Any outstanding i/o request with higher priority (lower numerical value) will
20073 * be executed before an outstanding request with lower priority. Default
20074 * priority is %G_PRIORITY_DEFAULT.
20079 * g_file_enumerator_next_files_finish:
20080 * @enumerator: a #GFileEnumerator.
20081 * @result: a #GAsyncResult.
20082 * @error: a #GError location to store the error occurring, or %NULL to
20085 * Finishes the asynchronous operation started with g_file_enumerator_next_files_async().
20087 * Returns: (transfer full) (element-type Gio.FileInfo): a #GList of #GFileInfos. You must free the list with
20088 * g_list_free() and unref the infos with g_object_unref() when you're
20094 * g_file_enumerator_set_pending:
20095 * @enumerator: a #GFileEnumerator.
20096 * @pending: a boolean value.
20098 * Sets the file enumerator as having pending operations.
20104 * @file1: the first #GFile
20105 * @file2: the second #GFile
20107 * Checks equality of two given #GFiles.
20109 * Note that two #GFiles that differ can still refer to the same
20110 * file on the filesystem due to various forms of filename
20113 * This call does no blocking I/O.
20115 * Returns: %TRUE if @file1 and @file2 are equal.
20120 * g_file_find_enclosing_mount:
20121 * @file: input #GFile
20122 * @cancellable: (allow-none): optional #GCancellable object,
20124 * @error: a #GError
20126 * Gets a #GMount for the #GFile.
20128 * If the #GFileIface for @file does not have a mount (e.g.
20129 * possibly a remote share), @error will be set to %G_IO_ERROR_NOT_FOUND
20130 * and %NULL will be returned.
20132 * If @cancellable is not %NULL, then the operation can be cancelled by
20133 * triggering the cancellable object from another thread. If the operation
20134 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
20136 * Returns: (transfer full): a #GMount where the @file is located
20137 * or %NULL on error.
20138 * Free the returned object with g_object_unref().
20143 * g_file_find_enclosing_mount_async:
20145 * @io_priority: the [I/O priority][io-priority] of the request
20146 * @cancellable: (allow-none): optional #GCancellable object,
20148 * @callback: (scope async): a #GAsyncReadyCallback to call
20149 * when the request is satisfied
20150 * @user_data: (closure): the data to pass to callback function
20152 * Asynchronously gets the mount for the file.
20154 * For more details, see g_file_find_enclosing_mount() which is
20155 * the synchronous version of this call.
20157 * When the operation is finished, @callback will be called.
20158 * You can then call g_file_find_enclosing_mount_finish() to
20159 * get the result of the operation.
20164 * g_file_find_enclosing_mount_finish:
20166 * @res: a #GAsyncResult
20167 * @error: a #GError
20169 * Finishes an asynchronous find mount request.
20170 * See g_file_find_enclosing_mount_async().
20172 * Returns: (transfer full): #GMount for given @file or %NULL on error.
20173 * Free the returned object with g_object_unref().
20178 * g_file_get_basename:
20179 * @file: input #GFile
20181 * Gets the base name (the last component of the path) for a given #GFile.
20183 * If called for the top level of a system (such as the filesystem root
20184 * or a uri like sftp://host/) it will return a single directory separator
20185 * (and on Windows, possibly a drive letter).
20187 * The base name is a byte string (not UTF-8). It has no defined encoding
20188 * or rules other than it may not contain zero bytes. If you want to use
20189 * filenames in a user interface you should use the display name that you
20190 * can get by requesting the %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME
20191 * attribute with g_file_query_info().
20193 * This call does no blocking I/O.
20195 * Returns: (nullable): string containing the #GFile's base name, or
20196 * %NULL if given #GFile is invalid. The returned string should be
20197 * freed with g_free() when no longer needed.
20202 * g_file_get_child:
20203 * @file: input #GFile
20204 * @name: string containing the child's basename
20206 * Gets a child of @file with basename equal to @name.
20208 * Note that the file with that specific name might not exist, but
20209 * you can still have a #GFile that points to it. You can use this
20210 * for instance to create that file.
20212 * This call does no blocking I/O.
20214 * Returns: (transfer full): a #GFile to a child specified by @name.
20215 * Free the returned object with g_object_unref().
20220 * g_file_get_child_for_display_name:
20221 * @file: input #GFile
20222 * @display_name: string to a possible child
20223 * @error: return location for an error
20225 * Gets the child of @file for a given @display_name (i.e. a UTF-8
20226 * version of the name). If this function fails, it returns %NULL
20227 * and @error will be set. This is very useful when constructing a
20228 * #GFile for a new file and the user entered the filename in the
20229 * user interface, for instance when you select a directory and
20230 * type a filename in the file selector.
20232 * This call does no blocking I/O.
20234 * Returns: (transfer full): a #GFile to the specified child, or
20235 * %NULL if the display name couldn't be converted.
20236 * Free the returned object with g_object_unref().
20241 * g_file_get_parent:
20242 * @file: input #GFile
20244 * Gets the parent directory for the @file.
20245 * If the @file represents the root directory of the
20246 * file system, then %NULL will be returned.
20248 * This call does no blocking I/O.
20250 * Returns: (nullable) (transfer full): a #GFile structure to the
20251 * parent of the given #GFile or %NULL if there is no parent. Free
20252 * the returned object with g_object_unref().
20257 * g_file_get_parse_name:
20258 * @file: input #GFile
20260 * Gets the parse name of the @file.
20261 * A parse name is a UTF-8 string that describes the
20262 * file such that one can get the #GFile back using
20263 * g_file_parse_name().
20265 * This is generally used to show the #GFile as a nice
20266 * full-pathname kind of string in a user interface,
20267 * like in a location entry.
20269 * For local files with names that can safely be converted
20270 * to UTF-8 the pathname is used, otherwise the IRI is used
20271 * (a form of URI that allows UTF-8 characters unescaped).
20273 * This call does no blocking I/O.
20275 * Returns: a string containing the #GFile's parse name.
20276 * The returned string should be freed with g_free()
20277 * when no longer needed.
20283 * @file: input #GFile
20285 * Gets the local pathname for #GFile, if one exists.
20287 * This call does no blocking I/O.
20289 * Returns: (nullable): string containing the #GFile's path, or %NULL
20290 * if no such path exists. The returned string should be freed
20291 * with g_free() when no longer needed.
20296 * g_file_get_relative_path:
20297 * @parent: input #GFile
20298 * @descendant: input #GFile
20300 * Gets the path for @descendant relative to @parent.
20302 * This call does no blocking I/O.
20304 * Returns: (nullable): string with the relative path from @descendant
20305 * to @parent, or %NULL if @descendant doesn't have @parent as
20306 * prefix. The returned string should be freed with g_free() when
20307 * no longer needed.
20313 * @file: input #GFile
20315 * Gets the URI for the @file.
20317 * This call does no blocking I/O.
20319 * Returns: a string containing the #GFile's URI.
20320 * The returned string should be freed with g_free()
20321 * when no longer needed.
20326 * g_file_get_uri_scheme:
20327 * @file: input #GFile
20329 * Gets the URI scheme for a #GFile.
20330 * RFC 3986 decodes the scheme as:
20332 * URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
20334 * Common schemes include "file", "http", "ftp", etc.
20336 * This call does no blocking I/O.
20338 * Returns: a string containing the URI scheme for the given
20339 * #GFile. The returned string should be freed with g_free()
20340 * when no longer needed.
20345 * g_file_has_parent:
20346 * @file: input #GFile
20347 * @parent: (allow-none): the parent to check for, or %NULL
20349 * Checks if @file has a parent, and optionally, if it is @parent.
20351 * If @parent is %NULL then this function returns %TRUE if @file has any
20352 * parent at all. If @parent is non-%NULL then %TRUE is only returned
20353 * if @file is a child of @parent.
20355 * Returns: %TRUE if @file is a child of @parent (or any parent in the
20356 * case that @parent is %NULL).
20362 * g_file_has_prefix: (virtual prefix_matches)
20363 * @file: input #GFile
20364 * @prefix: input #GFile
20366 * Checks whether @file has the prefix specified by @prefix.
20368 * In other words, if the names of initial elements of @file's
20369 * pathname match @prefix. Only full pathname elements are matched,
20370 * so a path like /foo is not considered a prefix of /foobar, only
20373 * This call does no I/O, as it works purely on names. As such it can
20374 * sometimes return %FALSE even if @file is inside a @prefix (from a
20375 * filesystem point of view), because the prefix of @file is an alias
20378 * Returns: %TRUE if the @files's parent, grandparent, etc is @prefix,
20379 * %FALSE otherwise.
20384 * g_file_has_uri_scheme:
20385 * @file: input #GFile
20386 * @uri_scheme: a string containing a URI scheme
20388 * Checks to see if a #GFile has a given URI scheme.
20390 * This call does no blocking I/O.
20392 * Returns: %TRUE if #GFile's backend supports the
20393 * given URI scheme, %FALSE if URI scheme is %NULL,
20394 * not supported, or #GFile is invalid.
20399 * g_file_hash: (virtual hash)
20400 * @file: (type GFile): #gconstpointer to a #GFile
20402 * Creates a hash value for a #GFile.
20404 * This call does no blocking I/O.
20406 * Returns: 0 if @file is not a valid #GFile, otherwise an
20407 * integer that can be used as hash value for the #GFile.
20408 * This function is intended for easily hashing a #GFile to
20409 * add to a #GHashTable or similar data structure.
20414 * g_file_icon_get_file:
20417 * Gets the #GFile associated with the given @icon.
20419 * Returns: (transfer none): a #GFile, or %NULL.
20427 * Creates a new icon for a file.
20429 * Returns: (transfer full) (type GFileIcon): a #GIcon for the given
20430 * @file, or %NULL on error.
20435 * g_file_info_clear_status:
20436 * @info: a #GFileInfo.
20438 * Clears the status information from @info.
20443 * g_file_info_copy_into:
20444 * @src_info: source to copy attributes from.
20445 * @dest_info: destination to copy attributes to.
20447 * Copies all of the [GFileAttribute][gio-GFileAttribute]
20448 * from @src_info to @dest_info.
20454 * @other: a #GFileInfo.
20456 * Duplicates a file info structure.
20458 * Returns: (transfer full): a duplicate #GFileInfo of @other.
20463 * g_file_info_get_attribute_as_string:
20464 * @info: a #GFileInfo.
20465 * @attribute: a file attribute key.
20467 * Gets the value of a attribute, formated as a string.
20468 * This escapes things as needed to make the string valid
20471 * Returns: a UTF-8 string associated with the given @attribute.
20472 * When you're done with the string it must be freed with g_free().
20477 * g_file_info_get_attribute_boolean:
20478 * @info: a #GFileInfo.
20479 * @attribute: a file attribute key.
20481 * Gets the value of a boolean attribute. If the attribute does not
20482 * contain a boolean value, %FALSE will be returned.
20484 * Returns: the boolean value contained within the attribute.
20489 * g_file_info_get_attribute_byte_string:
20490 * @info: a #GFileInfo.
20491 * @attribute: a file attribute key.
20493 * Gets the value of a byte string attribute. If the attribute does
20494 * not contain a byte string, %NULL will be returned.
20496 * Returns: the contents of the @attribute value as a byte string, or
20502 * g_file_info_get_attribute_data:
20503 * @info: a #GFileInfo
20504 * @attribute: a file attribute key
20505 * @type: (out) (allow-none): return location for the attribute type, or %NULL
20506 * @value_pp: (out) (allow-none): return location for the attribute value, or %NULL
20507 * @status: (out) (allow-none): return location for the attribute status, or %NULL
20509 * Gets the attribute type, value and status for an attribute key.
20511 * Returns: (transfer none): %TRUE if @info has an attribute named @attribute,
20512 * %FALSE otherwise.
20517 * g_file_info_get_attribute_int32:
20518 * @info: a #GFileInfo.
20519 * @attribute: a file attribute key.
20521 * Gets a signed 32-bit integer contained within the attribute. If the
20522 * attribute does not contain a signed 32-bit integer, or is invalid,
20523 * 0 will be returned.
20525 * Returns: a signed 32-bit integer from the attribute.
20530 * g_file_info_get_attribute_int64:
20531 * @info: a #GFileInfo.
20532 * @attribute: a file attribute key.
20534 * Gets a signed 64-bit integer contained within the attribute. If the
20535 * attribute does not contain an signed 64-bit integer, or is invalid,
20536 * 0 will be returned.
20538 * Returns: a signed 64-bit integer from the attribute.
20543 * g_file_info_get_attribute_object:
20544 * @info: a #GFileInfo.
20545 * @attribute: a file attribute key.
20547 * Gets the value of a #GObject attribute. If the attribute does
20548 * not contain a #GObject, %NULL will be returned.
20550 * Returns: (transfer none): a #GObject associated with the given @attribute, or
20556 * g_file_info_get_attribute_status:
20557 * @info: a #GFileInfo
20558 * @attribute: a file attribute key
20560 * Gets the attribute status for an attribute key.
20562 * Returns: a #GFileAttributeStatus for the given @attribute, or
20563 * %G_FILE_ATTRIBUTE_STATUS_UNSET if the key is invalid.
20568 * g_file_info_get_attribute_string:
20569 * @info: a #GFileInfo.
20570 * @attribute: a file attribute key.
20572 * Gets the value of a string attribute. If the attribute does
20573 * not contain a string, %NULL will be returned.
20575 * Returns: the contents of the @attribute value as a UTF-8 string, or
20581 * g_file_info_get_attribute_stringv:
20582 * @info: a #GFileInfo.
20583 * @attribute: a file attribute key.
20585 * Gets the value of a stringv attribute. If the attribute does
20586 * not contain a stringv, %NULL will be returned.
20588 * Returns: (transfer none): the contents of the @attribute value as a stringv, or
20589 * %NULL otherwise. Do not free. These returned strings are UTF-8.
20595 * g_file_info_get_attribute_type:
20596 * @info: a #GFileInfo.
20597 * @attribute: a file attribute key.
20599 * Gets the attribute type for an attribute key.
20601 * Returns: a #GFileAttributeType for the given @attribute, or
20602 * %G_FILE_ATTRIBUTE_TYPE_INVALID if the key is not set.
20607 * g_file_info_get_attribute_uint32:
20608 * @info: a #GFileInfo.
20609 * @attribute: a file attribute key.
20611 * Gets an unsigned 32-bit integer contained within the attribute. If the
20612 * attribute does not contain an unsigned 32-bit integer, or is invalid,
20613 * 0 will be returned.
20615 * Returns: an unsigned 32-bit integer from the attribute.
20620 * g_file_info_get_attribute_uint64:
20621 * @info: a #GFileInfo.
20622 * @attribute: a file attribute key.
20624 * Gets a unsigned 64-bit integer contained within the attribute. If the
20625 * attribute does not contain an unsigned 64-bit integer, or is invalid,
20626 * 0 will be returned.
20628 * Returns: a unsigned 64-bit integer from the attribute.
20633 * g_file_info_get_content_type:
20634 * @info: a #GFileInfo.
20636 * Gets the file's content type.
20638 * Returns: a string containing the file's content type.
20643 * g_file_info_get_deletion_date:
20644 * @info: a #GFileInfo.
20646 * Returns the #GDateTime representing the deletion date of the file, as
20647 * available in G_FILE_ATTRIBUTE_TRASH_DELETION_DATE. If the
20648 * G_FILE_ATTRIBUTE_TRASH_DELETION_DATE attribute is unset, %NULL is returned.
20650 * Returns: a #GDateTime, or %NULL.
20656 * g_file_info_get_display_name:
20657 * @info: a #GFileInfo.
20659 * Gets a display name for a file.
20661 * Returns: a string containing the display name.
20666 * g_file_info_get_edit_name:
20667 * @info: a #GFileInfo.
20669 * Gets the edit name for a file.
20671 * Returns: a string containing the edit name.
20676 * g_file_info_get_etag:
20677 * @info: a #GFileInfo.
20679 * Gets the [entity tag][gfile-etag] for a given
20680 * #GFileInfo. See %G_FILE_ATTRIBUTE_ETAG_VALUE.
20682 * Returns: a string containing the value of the "etag:value" attribute.
20687 * g_file_info_get_file_type:
20688 * @info: a #GFileInfo.
20690 * Gets a file's type (whether it is a regular file, symlink, etc).
20691 * This is different from the file's content type, see g_file_info_get_content_type().
20693 * Returns: a #GFileType for the given file.
20698 * g_file_info_get_icon:
20699 * @info: a #GFileInfo.
20701 * Gets the icon for a file.
20703 * Returns: (transfer none): #GIcon for the given @info.
20708 * g_file_info_get_is_backup:
20709 * @info: a #GFileInfo.
20711 * Checks if a file is a backup file.
20713 * Returns: %TRUE if file is a backup file, %FALSE otherwise.
20718 * g_file_info_get_is_hidden:
20719 * @info: a #GFileInfo.
20721 * Checks if a file is hidden.
20723 * Returns: %TRUE if the file is a hidden file, %FALSE otherwise.
20728 * g_file_info_get_is_symlink:
20729 * @info: a #GFileInfo.
20731 * Checks if a file is a symlink.
20733 * Returns: %TRUE if the given @info is a symlink.
20738 * g_file_info_get_modification_time:
20739 * @info: a #GFileInfo.
20740 * @result: (out caller-allocates): a #GTimeVal.
20742 * Gets the modification time of the current @info and sets it
20748 * g_file_info_get_name:
20749 * @info: a #GFileInfo.
20751 * Gets the name for a file.
20753 * Returns: a string containing the file name.
20758 * g_file_info_get_size:
20759 * @info: a #GFileInfo.
20761 * Gets the file's size.
20763 * Returns: a #goffset containing the file's size.
20768 * g_file_info_get_sort_order:
20769 * @info: a #GFileInfo.
20771 * Gets the value of the sort_order attribute from the #GFileInfo.
20772 * See %G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER.
20774 * Returns: a #gint32 containing the value of the "standard::sort_order" attribute.
20779 * g_file_info_get_symbolic_icon:
20780 * @info: a #GFileInfo.
20782 * Gets the symbolic icon for a file.
20784 * Returns: (transfer none): #GIcon for the given @info.
20790 * g_file_info_get_symlink_target:
20791 * @info: a #GFileInfo.
20793 * Gets the symlink target for a given #GFileInfo.
20795 * Returns: a string containing the symlink target.
20800 * g_file_info_has_attribute:
20801 * @info: a #GFileInfo.
20802 * @attribute: a file attribute key.
20804 * Checks if a file info structure has an attribute named @attribute.
20806 * Returns: %TRUE if @Ginfo has an attribute named @attribute,
20807 * %FALSE otherwise.
20812 * g_file_info_has_namespace:
20813 * @info: a #GFileInfo.
20814 * @name_space: a file attribute namespace.
20816 * Checks if a file info structure has an attribute in the
20817 * specified @name_space.
20819 * Returns: %TRUE if @Ginfo has an attribute in @name_space,
20820 * %FALSE otherwise.
20826 * g_file_info_list_attributes:
20827 * @info: a #GFileInfo.
20828 * @name_space: a file attribute key's namespace.
20830 * Lists the file info structure's attributes.
20832 * Returns: (nullable) (array zero-terminated=1) (transfer full): a
20833 * null-terminated array of strings of all of the possible attribute
20834 * types for the given @name_space, or %NULL on error.
20841 * Creates a new file info structure.
20843 * Returns: a #GFileInfo.
20848 * g_file_info_remove_attribute:
20849 * @info: a #GFileInfo.
20850 * @attribute: a file attribute key.
20852 * Removes all cases of @attribute from @info if it exists.
20857 * g_file_info_set_attribute:
20858 * @info: a #GFileInfo.
20859 * @attribute: a file attribute key.
20860 * @type: a #GFileAttributeType
20861 * @value_p: pointer to the value
20863 * Sets the @attribute to contain the given value, if possible. To unset the
20864 * attribute, use %G_ATTRIBUTE_TYPE_INVALID for @type.
20869 * g_file_info_set_attribute_boolean:
20870 * @info: a #GFileInfo.
20871 * @attribute: a file attribute key.
20872 * @attr_value: a boolean value.
20874 * Sets the @attribute to contain the given @attr_value,
20880 * g_file_info_set_attribute_byte_string:
20881 * @info: a #GFileInfo.
20882 * @attribute: a file attribute key.
20883 * @attr_value: a byte string.
20885 * Sets the @attribute to contain the given @attr_value,
20891 * g_file_info_set_attribute_int32:
20892 * @info: a #GFileInfo.
20893 * @attribute: a file attribute key.
20894 * @attr_value: a signed 32-bit integer
20896 * Sets the @attribute to contain the given @attr_value,
20902 * g_file_info_set_attribute_int64:
20903 * @info: a #GFileInfo.
20904 * @attribute: attribute name to set.
20905 * @attr_value: int64 value to set attribute to.
20907 * Sets the @attribute to contain the given @attr_value,
20913 * g_file_info_set_attribute_mask:
20914 * @info: a #GFileInfo.
20915 * @mask: a #GFileAttributeMatcher.
20917 * Sets @mask on @info to match specific attribute types.
20922 * g_file_info_set_attribute_object:
20923 * @info: a #GFileInfo.
20924 * @attribute: a file attribute key.
20925 * @attr_value: a #GObject.
20927 * Sets the @attribute to contain the given @attr_value,
20933 * g_file_info_set_attribute_status:
20934 * @info: a #GFileInfo
20935 * @attribute: a file attribute key
20936 * @status: a #GFileAttributeStatus
20938 * Sets the attribute status for an attribute key. This is only
20939 * needed by external code that implement g_file_set_attributes_from_info()
20940 * or similar functions.
20942 * The attribute must exist in @info for this to work. Otherwise %FALSE
20943 * is returned and @info is unchanged.
20945 * Returns: %TRUE if the status was changed, %FALSE if the key was not set.
20951 * g_file_info_set_attribute_string:
20952 * @info: a #GFileInfo.
20953 * @attribute: a file attribute key.
20954 * @attr_value: a UTF-8 string.
20956 * Sets the @attribute to contain the given @attr_value,
20962 * g_file_info_set_attribute_stringv:
20963 * @info: a #GFileInfo.
20964 * @attribute: a file attribute key
20965 * @attr_value: (array) (element-type utf8): a %NULL terminated array of UTF-8 strings.
20967 * Sets the @attribute to contain the given @attr_value,
20975 * g_file_info_set_attribute_uint32:
20976 * @info: a #GFileInfo.
20977 * @attribute: a file attribute key.
20978 * @attr_value: an unsigned 32-bit integer.
20980 * Sets the @attribute to contain the given @attr_value,
20986 * g_file_info_set_attribute_uint64:
20987 * @info: a #GFileInfo.
20988 * @attribute: a file attribute key.
20989 * @attr_value: an unsigned 64-bit integer.
20991 * Sets the @attribute to contain the given @attr_value,
20997 * g_file_info_set_content_type:
20998 * @info: a #GFileInfo.
20999 * @content_type: a content type. See [GContentType][gio-GContentType]
21001 * Sets the content type attribute for a given #GFileInfo.
21002 * See %G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE.
21007 * g_file_info_set_display_name:
21008 * @info: a #GFileInfo.
21009 * @display_name: a string containing a display name.
21011 * Sets the display name for the current #GFileInfo.
21012 * See %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME.
21017 * g_file_info_set_edit_name:
21018 * @info: a #GFileInfo.
21019 * @edit_name: a string containing an edit name.
21021 * Sets the edit name for the current file.
21022 * See %G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME.
21027 * g_file_info_set_file_type:
21028 * @info: a #GFileInfo.
21029 * @type: a #GFileType.
21031 * Sets the file type in a #GFileInfo to @type.
21032 * See %G_FILE_ATTRIBUTE_STANDARD_TYPE.
21037 * g_file_info_set_icon:
21038 * @info: a #GFileInfo.
21041 * Sets the icon for a given #GFileInfo.
21042 * See %G_FILE_ATTRIBUTE_STANDARD_ICON.
21047 * g_file_info_set_is_hidden:
21048 * @info: a #GFileInfo.
21049 * @is_hidden: a #gboolean.
21051 * Sets the "is_hidden" attribute in a #GFileInfo according to @is_hidden.
21052 * See %G_FILE_ATTRIBUTE_STANDARD_IS_HIDDEN.
21057 * g_file_info_set_is_symlink:
21058 * @info: a #GFileInfo.
21059 * @is_symlink: a #gboolean.
21061 * Sets the "is_symlink" attribute in a #GFileInfo according to @is_symlink.
21062 * See %G_FILE_ATTRIBUTE_STANDARD_IS_SYMLINK.
21067 * g_file_info_set_modification_time:
21068 * @info: a #GFileInfo.
21069 * @mtime: a #GTimeVal.
21071 * Sets the %G_FILE_ATTRIBUTE_TIME_MODIFIED attribute in the file
21072 * info to the given time value.
21077 * g_file_info_set_name:
21078 * @info: a #GFileInfo.
21079 * @name: a string containing a name.
21081 * Sets the name attribute for the current #GFileInfo.
21082 * See %G_FILE_ATTRIBUTE_STANDARD_NAME.
21087 * g_file_info_set_size:
21088 * @info: a #GFileInfo.
21089 * @size: a #goffset containing the file's size.
21091 * Sets the %G_FILE_ATTRIBUTE_STANDARD_SIZE attribute in the file info
21092 * to the given size.
21097 * g_file_info_set_sort_order:
21098 * @info: a #GFileInfo.
21099 * @sort_order: a sort order integer.
21101 * Sets the sort order attribute in the file info structure. See
21102 * %G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER.
21107 * g_file_info_set_symbolic_icon:
21108 * @info: a #GFileInfo.
21111 * Sets the symbolic icon for a given #GFileInfo.
21112 * See %G_FILE_ATTRIBUTE_STANDARD_SYMBOLIC_ICON.
21119 * g_file_info_set_symlink_target:
21120 * @info: a #GFileInfo.
21121 * @symlink_target: a static string containing a path to a symlink target.
21123 * Sets the %G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET attribute in the file info
21124 * to the given symlink target.
21129 * g_file_info_unset_attribute_mask:
21130 * @info: #GFileInfo.
21132 * Unsets a mask set by g_file_info_set_attribute_mask(), if one
21138 * g_file_input_stream_query_info:
21139 * @stream: a #GFileInputStream.
21140 * @attributes: a file attribute query string.
21141 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
21142 * @error: a #GError location to store the error occurring, or %NULL to
21145 * Queries a file input stream the given @attributes. This function blocks
21146 * while querying the stream. For the asynchronous (non-blocking) version
21147 * of this function, see g_file_input_stream_query_info_async(). While the
21148 * stream is blocked, the stream will set the pending flag internally, and
21149 * any other operations on the stream will fail with %G_IO_ERROR_PENDING.
21151 * Returns: (transfer full): a #GFileInfo, or %NULL on error.
21156 * g_file_input_stream_query_info_async:
21157 * @stream: a #GFileInputStream.
21158 * @attributes: a file attribute query string.
21159 * @io_priority: the [I/O priority][io-priority] of the request
21160 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
21161 * @callback: (scope async): callback to call when the request is satisfied
21162 * @user_data: (closure): the data to pass to callback function
21164 * Queries the stream information asynchronously.
21165 * When the operation is finished @callback will be called.
21166 * You can then call g_file_input_stream_query_info_finish()
21167 * to get the result of the operation.
21169 * For the synchronous version of this function,
21170 * see g_file_input_stream_query_info().
21172 * If @cancellable is not %NULL, then the operation can be cancelled by
21173 * triggering the cancellable object from another thread. If the operation
21174 * was cancelled, the error %G_IO_ERROR_CANCELLED will be set
21179 * g_file_input_stream_query_info_finish:
21180 * @stream: a #GFileInputStream.
21181 * @result: a #GAsyncResult.
21182 * @error: a #GError location to store the error occurring,
21183 * or %NULL to ignore.
21185 * Finishes an asynchronous info query operation.
21187 * Returns: (transfer full): #GFileInfo.
21192 * g_file_io_stream_get_etag:
21193 * @stream: a #GFileIOStream.
21195 * Gets the entity tag for the file when it has been written.
21196 * This must be called after the stream has been written
21197 * and closed, as the etag can change while writing.
21199 * Returns: the entity tag for the stream.
21205 * g_file_io_stream_query_info:
21206 * @stream: a #GFileIOStream.
21207 * @attributes: a file attribute query string.
21208 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
21209 * @error: a #GError, %NULL to ignore.
21211 * Queries a file io stream for the given @attributes.
21212 * This function blocks while querying the stream. For the asynchronous
21213 * version of this function, see g_file_io_stream_query_info_async().
21214 * While the stream is blocked, the stream will set the pending flag
21215 * internally, and any other operations on the stream will fail with
21216 * %G_IO_ERROR_PENDING.
21218 * Can fail if the stream was already closed (with @error being set to
21219 * %G_IO_ERROR_CLOSED), the stream has pending operations (with @error being
21220 * set to %G_IO_ERROR_PENDING), or if querying info is not supported for
21221 * the stream's interface (with @error being set to %G_IO_ERROR_NOT_SUPPORTED). I
21222 * all cases of failure, %NULL will be returned.
21224 * If @cancellable is not %NULL, then the operation can be cancelled by
21225 * triggering the cancellable object from another thread. If the operation
21226 * was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %NULL will
21229 * Returns: (transfer full): a #GFileInfo for the @stream, or %NULL on error.
21235 * g_file_io_stream_query_info_async:
21236 * @stream: a #GFileIOStream.
21237 * @attributes: a file attribute query string.
21238 * @io_priority: the [I/O priority][gio-GIOScheduler] of the request
21239 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
21240 * @callback: (scope async): callback to call when the request is satisfied
21241 * @user_data: (closure): the data to pass to callback function
21243 * Asynchronously queries the @stream for a #GFileInfo. When completed,
21244 * @callback will be called with a #GAsyncResult which can be used to
21245 * finish the operation with g_file_io_stream_query_info_finish().
21247 * For the synchronous version of this function, see
21248 * g_file_io_stream_query_info().
21255 * g_file_io_stream_query_info_finish:
21256 * @stream: a #GFileIOStream.
21257 * @result: a #GAsyncResult.
21258 * @error: a #GError, %NULL to ignore.
21260 * Finalizes the asynchronous query started
21261 * by g_file_io_stream_query_info_async().
21263 * Returns: (transfer full): A #GFileInfo for the finished query.
21269 * g_file_is_native:
21270 * @file: input #GFile
21272 * Checks to see if a file is native to the platform.
21274 * A native file s one expressed in the platform-native filename format,
21275 * e.g. "C:\Windows" or "/usr/bin/". This does not mean the file is local,
21276 * as it might be on a locally mounted remote filesystem.
21278 * On some systems non-native files may be available using the native
21279 * filesystem via a userspace filesystem (FUSE), in these cases this call
21280 * will return %FALSE, but g_file_get_path() will still return a native path.
21282 * This call does no blocking I/O.
21284 * Returns: %TRUE if @file is native
21289 * g_file_load_contents:
21290 * @file: input #GFile
21291 * @cancellable: optional #GCancellable object, %NULL to ignore
21292 * @contents: (out) (transfer full) (element-type guint8) (array length=length): a location to place the contents of the file
21293 * @length: (out) (allow-none): a location to place the length of the contents of the file,
21294 * or %NULL if the length is not needed
21295 * @etag_out: (out) (allow-none): a location to place the current entity tag for the file,
21296 * or %NULL if the entity tag is not needed
21297 * @error: a #GError, or %NULL
21299 * Loads the content of the file into memory. The data is always
21300 * zero-terminated, but this is not included in the resultant @length.
21301 * The returned @content should be freed with g_free() when no longer
21304 * If @cancellable is not %NULL, then the operation can be cancelled by
21305 * triggering the cancellable object from another thread. If the operation
21306 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
21308 * Returns: %TRUE if the @file's contents were successfully loaded.
21309 * %FALSE if there were errors.
21314 * g_file_load_contents_async:
21315 * @file: input #GFile
21316 * @cancellable: optional #GCancellable object, %NULL to ignore
21317 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
21318 * @user_data: the data to pass to callback function
21320 * Starts an asynchronous load of the @file's contents.
21322 * For more details, see g_file_load_contents() which is
21323 * the synchronous version of this call.
21325 * When the load operation has completed, @callback will be called
21326 * with @user data. To finish the operation, call
21327 * g_file_load_contents_finish() with the #GAsyncResult returned by
21330 * If @cancellable is not %NULL, then the operation can be cancelled by
21331 * triggering the cancellable object from another thread. If the operation
21332 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
21337 * g_file_load_contents_finish:
21338 * @file: input #GFile
21339 * @res: a #GAsyncResult
21340 * @contents: (out) (transfer full) (element-type guint8) (array length=length): a location to place the contents of the file
21341 * @length: (out) (allow-none): a location to place the length of the contents of the file,
21342 * or %NULL if the length is not needed
21343 * @etag_out: (out) (allow-none): a location to place the current entity tag for the file,
21344 * or %NULL if the entity tag is not needed
21345 * @error: a #GError, or %NULL
21347 * Finishes an asynchronous load of the @file's contents.
21348 * The contents are placed in @contents, and @length is set to the
21349 * size of the @contents string. The @content should be freed with
21350 * g_free() when no longer needed. If @etag_out is present, it will be
21351 * set to the new entity tag for the @file.
21353 * Returns: %TRUE if the load was successful. If %FALSE and @error is
21354 * present, it will be set appropriately.
21359 * g_file_load_partial_contents_async: (skip)
21360 * @file: input #GFile
21361 * @cancellable: optional #GCancellable object, %NULL to ignore
21362 * @read_more_callback: a #GFileReadMoreCallback to receive partial data
21363 * and to specify whether further data should be read
21364 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
21365 * @user_data: the data to pass to the callback functions
21367 * Reads the partial contents of a file. A #GFileReadMoreCallback should
21368 * be used to stop reading from the file when appropriate, else this
21369 * function will behave exactly as g_file_load_contents_async(). This
21370 * operation can be finished by g_file_load_partial_contents_finish().
21372 * Users of this function should be aware that @user_data is passed to
21373 * both the @read_more_callback and the @callback.
21375 * If @cancellable is not %NULL, then the operation can be cancelled by
21376 * triggering the cancellable object from another thread. If the operation
21377 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
21382 * g_file_load_partial_contents_finish:
21383 * @file: input #GFile
21384 * @res: a #GAsyncResult
21385 * @contents: (out) (transfer full) (element-type guint8) (array length=length): a location to place the contents of the file
21386 * @length: (out) (allow-none): a location to place the length of the contents of the file,
21387 * or %NULL if the length is not needed
21388 * @etag_out: (out) (allow-none): a location to place the current entity tag for the file,
21389 * or %NULL if the entity tag is not needed
21390 * @error: a #GError, or %NULL
21392 * Finishes an asynchronous partial load operation that was started
21393 * with g_file_load_partial_contents_async(). The data is always
21394 * zero-terminated, but this is not included in the resultant @length.
21395 * The returned @content should be freed with g_free() when no longer
21398 * Returns: %TRUE if the load was successful. If %FALSE and @error is
21399 * present, it will be set appropriately.
21404 * g_file_make_directory:
21405 * @file: input #GFile
21406 * @cancellable: (allow-none): optional #GCancellable object,
21408 * @error: a #GError, or %NULL
21410 * Creates a directory. Note that this will only create a child directory
21411 * of the immediate parent directory of the path or URI given by the #GFile.
21412 * To recursively create directories, see g_file_make_directory_with_parents().
21413 * This function will fail if the parent directory does not exist, setting
21414 * @error to %G_IO_ERROR_NOT_FOUND. If the file system doesn't support
21415 * creating directories, this function will fail, setting @error to
21416 * %G_IO_ERROR_NOT_SUPPORTED.
21418 * For a local #GFile the newly created directory will have the default
21419 * (current) ownership and permissions of the current process.
21421 * If @cancellable is not %NULL, then the operation can be cancelled by
21422 * triggering the cancellable object from another thread. If the operation
21423 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
21425 * Returns: %TRUE on successful creation, %FALSE otherwise.
21430 * g_file_make_directory_async: (virtual make_directory_async)
21431 * @file: input #GFile
21432 * @io_priority: the [I/O priority][io-priority] of the request
21433 * @cancellable: (allow-none): optional #GCancellable object,
21435 * @callback: a #GAsyncReadyCallback to call
21436 * when the request is satisfied
21437 * @user_data: the data to pass to callback function
21439 * Asynchronously creates a directory.
21446 * g_file_make_directory_finish: (virtual make_directory_finish)
21447 * @file: input #GFile
21448 * @result: a #GAsyncResult
21449 * @error: a #GError, or %NULL
21451 * Finishes an asynchronous directory creation, started with
21452 * g_file_make_directory_async().
21454 * Returns: %TRUE on successful directory creation, %FALSE otherwise.
21460 * g_file_make_directory_with_parents:
21461 * @file: input #GFile
21462 * @cancellable: (allow-none): optional #GCancellable object,
21464 * @error: a #GError, or %NULL
21466 * Creates a directory and any parent directories that may not
21467 * exist similar to 'mkdir -p'. If the file system does not support
21468 * creating directories, this function will fail, setting @error to
21469 * %G_IO_ERROR_NOT_SUPPORTED. If the directory itself already exists,
21470 * this function will fail setting @error to %G_IO_ERROR_EXISTS, unlike
21471 * the similar g_mkdir_with_parents().
21473 * For a local #GFile the newly created directories will have the default
21474 * (current) ownership and permissions of the current process.
21476 * If @cancellable is not %NULL, then the operation can be cancelled by
21477 * triggering the cancellable object from another thread. If the operation
21478 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
21480 * Returns: %TRUE if all directories have been successfully created, %FALSE
21487 * g_file_make_symbolic_link:
21488 * @file: a #GFile with the name of the symlink to create
21489 * @symlink_value: a string with the path for the target of the new symlink
21490 * @cancellable: (allow-none): optional #GCancellable object,
21492 * @error: a #GError
21494 * Creates a symbolic link named @file which contains the string
21497 * If @cancellable is not %NULL, then the operation can be cancelled by
21498 * triggering the cancellable object from another thread. If the operation
21499 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
21501 * Returns: %TRUE on the creation of a new symlink, %FALSE otherwise.
21506 * g_file_measure_disk_usage:
21508 * @flags: #GFileMeasureFlags
21509 * @cancellable: (allow-none): optional #GCancellable
21510 * @progress_callback: (allow-none): a #GFileMeasureProgressCallback
21511 * @progress_data: user_data for @progress_callback
21512 * @disk_usage: (allow-none) (out): the number of bytes of disk space used
21513 * @num_dirs: (allow-none) (out): the number of directories encountered
21514 * @num_files: (allow-none) (out): the number of non-directories encountered
21515 * @error: (allow-none): %NULL, or a pointer to a %NULL #GError pointer
21517 * Recursively measures the disk usage of @file.
21519 * This is essentially an analog of the 'du' command, but it also
21520 * reports the number of directories and non-directory files encountered
21521 * (including things like symbolic links).
21523 * By default, errors are only reported against the toplevel file
21524 * itself. Errors found while recursing are silently ignored, unless
21525 * %G_FILE_DISK_USAGE_REPORT_ALL_ERRORS is given in @flags.
21527 * The returned size, @disk_usage, is in bytes and should be formatted
21528 * with g_format_size() in order to get something reasonable for showing
21529 * in a user interface.
21531 * @progress_callback and @progress_data can be given to request
21532 * periodic progress updates while scanning. See the documentation for
21533 * #GFileMeasureProgressCallback for information about when and how the
21534 * callback will be invoked.
21536 * Returns: %TRUE if successful, with the out parameters set.
21537 * %FALSE otherwise, with @error set.
21543 * g_file_measure_disk_usage_async:
21545 * @flags: #GFileMeasureFlags
21546 * @io_priority: the [I/O priority][io-priority] of the request
21547 * @cancellable: (allow-none): optional #GCancellable
21548 * @progress_callback: (allow-none): a #GFileMeasureProgressCallback
21549 * @progress_data: user_data for @progress_callback
21550 * @callback: (allow-none): a #GAsyncReadyCallback to call when complete
21551 * @user_data: the data to pass to callback function
21553 * Recursively measures the disk usage of @file.
21555 * This is the asynchronous version of g_file_measure_disk_usage(). See
21556 * there for more information.
21563 * g_file_measure_disk_usage_finish:
21565 * @result: the #GAsyncResult passed to your #GAsyncReadyCallback
21566 * @disk_usage: (allow-none) (out): the number of bytes of disk space used
21567 * @num_dirs: (allow-none) (out): the number of directories encountered
21568 * @num_files: (allow-none) (out): the number of non-directories encountered
21569 * @error: (allow-none): %NULL, or a pointer to a %NULL #GError pointer
21571 * Collects the results from an earlier call to
21572 * g_file_measure_disk_usage_async(). See g_file_measure_disk_usage() for
21573 * more information.
21575 * Returns: %TRUE if successful, with the out parameters set.
21576 * %FALSE otherwise, with @error set.
21583 * @file: input #GFile
21584 * @flags: a set of #GFileMonitorFlags
21585 * @cancellable: (allow-none): optional #GCancellable object,
21587 * @error: a #GError, or %NULL
21589 * Obtains a file or directory monitor for the given file,
21590 * depending on the type of the file.
21592 * If @cancellable is not %NULL, then the operation can be cancelled by
21593 * triggering the cancellable object from another thread. If the operation
21594 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
21596 * Returns: (transfer full): a #GFileMonitor for the given @file,
21597 * or %NULL on error.
21598 * Free the returned object with g_object_unref().
21604 * g_file_monitor_cancel:
21605 * @monitor: a #GFileMonitor.
21607 * Cancels a file monitor.
21609 * Returns: %TRUE if monitor was cancelled.
21614 * g_file_monitor_directory: (virtual monitor_dir)
21615 * @file: input #GFile
21616 * @flags: a set of #GFileMonitorFlags
21617 * @cancellable: (allow-none): optional #GCancellable object,
21619 * @error: a #GError, or %NULL
21621 * Obtains a directory monitor for the given file.
21622 * This may fail if directory monitoring is not supported.
21624 * If @cancellable is not %NULL, then the operation can be cancelled by
21625 * triggering the cancellable object from another thread. If the operation
21626 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
21628 * It does not make sense for @flags to contain
21629 * %G_FILE_MONITOR_WATCH_HARD_LINKS, since hard links can not be made to
21630 * directories. It is not possible to monitor all the files in a
21631 * directory for changes made via hard links; if you want to do this then
21632 * you must register individual watches with g_file_monitor().
21634 * Returns: (transfer full): a #GFileMonitor for the given @file,
21635 * or %NULL on error.
21636 * Free the returned object with g_object_unref().
21641 * g_file_monitor_emit_event:
21642 * @monitor: a #GFileMonitor.
21643 * @child: a #GFile.
21644 * @other_file: a #GFile.
21645 * @event_type: a set of #GFileMonitorEvent flags.
21647 * Emits the #GFileMonitor::changed signal if a change
21648 * has taken place. Should be called from file monitor
21649 * implementations only.
21651 * The signal will be emitted from an idle handler (in the
21652 * [thread-default main context][g-main-context-push-thread-default]).
21657 * g_file_monitor_file:
21658 * @file: input #GFile
21659 * @flags: a set of #GFileMonitorFlags
21660 * @cancellable: (allow-none): optional #GCancellable object,
21662 * @error: a #GError, or %NULL
21664 * Obtains a file monitor for the given file. If no file notification
21665 * mechanism exists, then regular polling of the file is used.
21667 * If @cancellable is not %NULL, then the operation can be cancelled by
21668 * triggering the cancellable object from another thread. If the operation
21669 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
21671 * If @flags contains %G_FILE_MONITOR_WATCH_HARD_LINKS then the monitor
21672 * will also attempt to report changes made to the file via another
21673 * filename (ie, a hard link). Without this flag, you can only rely on
21674 * changes made through the filename contained in @file to be
21675 * reported. Using this flag may result in an increase in resource
21676 * usage, and may not have any effect depending on the #GFileMonitor
21677 * backend and/or filesystem type.
21679 * Returns: (transfer full): a #GFileMonitor for the given @file,
21680 * or %NULL on error.
21681 * Free the returned object with g_object_unref().
21686 * g_file_monitor_is_cancelled:
21687 * @monitor: a #GFileMonitor
21689 * Returns whether the monitor is canceled.
21691 * Returns: %TRUE if monitor is canceled. %FALSE otherwise.
21696 * g_file_monitor_set_rate_limit:
21697 * @monitor: a #GFileMonitor.
21698 * @limit_msecs: a non-negative integer with the limit in milliseconds
21699 * to poll for changes
21701 * Sets the rate limit to which the @monitor will report
21702 * consecutive change events to the same file.
21707 * g_file_mount_enclosing_volume:
21708 * @location: input #GFile
21709 * @flags: flags affecting the operation
21710 * @mount_operation: (allow-none): a #GMountOperation
21711 * or %NULL to avoid user interaction
21712 * @cancellable: (allow-none): optional #GCancellable object,
21714 * @callback: (allow-none): a #GAsyncReadyCallback to call
21715 * when the request is satisfied, or %NULL
21716 * @user_data: the data to pass to callback function
21718 * Starts a @mount_operation, mounting the volume that contains
21719 * the file @location.
21721 * When this operation has completed, @callback will be called with
21722 * @user_user data, and the operation can be finalized with
21723 * g_file_mount_enclosing_volume_finish().
21725 * If @cancellable is not %NULL, then the operation can be cancelled by
21726 * triggering the cancellable object from another thread. If the operation
21727 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
21732 * g_file_mount_enclosing_volume_finish:
21733 * @location: input #GFile
21734 * @result: a #GAsyncResult
21735 * @error: a #GError, or %NULL
21737 * Finishes a mount operation started by g_file_mount_enclosing_volume().
21739 * Returns: %TRUE if successful. If an error has occurred,
21740 * this function will return %FALSE and set @error
21741 * appropriately if present.
21746 * g_file_mount_mountable:
21747 * @file: input #GFile
21748 * @flags: flags affecting the operation
21749 * @mount_operation: (allow-none): a #GMountOperation,
21750 * or %NULL to avoid user interaction
21751 * @cancellable: (allow-none): optional #GCancellable object,
21753 * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call
21754 * when the request is satisfied, or %NULL
21755 * @user_data: (closure): the data to pass to callback function
21757 * Mounts a file of type G_FILE_TYPE_MOUNTABLE.
21758 * Using @mount_operation, you can request callbacks when, for instance,
21759 * passwords are needed during authentication.
21761 * If @cancellable is not %NULL, then the operation can be cancelled by
21762 * triggering the cancellable object from another thread. If the operation
21763 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
21765 * When the operation is finished, @callback will be called.
21766 * You can then call g_file_mount_mountable_finish() to get
21767 * the result of the operation.
21772 * g_file_mount_mountable_finish:
21773 * @file: input #GFile
21774 * @result: a #GAsyncResult
21775 * @error: a #GError, or %NULL
21777 * Finishes a mount operation. See g_file_mount_mountable() for details.
21779 * Finish an asynchronous mount operation that was started
21780 * with g_file_mount_mountable().
21782 * Returns: (transfer full): a #GFile or %NULL on error.
21783 * Free the returned object with g_object_unref().
21789 * @source: #GFile pointing to the source location
21790 * @destination: #GFile pointing to the destination location
21791 * @flags: set of #GFileCopyFlags
21792 * @cancellable: (allow-none): optional #GCancellable object,
21794 * @progress_callback: (allow-none) (scope call): #GFileProgressCallback
21795 * function for updates
21796 * @progress_callback_data: (closure): gpointer to user data for
21797 * the callback function
21798 * @error: #GError for returning error conditions, or %NULL
21800 * Tries to move the file or directory @source to the location specified
21801 * by @destination. If native move operations are supported then this is
21802 * used, otherwise a copy + delete fallback is used. The native
21803 * implementation may support moving directories (for instance on moves
21804 * inside the same filesystem), but the fallback code does not.
21806 * If the flag #G_FILE_COPY_OVERWRITE is specified an already
21807 * existing @destination file is overwritten.
21809 * If the flag #G_FILE_COPY_NOFOLLOW_SYMLINKS is specified then symlinks
21810 * will be copied as symlinks, otherwise the target of the
21811 * @source symlink will be copied.
21813 * If @cancellable is not %NULL, then the operation can be cancelled by
21814 * triggering the cancellable object from another thread. If the operation
21815 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
21817 * If @progress_callback is not %NULL, then the operation can be monitored
21818 * by setting this to a #GFileProgressCallback function.
21819 * @progress_callback_data will be passed to this function. It is
21820 * guaranteed that this callback will be called after all data has been
21821 * transferred with the total number of bytes copied during the operation.
21823 * If the @source file does not exist, then the %G_IO_ERROR_NOT_FOUND
21824 * error is returned, independent on the status of the @destination.
21826 * If #G_FILE_COPY_OVERWRITE is not specified and the target exists,
21827 * then the error %G_IO_ERROR_EXISTS is returned.
21829 * If trying to overwrite a file over a directory, the %G_IO_ERROR_IS_DIRECTORY
21830 * error is returned. If trying to overwrite a directory with a directory the
21831 * %G_IO_ERROR_WOULD_MERGE error is returned.
21833 * If the source is a directory and the target does not exist, or
21834 * #G_FILE_COPY_OVERWRITE is specified and the target is a file, then
21835 * the %G_IO_ERROR_WOULD_RECURSE error may be returned (if the native
21836 * move operation isn't available).
21838 * Returns: %TRUE on successful move, %FALSE otherwise.
21843 * g_file_new_for_commandline_arg:
21844 * @arg: a command line string
21846 * Creates a #GFile with the given argument from the command line.
21847 * The value of @arg can be either a URI, an absolute path or a
21848 * relative path resolved relative to the current working directory.
21849 * This operation never fails, but the returned object might not
21850 * support any I/O operation if @arg points to a malformed path.
21852 * Note that on Windows, this function expects its argument to be in
21853 * UTF-8 -- not the system code page. This means that you
21854 * should not use this function with string from argv as it is passed
21855 * to main(). g_win32_get_command_line() will return a UTF-8 version of
21856 * the commandline. #GApplication also uses UTF-8 but
21857 * g_application_command_line_create_file_for_arg() may be more useful
21858 * for you there. It is also always possible to use this function with
21859 * #GOptionContext arguments of type %G_OPTION_ARG_FILENAME.
21861 * Returns: (transfer full): a new #GFile.
21862 * Free the returned object with g_object_unref().
21867 * g_file_new_for_commandline_arg_and_cwd:
21868 * @arg: a command line string
21869 * @cwd: the current working directory of the commandline
21871 * Creates a #GFile with the given argument from the command line.
21873 * This function is similar to g_file_new_for_commandline_arg() except
21874 * that it allows for passing the current working directory as an
21875 * argument instead of using the current working directory of the
21878 * This is useful if the commandline argument was given in a context
21879 * other than the invocation of the current process.
21881 * See also g_application_command_line_create_file_for_arg().
21883 * Returns: (transfer full): a new #GFile
21889 * g_file_new_for_path:
21890 * @path: a string containing a relative or absolute path.
21891 * The string must be encoded in the glib filename encoding.
21893 * Constructs a #GFile for a given path. This operation never
21894 * fails, but the returned object might not support any I/O
21895 * operation if @path is malformed.
21897 * Returns: (transfer full): a new #GFile for the given @path.
21898 * Free the returned object with g_object_unref().
21903 * g_file_new_for_uri:
21904 * @uri: a UTF-8 string containing a URI
21906 * Constructs a #GFile for a given URI. This operation never
21907 * fails, but the returned object might not support any I/O
21908 * operation if @uri is malformed or if the uri type is
21911 * Returns: (transfer full): a new #GFile for the given @uri.
21912 * Free the returned object with g_object_unref().
21918 * @tmpl: (type filename) (allow-none): Template for the file
21919 * name, as in g_file_open_tmp(), or %NULL for a default template
21920 * @iostream: (out): on return, a #GFileIOStream for the created file
21921 * @error: a #GError, or %NULL
21923 * Opens a file in the preferred directory for temporary files (as
21924 * returned by g_get_tmp_dir()) and returns a #GFile and
21925 * #GFileIOStream pointing to it.
21927 * @tmpl should be a string in the GLib file name encoding
21928 * containing a sequence of six 'X' characters, and containing no
21929 * directory components. If it is %NULL, a default template is used.
21931 * Unlike the other #GFile constructors, this will return %NULL if
21932 * a temporary file could not be created.
21934 * Returns: (transfer full): a new #GFile.
21935 * Free the returned object with g_object_unref().
21941 * g_file_open_readwrite:
21942 * @file: #GFile to open
21943 * @cancellable: (allow-none): a #GCancellable
21944 * @error: a #GError, or %NULL
21946 * Opens an existing file for reading and writing. The result is
21947 * a #GFileIOStream that can be used to read and write the contents
21950 * If @cancellable is not %NULL, then the operation can be cancelled
21951 * by triggering the cancellable object from another thread. If the
21952 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
21955 * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will
21956 * be returned. If the file is a directory, the %G_IO_ERROR_IS_DIRECTORY
21957 * error will be returned. Other errors are possible too, and depend on
21958 * what kind of filesystem the file is on. Note that in many non-local
21959 * file cases read and write streams are not supported, so make sure you
21960 * really need to do read and write streaming, rather than just opening
21961 * for reading or writing.
21963 * Returns: (transfer full): #GFileIOStream or %NULL on error.
21964 * Free the returned object with g_object_unref().
21970 * g_file_open_readwrite_async:
21971 * @file: input #GFile
21972 * @io_priority: the [I/O priority][io-priority] of the request
21973 * @cancellable: (allow-none): optional #GCancellable object,
21975 * @callback: (scope async): a #GAsyncReadyCallback to call
21976 * when the request is satisfied
21977 * @user_data: (closure): the data to pass to callback function
21979 * Asynchronously opens @file for reading and writing.
21981 * For more details, see g_file_open_readwrite() which is
21982 * the synchronous version of this call.
21984 * When the operation is finished, @callback will be called.
21985 * You can then call g_file_open_readwrite_finish() to get
21986 * the result of the operation.
21993 * g_file_open_readwrite_finish:
21994 * @file: input #GFile
21995 * @res: a #GAsyncResult
21996 * @error: a #GError, or %NULL
21998 * Finishes an asynchronous file read operation started with
21999 * g_file_open_readwrite_async().
22001 * Returns: (transfer full): a #GFileIOStream or %NULL on error.
22002 * Free the returned object with g_object_unref().
22008 * g_file_output_stream_get_etag:
22009 * @stream: a #GFileOutputStream.
22011 * Gets the entity tag for the file when it has been written.
22012 * This must be called after the stream has been written
22013 * and closed, as the etag can change while writing.
22015 * Returns: the entity tag for the stream.
22020 * g_file_output_stream_query_info:
22021 * @stream: a #GFileOutputStream.
22022 * @attributes: a file attribute query string.
22023 * @cancellable: optional #GCancellable object, %NULL to ignore.
22024 * @error: a #GError, %NULL to ignore.
22026 * Queries a file output stream for the given @attributes.
22027 * This function blocks while querying the stream. For the asynchronous
22028 * version of this function, see g_file_output_stream_query_info_async().
22029 * While the stream is blocked, the stream will set the pending flag
22030 * internally, and any other operations on the stream will fail with
22031 * %G_IO_ERROR_PENDING.
22033 * Can fail if the stream was already closed (with @error being set to
22034 * %G_IO_ERROR_CLOSED), the stream has pending operations (with @error being
22035 * set to %G_IO_ERROR_PENDING), or if querying info is not supported for
22036 * the stream's interface (with @error being set to %G_IO_ERROR_NOT_SUPPORTED). In
22037 * all cases of failure, %NULL will be returned.
22039 * If @cancellable is not %NULL, then the operation can be cancelled by
22040 * triggering the cancellable object from another thread. If the operation
22041 * was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %NULL will
22044 * Returns: (transfer full): a #GFileInfo for the @stream, or %NULL on error.
22049 * g_file_output_stream_query_info_async:
22050 * @stream: a #GFileOutputStream.
22051 * @attributes: a file attribute query string.
22052 * @io_priority: the [I/O priority][gio-GIOScheduler] of the request
22053 * @cancellable: optional #GCancellable object, %NULL to ignore.
22054 * @callback: callback to call when the request is satisfied
22055 * @user_data: the data to pass to callback function
22057 * Asynchronously queries the @stream for a #GFileInfo. When completed,
22058 * @callback will be called with a #GAsyncResult which can be used to
22059 * finish the operation with g_file_output_stream_query_info_finish().
22061 * For the synchronous version of this function, see
22062 * g_file_output_stream_query_info().
22067 * g_file_output_stream_query_info_finish:
22068 * @stream: a #GFileOutputStream.
22069 * @result: a #GAsyncResult.
22070 * @error: a #GError, %NULL to ignore.
22072 * Finalizes the asynchronous query started
22073 * by g_file_output_stream_query_info_async().
22075 * Returns: (transfer full): A #GFileInfo for the finished query.
22080 * g_file_parse_name:
22081 * @parse_name: a file name or path to be parsed
22083 * Constructs a #GFile with the given @parse_name (i.e. something
22084 * given by g_file_get_parse_name()). This operation never fails,
22085 * but the returned object might not support any I/O operation if
22086 * the @parse_name cannot be parsed.
22088 * Returns: (transfer full): a new #GFile.
22093 * g_file_poll_mountable:
22094 * @file: input #GFile
22095 * @cancellable: optional #GCancellable object, %NULL to ignore
22096 * @callback: (allow-none): a #GAsyncReadyCallback to call
22097 * when the request is satisfied, or %NULL
22098 * @user_data: the data to pass to callback function
22100 * Polls a file of type #G_FILE_TYPE_MOUNTABLE.
22102 * If @cancellable is not %NULL, then the operation can be cancelled by
22103 * triggering the cancellable object from another thread. If the operation
22104 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
22106 * When the operation is finished, @callback will be called.
22107 * You can then call g_file_mount_mountable_finish() to get
22108 * the result of the operation.
22115 * g_file_poll_mountable_finish:
22116 * @file: input #GFile
22117 * @result: a #GAsyncResult
22118 * @error: a #GError, or %NULL
22120 * Finishes a poll operation. See g_file_poll_mountable() for details.
22122 * Finish an asynchronous poll operation that was polled
22123 * with g_file_poll_mountable().
22125 * Returns: %TRUE if the operation finished successfully. %FALSE
22132 * g_file_query_default_handler:
22133 * @file: a #GFile to open
22134 * @cancellable: optional #GCancellable object, %NULL to ignore
22135 * @error: a #GError, or %NULL
22137 * Returns the #GAppInfo that is registered as the default
22138 * application to handle the file specified by @file.
22140 * If @cancellable is not %NULL, then the operation can be cancelled by
22141 * triggering the cancellable object from another thread. If the operation
22142 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
22144 * Returns: (transfer full): a #GAppInfo if the handle was found,
22145 * %NULL if there were errors.
22146 * When you are done with it, release it with g_object_unref()
22151 * g_file_query_exists:
22152 * @file: input #GFile
22153 * @cancellable: (allow-none): optional #GCancellable object,
22156 * Utility function to check if a particular file exists. This is
22157 * implemented using g_file_query_info() and as such does blocking I/O.
22159 * Note that in many cases it is racy to first check for file existence
22160 * and then execute something based on the outcome of that, because the
22161 * file might have been created or removed in between the operations. The
22162 * general approach to handling that is to not check, but just do the
22163 * operation and handle the errors as they come.
22165 * As an example of race-free checking, take the case of reading a file,
22166 * and if it doesn't exist, creating it. There are two racy versions: read
22167 * it, and on error create it; and: check if it exists, if not create it.
22168 * These can both result in two processes creating the file (with perhaps
22169 * a partially written file as the result). The correct approach is to
22170 * always try to create the file with g_file_create() which will either
22171 * atomically create the file or fail with a %G_IO_ERROR_EXISTS error.
22173 * However, in many cases an existence check is useful in a user interface,
22174 * for instance to make a menu item sensitive/insensitive, so that you don't
22175 * have to fool users that something is possible and then just show an error
22176 * dialog. If you do this, you should make sure to also handle the errors
22177 * that can happen due to races when you execute the operation.
22179 * Returns: %TRUE if the file exists (and can be detected without error),
22180 * %FALSE otherwise (or if cancelled).
22185 * g_file_query_file_type:
22186 * @file: input #GFile
22187 * @flags: a set of #GFileQueryInfoFlags passed to g_file_query_info()
22188 * @cancellable: (allow-none): optional #GCancellable object,
22191 * Utility function to inspect the #GFileType of a file. This is
22192 * implemented using g_file_query_info() and as such does blocking I/O.
22194 * The primary use case of this method is to check if a file is
22195 * a regular file, directory, or symlink.
22197 * Returns: The #GFileType of the file and #G_FILE_TYPE_UNKNOWN
22198 * if the file does not exist
22204 * g_file_query_filesystem_info:
22205 * @file: input #GFile
22206 * @attributes: an attribute query string
22207 * @cancellable: (allow-none): optional #GCancellable object,
22209 * @error: a #GError
22211 * Similar to g_file_query_info(), but obtains information
22212 * about the filesystem the @file is on, rather than the file itself.
22213 * For instance the amount of space available and the type of
22216 * The @attributes value is a string that specifies the attributes
22217 * that should be gathered. It is not an error if it's not possible
22218 * to read a particular requested attribute from a file - it just
22219 * won't be set. @attributes should be a comma-separated list of
22220 * attributes or attribute wildcards. The wildcard "*" means all
22221 * attributes, and a wildcard like "filesystem::*" means all attributes
22222 * in the filesystem namespace. The standard namespace for filesystem
22223 * attributes is "filesystem". Common attributes of interest are
22224 * #G_FILE_ATTRIBUTE_FILESYSTEM_SIZE (the total size of the filesystem
22225 * in bytes), #G_FILE_ATTRIBUTE_FILESYSTEM_FREE (number of bytes available),
22226 * and #G_FILE_ATTRIBUTE_FILESYSTEM_TYPE (type of the filesystem).
22228 * If @cancellable is not %NULL, then the operation can be cancelled
22229 * by triggering the cancellable object from another thread. If the
22230 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
22233 * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will
22234 * be returned. Other errors are possible too, and depend on what
22235 * kind of filesystem the file is on.
22237 * Returns: (transfer full): a #GFileInfo or %NULL if there was an error.
22238 * Free the returned object with g_object_unref().
22243 * g_file_query_filesystem_info_async:
22244 * @file: input #GFile
22245 * @attributes: an attribute query string
22246 * @io_priority: the [I/O priority][io-priority] of the request
22247 * @cancellable: (allow-none): optional #GCancellable object,
22249 * @callback: (scope async): a #GAsyncReadyCallback to call
22250 * when the request is satisfied
22251 * @user_data: (closure): the data to pass to callback function
22253 * Asynchronously gets the requested information about the filesystem
22254 * that the specified @file is on. The result is a #GFileInfo object
22255 * that contains key-value attributes (such as type or size for the
22258 * For more details, see g_file_query_filesystem_info() which is the
22259 * synchronous version of this call.
22261 * When the operation is finished, @callback will be called. You can
22262 * then call g_file_query_info_finish() to get the result of the
22268 * g_file_query_filesystem_info_finish:
22269 * @file: input #GFile
22270 * @res: a #GAsyncResult
22271 * @error: a #GError
22273 * Finishes an asynchronous filesystem info query.
22274 * See g_file_query_filesystem_info_async().
22276 * Returns: (transfer full): #GFileInfo for given @file
22277 * or %NULL on error.
22278 * Free the returned object with g_object_unref().
22283 * g_file_query_info:
22284 * @file: input #GFile
22285 * @attributes: an attribute query string
22286 * @flags: a set of #GFileQueryInfoFlags
22287 * @cancellable: (allow-none): optional #GCancellable object,
22289 * @error: a #GError
22291 * Gets the requested information about specified @file.
22292 * The result is a #GFileInfo object that contains key-value
22293 * attributes (such as the type or size of the file).
22295 * The @attributes value is a string that specifies the file
22296 * attributes that should be gathered. It is not an error if
22297 * it's not possible to read a particular requested attribute
22298 * from a file - it just won't be set. @attributes should be a
22299 * comma-separated list of attributes or attribute wildcards.
22300 * The wildcard "*" means all attributes, and a wildcard like
22301 * "standard::*" means all attributes in the standard namespace.
22302 * An example attribute query be "standard::*,owner::user".
22303 * The standard attributes are available as defines, like
22304 * #G_FILE_ATTRIBUTE_STANDARD_NAME.
22306 * If @cancellable is not %NULL, then the operation can be cancelled
22307 * by triggering the cancellable object from another thread. If the
22308 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
22311 * For symlinks, normally the information about the target of the
22312 * symlink is returned, rather than information about the symlink
22313 * itself. However if you pass #G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS
22314 * in @flags the information about the symlink itself will be returned.
22315 * Also, for symlinks that point to non-existing files the information
22316 * about the symlink itself will be returned.
22318 * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will be
22319 * returned. Other errors are possible too, and depend on what kind of
22320 * filesystem the file is on.
22322 * Returns: (transfer full): a #GFileInfo for the given @file, or %NULL
22323 * on error. Free the returned object with g_object_unref().
22328 * g_file_query_info_async:
22329 * @file: input #GFile
22330 * @attributes: an attribute query string
22331 * @flags: a set of #GFileQueryInfoFlags
22332 * @io_priority: the [I/O priority][io-priority] of the request
22333 * @cancellable: (allow-none): optional #GCancellable object,
22335 * @callback: (scope async): a #GAsyncReadyCallback to call when the
22336 * request is satisfied
22337 * @user_data: (closure): the data to pass to callback function
22339 * Asynchronously gets the requested information about specified @file.
22340 * The result is a #GFileInfo object that contains key-value attributes
22341 * (such as type or size for the file).
22343 * For more details, see g_file_query_info() which is the synchronous
22344 * version of this call.
22346 * When the operation is finished, @callback will be called. You can
22347 * then call g_file_query_info_finish() to get the result of the operation.
22352 * g_file_query_info_finish:
22353 * @file: input #GFile
22354 * @res: a #GAsyncResult
22355 * @error: a #GError
22357 * Finishes an asynchronous file info query.
22358 * See g_file_query_info_async().
22360 * Returns: (transfer full): #GFileInfo for given @file
22361 * or %NULL on error. Free the returned object with
22362 * g_object_unref().
22367 * g_file_query_settable_attributes:
22368 * @file: input #GFile
22369 * @cancellable: (allow-none): optional #GCancellable object,
22371 * @error: a #GError, or %NULL
22373 * Obtain the list of settable attributes for the file.
22375 * Returns the type and full attribute name of all the attributes
22376 * that can be set on this file. This doesn't mean setting it will
22377 * always succeed though, you might get an access failure, or some
22378 * specific file may not support a specific attribute.
22380 * If @cancellable is not %NULL, then the operation can be cancelled by
22381 * triggering the cancellable object from another thread. If the operation
22382 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
22384 * Returns: a #GFileAttributeInfoList describing the settable attributes.
22385 * When you are done with it, release it with
22386 * g_file_attribute_info_list_unref()
22391 * g_file_query_writable_namespaces:
22392 * @file: input #GFile
22393 * @cancellable: (allow-none): optional #GCancellable object,
22395 * @error: a #GError, or %NULL
22397 * Obtain the list of attribute namespaces where new attributes
22398 * can be created by a user. An example of this is extended
22399 * attributes (in the "xattr" namespace).
22401 * If @cancellable is not %NULL, then the operation can be cancelled by
22402 * triggering the cancellable object from another thread. If the operation
22403 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
22405 * Returns: a #GFileAttributeInfoList describing the writable namespaces.
22406 * When you are done with it, release it with
22407 * g_file_attribute_info_list_unref()
22412 * g_file_read: (virtual read_fn)
22413 * @file: #GFile to read
22414 * @cancellable: (allow-none): a #GCancellable
22415 * @error: a #GError, or %NULL
22417 * Opens a file for reading. The result is a #GFileInputStream that
22418 * can be used to read the contents of the file.
22420 * If @cancellable is not %NULL, then the operation can be cancelled by
22421 * triggering the cancellable object from another thread. If the operation
22422 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
22424 * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will be
22425 * returned. If the file is a directory, the %G_IO_ERROR_IS_DIRECTORY
22426 * error will be returned. Other errors are possible too, and depend
22427 * on what kind of filesystem the file is on.
22429 * Returns: (transfer full): #GFileInputStream or %NULL on error.
22430 * Free the returned object with g_object_unref().
22435 * g_file_read_async:
22436 * @file: input #GFile
22437 * @io_priority: the [I/O priority][io-priority] of the request
22438 * @cancellable: (allow-none): optional #GCancellable object,
22440 * @callback: (scope async): a #GAsyncReadyCallback to call
22441 * when the request is satisfied
22442 * @user_data: (closure): the data to pass to callback function
22444 * Asynchronously opens @file for reading.
22446 * For more details, see g_file_read() which is
22447 * the synchronous version of this call.
22449 * When the operation is finished, @callback will be called.
22450 * You can then call g_file_read_finish() to get the result
22451 * of the operation.
22456 * g_file_read_finish:
22457 * @file: input #GFile
22458 * @res: a #GAsyncResult
22459 * @error: a #GError, or %NULL
22461 * Finishes an asynchronous file read operation started with
22462 * g_file_read_async().
22464 * Returns: (transfer full): a #GFileInputStream or %NULL on error.
22465 * Free the returned object with g_object_unref().
22471 * @file: input #GFile
22472 * @etag: (allow-none): an optional [entity tag][gfile-etag]
22473 * for the current #GFile, or #NULL to ignore
22474 * @make_backup: %TRUE if a backup should be created
22475 * @flags: a set of #GFileCreateFlags
22476 * @cancellable: (allow-none): optional #GCancellable object,
22478 * @error: a #GError, or %NULL
22480 * Returns an output stream for overwriting the file, possibly
22481 * creating a backup copy of the file first. If the file doesn't exist,
22482 * it will be created.
22484 * This will try to replace the file in the safest way possible so
22485 * that any errors during the writing will not affect an already
22486 * existing copy of the file. For instance, for local files it
22487 * may write to a temporary file and then atomically rename over
22488 * the destination when the stream is closed.
22490 * By default files created are generally readable by everyone,
22491 * but if you pass #G_FILE_CREATE_PRIVATE in @flags the file
22492 * will be made readable only to the current user, to the level that
22493 * is supported on the target filesystem.
22495 * If @cancellable is not %NULL, then the operation can be cancelled
22496 * by triggering the cancellable object from another thread. If the
22497 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
22500 * If you pass in a non-%NULL @etag value, then this value is
22501 * compared to the current entity tag of the file, and if they differ
22502 * an %G_IO_ERROR_WRONG_ETAG error is returned. This generally means
22503 * that the file has been changed since you last read it. You can get
22504 * the new etag from g_file_output_stream_get_etag() after you've
22505 * finished writing and closed the #GFileOutputStream. When you load
22506 * a new file you can use g_file_input_stream_query_info() to get
22507 * the etag of the file.
22509 * If @make_backup is %TRUE, this function will attempt to make a
22510 * backup of the current file before overwriting it. If this fails
22511 * a %G_IO_ERROR_CANT_CREATE_BACKUP error will be returned. If you
22512 * want to replace anyway, try again with @make_backup set to %FALSE.
22514 * If the file is a directory the %G_IO_ERROR_IS_DIRECTORY error will
22515 * be returned, and if the file is some other form of non-regular file
22516 * then a %G_IO_ERROR_NOT_REGULAR_FILE error will be returned. Some
22517 * file systems don't allow all file names, and may return an
22518 * %G_IO_ERROR_INVALID_FILENAME error, and if the name is to long
22519 * %G_IO_ERROR_FILENAME_TOO_LONG will be returned. Other errors are
22520 * possible too, and depend on what kind of filesystem the file is on.
22522 * Returns: (transfer full): a #GFileOutputStream or %NULL on error.
22523 * Free the returned object with g_object_unref().
22528 * g_file_replace_async:
22529 * @file: input #GFile
22530 * @etag: (allow-none): an [entity tag][gfile-etag] for the current #GFile,
22531 * or %NULL to ignore
22532 * @make_backup: %TRUE if a backup should be created
22533 * @flags: a set of #GFileCreateFlags
22534 * @io_priority: the [I/O priority][io-priority] of the request
22535 * @cancellable: (allow-none): optional #GCancellable object,
22537 * @callback: (scope async): a #GAsyncReadyCallback to call
22538 * when the request is satisfied
22539 * @user_data: (closure): the data to pass to callback function
22541 * Asynchronously overwrites the file, replacing the contents,
22542 * possibly creating a backup copy of the file first.
22544 * For more details, see g_file_replace() which is
22545 * the synchronous version of this call.
22547 * When the operation is finished, @callback will be called.
22548 * You can then call g_file_replace_finish() to get the result
22549 * of the operation.
22554 * g_file_replace_contents:
22555 * @file: input #GFile
22556 * @contents: (element-type guint8) (array length=length): a string containing the new contents for @file
22557 * @length: the length of @contents in bytes
22558 * @etag: (allow-none): the old [entity-tag][gfile-etag] for the document,
22560 * @make_backup: %TRUE if a backup should be created
22561 * @flags: a set of #GFileCreateFlags
22562 * @new_etag: (allow-none) (out): a location to a new [entity tag][gfile-etag]
22563 * for the document. This should be freed with g_free() when no longer
22565 * @cancellable: optional #GCancellable object, %NULL to ignore
22566 * @error: a #GError, or %NULL
22568 * Replaces the contents of @file with @contents of @length bytes.
22570 * If @etag is specified (not %NULL), any existing file must have that etag,
22571 * or the error %G_IO_ERROR_WRONG_ETAG will be returned.
22573 * If @make_backup is %TRUE, this function will attempt to make a backup
22576 * If @cancellable is not %NULL, then the operation can be cancelled by
22577 * triggering the cancellable object from another thread. If the operation
22578 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
22580 * The returned @new_etag can be used to verify that the file hasn't
22581 * changed the next time it is saved over.
22583 * Returns: %TRUE if successful. If an error has occurred, this function
22584 * will return %FALSE and set @error appropriately if present.
22589 * g_file_replace_contents_async:
22590 * @file: input #GFile
22591 * @contents: (element-type guint8) (array length=length): string of contents to replace the file with
22592 * @length: the length of @contents in bytes
22593 * @etag: (allow-none): a new [entity tag][gfile-etag] for the @file, or %NULL
22594 * @make_backup: %TRUE if a backup should be created
22595 * @flags: a set of #GFileCreateFlags
22596 * @cancellable: optional #GCancellable object, %NULL to ignore
22597 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
22598 * @user_data: the data to pass to callback function
22600 * Starts an asynchronous replacement of @file with the given
22601 * @contents of @length bytes. @etag will replace the document's
22602 * current entity tag.
22604 * When this operation has completed, @callback will be called with
22605 * @user_user data, and the operation can be finalized with
22606 * g_file_replace_contents_finish().
22608 * If @cancellable is not %NULL, then the operation can be cancelled by
22609 * triggering the cancellable object from another thread. If the operation
22610 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
22612 * If @make_backup is %TRUE, this function will attempt to
22613 * make a backup of @file.
22615 * Note that no copy of @content will be made, so it must stay valid
22616 * until @callback is called. See g_file_replace_contents_bytes_async()
22617 * for a #GBytes version that will automatically hold a reference to the
22618 * contents (without copying) for the duration of the call.
22623 * g_file_replace_contents_bytes_async:
22624 * @file: input #GFile
22625 * @contents: a #GBytes
22626 * @etag: (allow-none): a new [entity tag][gfile-etag] for the @file, or %NULL
22627 * @make_backup: %TRUE if a backup should be created
22628 * @flags: a set of #GFileCreateFlags
22629 * @cancellable: optional #GCancellable object, %NULL to ignore
22630 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
22631 * @user_data: the data to pass to callback function
22633 * Same as g_file_replace_contents_async() but takes a #GBytes input instead.
22634 * This function will keep a ref on @contents until the operation is done.
22635 * Unlike g_file_replace_contents_async() this allows forgetting about the
22636 * content without waiting for the callback.
22638 * When this operation has completed, @callback will be called with
22639 * @user_user data, and the operation can be finalized with
22640 * g_file_replace_contents_finish().
22647 * g_file_replace_contents_finish:
22648 * @file: input #GFile
22649 * @res: a #GAsyncResult
22650 * @new_etag: (out) (allow-none): a location of a new [entity tag][gfile-etag]
22651 * for the document. This should be freed with g_free() when it is no
22652 * longer needed, or %NULL
22653 * @error: a #GError, or %NULL
22655 * Finishes an asynchronous replace of the given @file. See
22656 * g_file_replace_contents_async(). Sets @new_etag to the new entity
22657 * tag for the document, if present.
22659 * Returns: %TRUE on success, %FALSE on failure.
22664 * g_file_replace_finish:
22665 * @file: input #GFile
22666 * @res: a #GAsyncResult
22667 * @error: a #GError, or %NULL
22669 * Finishes an asynchronous file replace operation started with
22670 * g_file_replace_async().
22672 * Returns: (transfer full): a #GFileOutputStream, or %NULL on error.
22673 * Free the returned object with g_object_unref().
22678 * g_file_replace_readwrite:
22680 * @etag: (allow-none): an optional [entity tag][gfile-etag]
22681 * for the current #GFile, or #NULL to ignore
22682 * @make_backup: %TRUE if a backup should be created
22683 * @flags: a set of #GFileCreateFlags
22684 * @cancellable: (allow-none): optional #GCancellable object,
22686 * @error: return location for a #GError, or %NULL
22688 * Returns an output stream for overwriting the file in readwrite mode,
22689 * possibly creating a backup copy of the file first. If the file doesn't
22690 * exist, it will be created.
22692 * For details about the behaviour, see g_file_replace() which does the
22693 * same thing but returns an output stream only.
22695 * Note that in many non-local file cases read and write streams are not
22696 * supported, so make sure you really need to do read and write streaming,
22697 * rather than just opening for reading or writing.
22699 * Returns: (transfer full): a #GFileIOStream or %NULL on error.
22700 * Free the returned object with g_object_unref().
22706 * g_file_replace_readwrite_async:
22707 * @file: input #GFile
22708 * @etag: (allow-none): an [entity tag][gfile-etag] for the current #GFile,
22709 * or %NULL to ignore
22710 * @make_backup: %TRUE if a backup should be created
22711 * @flags: a set of #GFileCreateFlags
22712 * @io_priority: the [I/O priority][io-priority] of the request
22713 * @cancellable: (allow-none): optional #GCancellable object,
22715 * @callback: (scope async): a #GAsyncReadyCallback to call
22716 * when the request is satisfied
22717 * @user_data: (closure): the data to pass to callback function
22719 * Asynchronously overwrites the file in read-write mode,
22720 * replacing the contents, possibly creating a backup copy
22721 * of the file first.
22723 * For more details, see g_file_replace_readwrite() which is
22724 * the synchronous version of this call.
22726 * When the operation is finished, @callback will be called.
22727 * You can then call g_file_replace_readwrite_finish() to get
22728 * the result of the operation.
22735 * g_file_replace_readwrite_finish:
22736 * @file: input #GFile
22737 * @res: a #GAsyncResult
22738 * @error: a #GError, or %NULL
22740 * Finishes an asynchronous file replace operation started with
22741 * g_file_replace_readwrite_async().
22743 * Returns: (transfer full): a #GFileIOStream, or %NULL on error.
22744 * Free the returned object with g_object_unref().
22750 * g_file_resolve_relative_path:
22751 * @file: input #GFile
22752 * @relative_path: a given relative path string
22754 * Resolves a relative path for @file to an absolute path.
22756 * This call does no blocking I/O.
22758 * Returns: (transfer full): #GFile to the resolved path.
22759 * %NULL if @relative_path is %NULL or if @file is invalid.
22760 * Free the returned object with g_object_unref().
22765 * g_file_set_attribute:
22766 * @file: input #GFile
22767 * @attribute: a string containing the attribute's name
22768 * @type: The type of the attribute
22769 * @value_p: (allow-none): a pointer to the value (or the pointer
22770 * itself if the type is a pointer type)
22771 * @flags: a set of #GFileQueryInfoFlags
22772 * @cancellable: (allow-none): optional #GCancellable object,
22774 * @error: a #GError, or %NULL
22776 * Sets an attribute in the file with attribute name @attribute to @value.
22778 * Some attributes can be unset by setting @attribute to
22779 * %G_FILE_ATTRIBUTE_TYPE_INVALID and @value_p to %NULL.
22781 * If @cancellable is not %NULL, then the operation can be cancelled by
22782 * triggering the cancellable object from another thread. If the operation
22783 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
22785 * Returns: %TRUE if the attribute was set, %FALSE otherwise.
22790 * g_file_set_attribute_byte_string:
22791 * @file: input #GFile
22792 * @attribute: a string containing the attribute's name
22793 * @value: a string containing the attribute's new value
22794 * @flags: a #GFileQueryInfoFlags
22795 * @cancellable: (allow-none): optional #GCancellable object,
22797 * @error: a #GError, or %NULL
22799 * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING to @value.
22800 * If @attribute is of a different type, this operation will fail,
22801 * returning %FALSE.
22803 * If @cancellable is not %NULL, then the operation can be cancelled by
22804 * triggering the cancellable object from another thread. If the operation
22805 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
22807 * Returns: %TRUE if the @attribute was successfully set to @value
22808 * in the @file, %FALSE otherwise.
22813 * g_file_set_attribute_int32:
22814 * @file: input #GFile
22815 * @attribute: a string containing the attribute's name
22816 * @value: a #gint32 containing the attribute's new value
22817 * @flags: a #GFileQueryInfoFlags
22818 * @cancellable: (allow-none): optional #GCancellable object,
22820 * @error: a #GError, or %NULL
22822 * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT32 to @value.
22823 * If @attribute is of a different type, this operation will fail.
22825 * If @cancellable is not %NULL, then the operation can be cancelled by
22826 * triggering the cancellable object from another thread. If the operation
22827 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
22829 * Returns: %TRUE if the @attribute was successfully set to @value
22830 * in the @file, %FALSE otherwise.
22835 * g_file_set_attribute_int64:
22836 * @file: input #GFile
22837 * @attribute: a string containing the attribute's name
22838 * @value: a #guint64 containing the attribute's new value
22839 * @flags: a #GFileQueryInfoFlags
22840 * @cancellable: (allow-none): optional #GCancellable object,
22842 * @error: a #GError, or %NULL
22844 * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT64 to @value.
22845 * If @attribute is of a different type, this operation will fail.
22847 * If @cancellable is not %NULL, then the operation can be cancelled by
22848 * triggering the cancellable object from another thread. If the operation
22849 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
22851 * Returns: %TRUE if the @attribute was successfully set, %FALSE otherwise.
22856 * g_file_set_attribute_string:
22857 * @file: input #GFile
22858 * @attribute: a string containing the attribute's name
22859 * @value: a string containing the attribute's value
22860 * @flags: #GFileQueryInfoFlags
22861 * @cancellable: (allow-none): optional #GCancellable object,
22863 * @error: a #GError, or %NULL
22865 * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_STRING to @value.
22866 * If @attribute is of a different type, this operation will fail.
22868 * If @cancellable is not %NULL, then the operation can be cancelled by
22869 * triggering the cancellable object from another thread. If the operation
22870 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
22872 * Returns: %TRUE if the @attribute was successfully set, %FALSE otherwise.
22877 * g_file_set_attribute_uint32:
22878 * @file: input #GFile
22879 * @attribute: a string containing the attribute's name
22880 * @value: a #guint32 containing the attribute's new value
22881 * @flags: a #GFileQueryInfoFlags
22882 * @cancellable: (allow-none): optional #GCancellable object,
22884 * @error: a #GError, or %NULL
22886 * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT32 to @value.
22887 * If @attribute is of a different type, this operation will fail.
22889 * If @cancellable is not %NULL, then the operation can be cancelled by
22890 * triggering the cancellable object from another thread. If the operation
22891 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
22893 * Returns: %TRUE if the @attribute was successfully set to @value
22894 * in the @file, %FALSE otherwise.
22899 * g_file_set_attribute_uint64:
22900 * @file: input #GFile
22901 * @attribute: a string containing the attribute's name
22902 * @value: a #guint64 containing the attribute's new value
22903 * @flags: a #GFileQueryInfoFlags
22904 * @cancellable: (allow-none): optional #GCancellable object,
22906 * @error: a #GError, or %NULL
22908 * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT64 to @value.
22909 * If @attribute is of a different type, this operation will fail.
22911 * If @cancellable is not %NULL, then the operation can be cancelled by
22912 * triggering the cancellable object from another thread. If the operation
22913 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
22915 * Returns: %TRUE if the @attribute was successfully set to @value
22916 * in the @file, %FALSE otherwise.
22921 * g_file_set_attributes_async:
22922 * @file: input #GFile
22923 * @info: a #GFileInfo
22924 * @flags: a #GFileQueryInfoFlags
22925 * @io_priority: the [I/O priority][io-priority] of the request
22926 * @cancellable: (allow-none): optional #GCancellable object,
22928 * @callback: (scope async): a #GAsyncReadyCallback
22929 * @user_data: (closure): a #gpointer
22931 * Asynchronously sets the attributes of @file with @info.
22933 * For more details, see g_file_set_attributes_from_info(),
22934 * which is the synchronous version of this call.
22936 * When the operation is finished, @callback will be called.
22937 * You can then call g_file_set_attributes_finish() to get
22938 * the result of the operation.
22943 * g_file_set_attributes_finish:
22944 * @file: input #GFile
22945 * @result: a #GAsyncResult
22946 * @info: (out) (transfer full): a #GFileInfo
22947 * @error: a #GError, or %NULL
22949 * Finishes setting an attribute started in g_file_set_attributes_async().
22951 * Returns: %TRUE if the attributes were set correctly, %FALSE otherwise.
22956 * g_file_set_attributes_from_info:
22957 * @file: input #GFile
22958 * @info: a #GFileInfo
22959 * @flags: #GFileQueryInfoFlags
22960 * @cancellable: (allow-none): optional #GCancellable object,
22962 * @error: a #GError, or %NULL
22964 * Tries to set all attributes in the #GFileInfo on the target
22965 * values, not stopping on the first error.
22967 * If there is any error during this operation then @error will
22968 * be set to the first error. Error on particular fields are flagged
22969 * by setting the "status" field in the attribute value to
22970 * %G_FILE_ATTRIBUTE_STATUS_ERROR_SETTING, which means you can
22971 * also detect further errors.
22973 * If @cancellable is not %NULL, then the operation can be cancelled by
22974 * triggering the cancellable object from another thread. If the operation
22975 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
22977 * Returns: %FALSE if there was any error, %TRUE otherwise.
22982 * g_file_set_display_name:
22983 * @file: input #GFile
22984 * @display_name: a string
22985 * @cancellable: (allow-none): optional #GCancellable object,
22987 * @error: a #GError, or %NULL
22989 * Renames @file to the specified display name.
22991 * The display name is converted from UTF-8 to the correct encoding
22992 * for the target filesystem if possible and the @file is renamed to this.
22994 * If you want to implement a rename operation in the user interface the
22995 * edit name (#G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME) should be used as the
22996 * initial value in the rename widget, and then the result after editing
22997 * should be passed to g_file_set_display_name().
22999 * On success the resulting converted filename is returned.
23001 * If @cancellable is not %NULL, then the operation can be cancelled by
23002 * triggering the cancellable object from another thread. If the operation
23003 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
23005 * Returns: (transfer full): a #GFile specifying what @file was renamed to,
23006 * or %NULL if there was an error.
23007 * Free the returned object with g_object_unref().
23012 * g_file_set_display_name_async:
23013 * @file: input #GFile
23014 * @display_name: a string
23015 * @io_priority: the [I/O priority][io-priority] of the request
23016 * @cancellable: (allow-none): optional #GCancellable object,
23018 * @callback: (scope async): a #GAsyncReadyCallback to call
23019 * when the request is satisfied
23020 * @user_data: (closure): the data to pass to callback function
23022 * Asynchronously sets the display name for a given #GFile.
23024 * For more details, see g_file_set_display_name() which is
23025 * the synchronous version of this call.
23027 * When the operation is finished, @callback will be called.
23028 * You can then call g_file_set_display_name_finish() to get
23029 * the result of the operation.
23034 * g_file_set_display_name_finish:
23035 * @file: input #GFile
23036 * @res: a #GAsyncResult
23037 * @error: a #GError, or %NULL
23039 * Finishes setting a display name started with
23040 * g_file_set_display_name_async().
23042 * Returns: (transfer full): a #GFile or %NULL on error.
23043 * Free the returned object with g_object_unref().
23048 * g_file_start_mountable:
23049 * @file: input #GFile
23050 * @flags: flags affecting the operation
23051 * @start_operation: (allow-none): a #GMountOperation, or %NULL to avoid user interaction
23052 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
23053 * @callback: (allow-none): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL
23054 * @user_data: the data to pass to callback function
23056 * Starts a file of type #G_FILE_TYPE_MOUNTABLE.
23057 * Using @start_operation, you can request callbacks when, for instance,
23058 * passwords are needed during authentication.
23060 * If @cancellable is not %NULL, then the operation can be cancelled by
23061 * triggering the cancellable object from another thread. If the operation
23062 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
23064 * When the operation is finished, @callback will be called.
23065 * You can then call g_file_mount_mountable_finish() to get
23066 * the result of the operation.
23073 * g_file_start_mountable_finish:
23074 * @file: input #GFile
23075 * @result: a #GAsyncResult
23076 * @error: a #GError, or %NULL
23078 * Finishes a start operation. See g_file_start_mountable() for details.
23080 * Finish an asynchronous start operation that was started
23081 * with g_file_start_mountable().
23083 * Returns: %TRUE if the operation finished successfully. %FALSE
23090 * g_file_stop_mountable:
23091 * @file: input #GFile
23092 * @flags: flags affecting the operation
23093 * @mount_operation: (allow-none): a #GMountOperation,
23094 * or %NULL to avoid user interaction.
23095 * @cancellable: (allow-none): optional #GCancellable object,
23097 * @callback: (allow-none): a #GAsyncReadyCallback to call
23098 * when the request is satisfied, or %NULL
23099 * @user_data: the data to pass to callback function
23101 * Stops a file of type #G_FILE_TYPE_MOUNTABLE.
23103 * If @cancellable is not %NULL, then the operation can be cancelled by
23104 * triggering the cancellable object from another thread. If the operation
23105 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
23107 * When the operation is finished, @callback will be called.
23108 * You can then call g_file_stop_mountable_finish() to get
23109 * the result of the operation.
23116 * g_file_stop_mountable_finish:
23117 * @file: input #GFile
23118 * @result: a #GAsyncResult
23119 * @error: a #GError, or %NULL
23121 * Finishes an stop operation, see g_file_stop_mountable() for details.
23123 * Finish an asynchronous stop operation that was started
23124 * with g_file_stop_mountable().
23126 * Returns: %TRUE if the operation finished successfully.
23127 * %FALSE otherwise.
23133 * g_file_supports_thread_contexts:
23136 * Checks if @file supports
23137 * [thread-default contexts][g-main-context-push-thread-default-context].
23138 * If this returns %FALSE, you cannot perform asynchronous operations on
23139 * @file in a thread that has a thread-default context.
23141 * Returns: Whether or not @file supports thread-default contexts.
23147 * g_file_trash: (virtual trash)
23148 * @file: #GFile to send to trash
23149 * @cancellable: (allow-none): optional #GCancellable object,
23151 * @error: a #GError, or %NULL
23153 * Sends @file to the "Trashcan", if possible. This is similar to
23154 * deleting it, but the user can recover it before emptying the trashcan.
23155 * Not all file systems support trashing, so this call can return the
23156 * %G_IO_ERROR_NOT_SUPPORTED error.
23158 * If @cancellable is not %NULL, then the operation can be cancelled by
23159 * triggering the cancellable object from another thread. If the operation
23160 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
23162 * Returns: %TRUE on successful trash, %FALSE otherwise.
23167 * g_file_trash_async: (virtual trash_async)
23168 * @file: input #GFile
23169 * @io_priority: the [I/O priority][io-priority] of the request
23170 * @cancellable: (allow-none): optional #GCancellable object,
23172 * @callback: a #GAsyncReadyCallback to call
23173 * when the request is satisfied
23174 * @user_data: the data to pass to callback function
23176 * Asynchronously sends @file to the Trash location, if possible.
23183 * g_file_trash_finish: (virtual trash_finish)
23184 * @file: input #GFile
23185 * @result: a #GAsyncResult
23186 * @error: a #GError, or %NULL
23188 * Finishes an asynchronous file trashing operation, started with
23189 * g_file_trash_async().
23191 * Returns: %TRUE on successful trash, %FALSE otherwise.
23197 * g_file_unmount_mountable:
23198 * @file: input #GFile
23199 * @flags: flags affecting the operation
23200 * @cancellable: (allow-none): optional #GCancellable object,
23202 * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call
23203 * when the request is satisfied, or %NULL
23204 * @user_data: (closure): the data to pass to callback function
23206 * Unmounts a file of type G_FILE_TYPE_MOUNTABLE.
23208 * If @cancellable is not %NULL, then the operation can be cancelled by
23209 * triggering the cancellable object from another thread. If the operation
23210 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
23212 * When the operation is finished, @callback will be called.
23213 * You can then call g_file_unmount_mountable_finish() to get
23214 * the result of the operation.
23216 * Deprecated: 2.22: Use g_file_unmount_mountable_with_operation() instead.
23221 * g_file_unmount_mountable_finish:
23222 * @file: input #GFile
23223 * @result: a #GAsyncResult
23224 * @error: a #GError, or %NULL
23226 * Finishes an unmount operation, see g_file_unmount_mountable() for details.
23228 * Finish an asynchronous unmount operation that was started
23229 * with g_file_unmount_mountable().
23231 * Returns: %TRUE if the operation finished successfully.
23232 * %FALSE otherwise.
23233 * Deprecated: 2.22: Use g_file_unmount_mountable_with_operation_finish()
23239 * g_file_unmount_mountable_with_operation:
23240 * @file: input #GFile
23241 * @flags: flags affecting the operation
23242 * @mount_operation: (allow-none): a #GMountOperation,
23243 * or %NULL to avoid user interaction
23244 * @cancellable: (allow-none): optional #GCancellable object,
23246 * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call
23247 * when the request is satisfied, or %NULL
23248 * @user_data: (closure): the data to pass to callback function
23250 * Unmounts a file of type #G_FILE_TYPE_MOUNTABLE.
23252 * If @cancellable is not %NULL, then the operation can be cancelled by
23253 * triggering the cancellable object from another thread. If the operation
23254 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
23256 * When the operation is finished, @callback will be called.
23257 * You can then call g_file_unmount_mountable_finish() to get
23258 * the result of the operation.
23265 * g_file_unmount_mountable_with_operation_finish:
23266 * @file: input #GFile
23267 * @result: a #GAsyncResult
23268 * @error: a #GError, or %NULL
23270 * Finishes an unmount operation,
23271 * see g_file_unmount_mountable_with_operation() for details.
23273 * Finish an asynchronous unmount operation that was started
23274 * with g_file_unmount_mountable_with_operation().
23276 * Returns: %TRUE if the operation finished successfully.
23277 * %FALSE otherwise.
23283 * g_filename_completer_get_completion_suffix:
23284 * @completer: the filename completer.
23285 * @initial_text: text to be completed.
23287 * Obtains a completion for @initial_text from @completer.
23289 * Returns: a completed string, or %NULL if no completion exists.
23290 * This string is not owned by GIO, so remember to g_free() it
23296 * g_filename_completer_get_completions:
23297 * @completer: the filename completer.
23298 * @initial_text: text to be completed.
23300 * Gets an array of completion strings for a given initial text.
23302 * Returns: (array zero-terminated=1) (transfer full): array of strings with possible completions for @initial_text.
23303 * This array must be freed by g_strfreev() when finished.
23308 * g_filename_completer_new:
23310 * Creates a new filename completer.
23312 * Returns: a #GFilenameCompleter.
23317 * g_filename_completer_set_dirs_only:
23318 * @completer: the filename completer.
23319 * @dirs_only: a #gboolean.
23321 * If @dirs_only is %TRUE, @completer will only
23322 * complete directory names, and not file names.
23327 * g_filter_input_stream_get_base_stream:
23328 * @stream: a #GFilterInputStream.
23330 * Gets the base stream for the filter stream.
23332 * Returns: (transfer none): a #GInputStream.
23337 * g_filter_input_stream_get_close_base_stream:
23338 * @stream: a #GFilterInputStream.
23340 * Returns whether the base stream will be closed when @stream is
23343 * Returns: %TRUE if the base stream will be closed.
23348 * g_filter_input_stream_set_close_base_stream:
23349 * @stream: a #GFilterInputStream.
23350 * @close_base: %TRUE to close the base stream.
23352 * Sets whether the base stream will be closed when @stream is closed.
23357 * g_filter_output_stream_get_base_stream:
23358 * @stream: a #GFilterOutputStream.
23360 * Gets the base stream for the filter stream.
23362 * Returns: (transfer none): a #GOutputStream.
23367 * g_filter_output_stream_get_close_base_stream:
23368 * @stream: a #GFilterOutputStream.
23370 * Returns whether the base stream will be closed when @stream is
23373 * Returns: %TRUE if the base stream will be closed.
23378 * g_filter_output_stream_set_close_base_stream:
23379 * @stream: a #GFilterOutputStream.
23380 * @close_base: %TRUE to close the base stream.
23382 * Sets whether the base stream will be closed when @stream is closed.
23387 * g_icon_deserialize:
23388 * @value: a #GVariant created with g_icon_serialize()
23390 * Deserializes a #GIcon previously serialized using g_icon_serialize().
23392 * Returns: (transfer full): a #GIcon, or %NULL when deserialization fails.
23399 * @icon1: (allow-none): pointer to the first #GIcon.
23400 * @icon2: (allow-none): pointer to the second #GIcon.
23402 * Checks if two icons are equal.
23404 * Returns: %TRUE if @icon1 is equal to @icon2. %FALSE otherwise.
23409 * g_icon_hash: (virtual hash)
23410 * @icon: #gconstpointer to an icon object.
23412 * Gets a hash for an icon.
23414 * Returns: a #guint containing a hash for the @icon, suitable for
23415 * use in a #GHashTable or similar data structure.
23420 * g_icon_new_for_string:
23421 * @str: A string obtained via g_icon_to_string().
23422 * @error: Return location for error.
23424 * Generate a #GIcon instance from @str. This function can fail if
23425 * @str is not valid - see g_icon_to_string() for discussion.
23427 * If your application or library provides one or more #GIcon
23428 * implementations you need to ensure that each #GType is registered
23429 * with the type system prior to calling g_icon_new_for_string().
23431 * Returns: (transfer full): An object implementing the #GIcon
23432 * interface or %NULL if @error is set.
23438 * g_icon_serialize:
23441 * Serializes a #GIcon into a #GVariant. An equivalent #GIcon can be retrieved
23442 * back by calling g_icon_deserialize() on the returned value.
23443 * As serialization will avoid using raw icon data when possible, it only
23444 * makes sense to transfer the #GVariant between processes on the same machine,
23445 * (as opposed to over the network), and within the same file system namespace.
23447 * Returns: (transfer full): a #GVariant, or %NULL when serialization fails.
23453 * g_icon_to_string: (virtual to_tokens)
23456 * Generates a textual representation of @icon that can be used for
23457 * serialization such as when passing @icon to a different process or
23458 * saving it to persistent storage. Use g_icon_new_for_string() to
23459 * get @icon back from the returned string.
23461 * The encoding of the returned string is proprietary to #GIcon except
23462 * in the following two cases
23464 * - If @icon is a #GFileIcon, the returned string is a native path
23465 * (such as `/path/to/my icon.png`) without escaping
23466 * if the #GFile for @icon is a native file. If the file is not
23467 * native, the returned string is the result of g_file_get_uri()
23468 * (such as `sftp://path/to/my%20icon.png`).
23470 * - If @icon is a #GThemedIcon with exactly one name, the encoding is
23471 * simply the name (such as `network-server`).
23473 * Returns: (nullable): An allocated NUL-terminated UTF8 string or
23474 * %NULL if @icon can't be serialized. Use g_free() to free.
23480 * g_inet_address_equal:
23481 * @address: A #GInetAddress.
23482 * @other_address: Another #GInetAddress.
23484 * Checks if two #GInetAddress instances are equal, e.g. the same address.
23486 * Returns: %TRUE if @address and @other_address are equal, %FALSE otherwise.
23492 * g_inet_address_get_family:
23493 * @address: a #GInetAddress
23495 * Gets @address's family
23497 * Returns: @address's family
23503 * g_inet_address_get_is_any:
23504 * @address: a #GInetAddress
23506 * Tests whether @address is the "any" address for its family.
23508 * Returns: %TRUE if @address is the "any" address for its family.
23514 * g_inet_address_get_is_link_local:
23515 * @address: a #GInetAddress
23517 * Tests whether @address is a link-local address (that is, if it
23518 * identifies a host on a local network that is not connected to the
23521 * Returns: %TRUE if @address is a link-local address.
23527 * g_inet_address_get_is_loopback:
23528 * @address: a #GInetAddress
23530 * Tests whether @address is the loopback address for its family.
23532 * Returns: %TRUE if @address is the loopback address for its family.
23538 * g_inet_address_get_is_mc_global:
23539 * @address: a #GInetAddress
23541 * Tests whether @address is a global multicast address.
23543 * Returns: %TRUE if @address is a global multicast address.
23549 * g_inet_address_get_is_mc_link_local:
23550 * @address: a #GInetAddress
23552 * Tests whether @address is a link-local multicast address.
23554 * Returns: %TRUE if @address is a link-local multicast address.
23560 * g_inet_address_get_is_mc_node_local:
23561 * @address: a #GInetAddress
23563 * Tests whether @address is a node-local multicast address.
23565 * Returns: %TRUE if @address is a node-local multicast address.
23571 * g_inet_address_get_is_mc_org_local:
23572 * @address: a #GInetAddress
23574 * Tests whether @address is an organization-local multicast address.
23576 * Returns: %TRUE if @address is an organization-local multicast address.
23582 * g_inet_address_get_is_mc_site_local:
23583 * @address: a #GInetAddress
23585 * Tests whether @address is a site-local multicast address.
23587 * Returns: %TRUE if @address is a site-local multicast address.
23593 * g_inet_address_get_is_multicast:
23594 * @address: a #GInetAddress
23596 * Tests whether @address is a multicast address.
23598 * Returns: %TRUE if @address is a multicast address.
23604 * g_inet_address_get_is_site_local:
23605 * @address: a #GInetAddress
23607 * Tests whether @address is a site-local address such as 10.0.0.1
23608 * (that is, the address identifies a host on a local network that can
23609 * not be reached directly from the Internet, but which may have
23610 * outgoing Internet connectivity via a NAT or firewall).
23612 * Returns: %TRUE if @address is a site-local address.
23618 * g_inet_address_get_native_size:
23619 * @address: a #GInetAddress
23621 * Gets the size of the native raw binary address for @address. This
23622 * is the size of the data that you get from g_inet_address_to_bytes().
23624 * Returns: the number of bytes used for the native version of @address.
23630 * g_inet_address_mask_equal:
23631 * @mask: a #GInetAddressMask
23632 * @mask2: another #GInetAddressMask
23634 * Tests if @mask and @mask2 are the same mask.
23636 * Returns: whether @mask and @mask2 are the same mask
23642 * g_inet_address_mask_get_address:
23643 * @mask: a #GInetAddressMask
23645 * Gets @mask's base address
23647 * Returns: (transfer none): @mask's base address
23653 * g_inet_address_mask_get_family:
23654 * @mask: a #GInetAddressMask
23656 * Gets the #GSocketFamily of @mask's address
23658 * Returns: the #GSocketFamily of @mask's address
23664 * g_inet_address_mask_get_length:
23665 * @mask: a #GInetAddressMask
23667 * Gets @mask's length
23669 * Returns: @mask's length
23675 * g_inet_address_mask_matches:
23676 * @mask: a #GInetAddressMask
23677 * @address: a #GInetAddress
23679 * Tests if @address falls within the range described by @mask.
23681 * Returns: whether @address falls within the range described by
23688 * g_inet_address_mask_new:
23689 * @addr: a #GInetAddress
23690 * @length: number of bits of @addr to use
23691 * @error: return location for #GError, or %NULL
23693 * Creates a new #GInetAddressMask representing all addresses whose
23694 * first @length bits match @addr.
23696 * Returns: a new #GInetAddressMask, or %NULL on error
23702 * g_inet_address_mask_new_from_string:
23703 * @mask_string: an IP address or address/length string
23704 * @error: return location for #GError, or %NULL
23706 * Parses @mask_string as an IP address and (optional) length, and
23707 * creates a new #GInetAddressMask. The length, if present, is
23708 * delimited by a "/". If it is not present, then the length is
23709 * assumed to be the full length of the address.
23711 * Returns: a new #GInetAddressMask corresponding to @string, or %NULL
23718 * g_inet_address_mask_to_string:
23719 * @mask: a #GInetAddressMask
23721 * Converts @mask back to its corresponding string form.
23723 * Returns: a string corresponding to @mask.
23729 * g_inet_address_new_any:
23730 * @family: the address family
23732 * Creates a #GInetAddress for the "any" address (unassigned/"don't
23733 * care") for @family.
23735 * Returns: a new #GInetAddress corresponding to the "any" address
23742 * g_inet_address_new_from_bytes:
23743 * @bytes: (array) (element-type guint8): raw address data
23744 * @family: the address family of @bytes
23746 * Creates a new #GInetAddress from the given @family and @bytes.
23747 * @bytes should be 4 bytes for %G_SOCKET_FAMILY_IPV4 and 16 bytes for
23748 * %G_SOCKET_FAMILY_IPV6.
23750 * Returns: a new #GInetAddress corresponding to @family and @bytes.
23756 * g_inet_address_new_from_string:
23757 * @string: a string representation of an IP address
23759 * Parses @string as an IP address and creates a new #GInetAddress.
23761 * Returns: a new #GInetAddress corresponding to @string, or %NULL if
23762 * @string could not be parsed.
23768 * g_inet_address_new_loopback:
23769 * @family: the address family
23771 * Creates a #GInetAddress for the loopback address for @family.
23773 * Returns: a new #GInetAddress corresponding to the loopback address
23780 * g_inet_address_to_bytes: (skip)
23781 * @address: a #GInetAddress
23783 * Gets the raw binary address data from @address.
23785 * Returns: a pointer to an internal array of the bytes in @address,
23786 * which should not be modified, stored, or freed. The size of this
23787 * array can be gotten with g_inet_address_get_native_size().
23793 * g_inet_address_to_string:
23794 * @address: a #GInetAddress
23796 * Converts @address to string form.
23798 * Returns: a representation of @address as a string, which should be
23805 * g_inet_socket_address_get_address:
23806 * @address: a #GInetSocketAddress
23808 * Gets @address's #GInetAddress.
23810 * Returns: (transfer none): the #GInetAddress for @address, which must be
23811 * g_object_ref()'d if it will be stored
23817 * g_inet_socket_address_get_flowinfo:
23818 * @address: a %G_SOCKET_FAMILY_IPV6 #GInetSocketAddress
23820 * Gets the `sin6_flowinfo` field from @address,
23821 * which must be an IPv6 address.
23823 * Returns: the flowinfo field
23829 * g_inet_socket_address_get_port:
23830 * @address: a #GInetSocketAddress
23832 * Gets @address's port.
23834 * Returns: the port for @address
23840 * g_inet_socket_address_get_scope_id:
23841 * @address: a %G_SOCKET_FAMILY_IPV6 #GInetAddress
23843 * Gets the `sin6_scope_id` field from @address,
23844 * which must be an IPv6 address.
23846 * Returns: the scope id field
23852 * g_inet_socket_address_new:
23853 * @address: a #GInetAddress
23854 * @port: a port number
23856 * Creates a new #GInetSocketAddress for @address and @port.
23858 * Returns: a new #GInetSocketAddress
23864 * g_inet_socket_address_new_from_string:
23865 * @address: the string form of an IP address
23866 * @port: a port number
23868 * Creates a new #GInetSocketAddress for @address and @port.
23870 * If @address is an IPv6 address, it can also contain a scope ID
23871 * (separated from the address by a "<literal>%</literal>").
23873 * Returns: a new #GInetSocketAddress, or %NULL if @address cannot be
23881 * @initable: a #GInitable.
23882 * @cancellable: optional #GCancellable object, %NULL to ignore.
23883 * @error: a #GError location to store the error occurring, or %NULL to
23886 * Initializes the object implementing the interface.
23888 * The object must be initialized before any real use after initial
23889 * construction, either with this function or g_async_initable_init_async().
23891 * Implementations may also support cancellation. If @cancellable is not %NULL,
23892 * then initialization can be cancelled by triggering the cancellable object
23893 * from another thread. If the operation was cancelled, the error
23894 * %G_IO_ERROR_CANCELLED will be returned. If @cancellable is not %NULL and
23895 * the object doesn't support cancellable initialization the error
23896 * %G_IO_ERROR_NOT_SUPPORTED will be returned.
23898 * If the object is not initialized, or initialization returns with an
23899 * error, then all operations on the object except g_object_ref() and
23900 * g_object_unref() are considered to be invalid, and have undefined
23901 * behaviour. See the [introduction][ginitable] for more details.
23903 * Implementations of this method must be idempotent, i.e. multiple calls
23904 * to this function with the same argument should return the same results.
23905 * Only the first call initializes the object, further calls return the result
23906 * of the first call. This is so that it's safe to implement the singleton
23907 * pattern in the GObject constructor function.
23909 * Returns: %TRUE if successful. If an error has occurred, this function will
23910 * return %FALSE and set @error appropriately if present.
23917 * @object_type: a #GType supporting #GInitable.
23918 * @cancellable: optional #GCancellable object, %NULL to ignore.
23919 * @error: a #GError location to store the error occurring, or %NULL to
23921 * @first_property_name: (allow-none): the name of the first property, or %NULL if no
23923 * @...: the value if the first property, followed by and other property
23924 * value pairs, and ended by %NULL.
23926 * Helper function for constructing #GInitable object. This is
23927 * similar to g_object_new() but also initializes the object
23928 * and returns %NULL, setting an error on failure.
23930 * Returns: (type GObject.Object) (transfer full): a newly allocated
23931 * #GObject, or %NULL on error
23937 * g_initable_new_valist:
23938 * @object_type: a #GType supporting #GInitable.
23939 * @first_property_name: the name of the first property, followed by
23940 * the value, and other property value pairs, and ended by %NULL.
23941 * @var_args: The var args list generated from @first_property_name.
23942 * @cancellable: optional #GCancellable object, %NULL to ignore.
23943 * @error: a #GError location to store the error occurring, or %NULL to
23946 * Helper function for constructing #GInitable object. This is
23947 * similar to g_object_new_valist() but also initializes the object
23948 * and returns %NULL, setting an error on failure.
23950 * Returns: (type GObject.Object) (transfer full): a newly allocated
23951 * #GObject, or %NULL on error
23958 * @object_type: a #GType supporting #GInitable.
23959 * @n_parameters: the number of parameters in @parameters
23960 * @parameters: (array length=n_parameters): the parameters to use to construct the object
23961 * @cancellable: optional #GCancellable object, %NULL to ignore.
23962 * @error: a #GError location to store the error occurring, or %NULL to
23965 * Helper function for constructing #GInitable object. This is
23966 * similar to g_object_newv() but also initializes the object
23967 * and returns %NULL, setting an error on failure.
23969 * Returns: (type GObject.Object) (transfer full): a newly allocated
23970 * #GObject, or %NULL on error
23976 * g_input_stream_async_read_is_via_threads:
23977 * @stream: input stream
23979 * Checks if an input stream's read_async function uses threads.
23981 * Returns: %TRUE if @stream's read_async function uses threads.
23986 * g_input_stream_clear_pending:
23987 * @stream: input stream
23989 * Clears the pending flag on @stream.
23994 * g_input_stream_close:
23995 * @stream: A #GInputStream.
23996 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
23997 * @error: location to store the error occurring, or %NULL to ignore
23999 * Closes the stream, releasing resources related to it.
24001 * Once the stream is closed, all other operations will return %G_IO_ERROR_CLOSED.
24002 * Closing a stream multiple times will not return an error.
24004 * Streams will be automatically closed when the last reference
24005 * is dropped, but you might want to call this function to make sure
24006 * resources are released as early as possible.
24008 * Some streams might keep the backing store of the stream (e.g. a file descriptor)
24009 * open after the stream is closed. See the documentation for the individual
24010 * stream for details.
24012 * On failure the first error that happened will be reported, but the close
24013 * operation will finish as much as possible. A stream that failed to
24014 * close will still return %G_IO_ERROR_CLOSED for all operations. Still, it
24015 * is important to check and report the error to the user.
24017 * If @cancellable is not %NULL, then the operation can be cancelled by
24018 * triggering the cancellable object from another thread. If the operation
24019 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
24020 * Cancelling a close will still leave the stream closed, but some streams
24021 * can use a faster close that doesn't block to e.g. check errors.
24023 * Returns: %TRUE on success, %FALSE on failure
24028 * g_input_stream_close_async:
24029 * @stream: A #GInputStream.
24030 * @io_priority: the [I/O priority][io-priority] of the request
24031 * @cancellable: (allow-none): optional cancellable object
24032 * @callback: (scope async): callback to call when the request is satisfied
24033 * @user_data: (closure): the data to pass to callback function
24035 * Requests an asynchronous closes of the stream, releasing resources related to it.
24036 * When the operation is finished @callback will be called.
24037 * You can then call g_input_stream_close_finish() to get the result of the
24040 * For behaviour details see g_input_stream_close().
24042 * The asyncronous methods have a default fallback that uses threads to implement
24043 * asynchronicity, so they are optional for inheriting classes. However, if you
24044 * override one you must override all.
24049 * g_input_stream_close_finish:
24050 * @stream: a #GInputStream.
24051 * @result: a #GAsyncResult.
24052 * @error: a #GError location to store the error occurring, or %NULL to
24055 * Finishes closing a stream asynchronously, started from g_input_stream_close_async().
24057 * Returns: %TRUE if the stream was closed successfully.
24062 * g_input_stream_has_pending:
24063 * @stream: input stream.
24065 * Checks if an input stream has pending actions.
24067 * Returns: %TRUE if @stream has pending actions.
24072 * g_input_stream_is_closed:
24073 * @stream: input stream.
24075 * Checks if an input stream is closed.
24077 * Returns: %TRUE if the stream is closed.
24082 * g_input_stream_read:
24083 * @stream: a #GInputStream.
24084 * @buffer: (array length=count) (element-type guint8): a buffer to
24085 * read data into (which should be at least count bytes long).
24086 * @count: the number of bytes that will be read from the stream
24087 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
24088 * @error: location to store the error occurring, or %NULL to ignore
24090 * Tries to read @count bytes from the stream into the buffer starting at
24091 * @buffer. Will block during this read.
24093 * If count is zero returns zero and does nothing. A value of @count
24094 * larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
24096 * On success, the number of bytes read into the buffer is returned.
24097 * It is not an error if this is not the same as the requested size, as it
24098 * can happen e.g. near the end of a file. Zero is returned on end of file
24099 * (or if @count is zero), but never otherwise.
24101 * The returned @buffer is not a nul-terminated string, it can contain nul bytes
24102 * at any position, and this function doesn't nul-terminate the @buffer.
24104 * If @cancellable is not %NULL, then the operation can be cancelled by
24105 * triggering the cancellable object from another thread. If the operation
24106 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
24107 * operation was partially finished when the operation was cancelled the
24108 * partial result will be returned, without an error.
24110 * On error -1 is returned and @error is set accordingly.
24112 * Returns: Number of bytes read, or -1 on error, or 0 on end of file.
24117 * g_input_stream_read_all:
24118 * @stream: a #GInputStream.
24119 * @buffer: (array length=count) (element-type guint8): a buffer to
24120 * read data into (which should be at least count bytes long).
24121 * @count: the number of bytes that will be read from the stream
24122 * @bytes_read: (out): location to store the number of bytes that was read from the stream
24123 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
24124 * @error: location to store the error occurring, or %NULL to ignore
24126 * Tries to read @count bytes from the stream into the buffer starting at
24127 * @buffer. Will block during this read.
24129 * This function is similar to g_input_stream_read(), except it tries to
24130 * read as many bytes as requested, only stopping on an error or end of stream.
24132 * On a successful read of @count bytes, or if we reached the end of the
24133 * stream, %TRUE is returned, and @bytes_read is set to the number of bytes
24134 * read into @buffer.
24136 * If there is an error during the operation %FALSE is returned and @error
24137 * is set to indicate the error status, @bytes_read is updated to contain
24138 * the number of bytes read into @buffer before the error occurred.
24140 * Returns: %TRUE on success, %FALSE if there was an error
24145 * g_input_stream_read_async:
24146 * @stream: A #GInputStream.
24147 * @buffer: (array length=count) (element-type guint8): a buffer to
24148 * read data into (which should be at least count bytes long).
24149 * @count: the number of bytes that will be read from the stream
24150 * @io_priority: the [I/O priority][io-priority]
24152 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
24153 * @callback: (scope async): callback to call when the request is satisfied
24154 * @user_data: (closure): the data to pass to callback function
24156 * Request an asynchronous read of @count bytes from the stream into the buffer
24157 * starting at @buffer. When the operation is finished @callback will be called.
24158 * You can then call g_input_stream_read_finish() to get the result of the
24161 * During an async request no other sync and async calls are allowed on @stream, and will
24162 * result in %G_IO_ERROR_PENDING errors.
24164 * A value of @count larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
24166 * On success, the number of bytes read into the buffer will be passed to the
24167 * callback. It is not an error if this is not the same as the requested size, as it
24168 * can happen e.g. near the end of a file, but generally we try to read
24169 * as many bytes as requested. Zero is returned on end of file
24170 * (or if @count is zero), but never otherwise.
24172 * Any outstanding i/o request with higher priority (lower numerical value) will
24173 * be executed before an outstanding request with lower priority. Default
24174 * priority is %G_PRIORITY_DEFAULT.
24176 * The asyncronous methods have a default fallback that uses threads to implement
24177 * asynchronicity, so they are optional for inheriting classes. However, if you
24178 * override one you must override all.
24183 * g_input_stream_read_bytes:
24184 * @stream: a #GInputStream.
24185 * @count: maximum number of bytes that will be read from the stream. Common
24186 * values include 4096 and 8192.
24187 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
24188 * @error: location to store the error occurring, or %NULL to ignore
24190 * Like g_input_stream_read(), this tries to read @count bytes from
24191 * the stream in a blocking fashion. However, rather than reading into
24192 * a user-supplied buffer, this will create a new #GBytes containing
24193 * the data that was read. This may be easier to use from language
24196 * If count is zero, returns a zero-length #GBytes and does nothing. A
24197 * value of @count larger than %G_MAXSSIZE will cause a
24198 * %G_IO_ERROR_INVALID_ARGUMENT error.
24200 * On success, a new #GBytes is returned. It is not an error if the
24201 * size of this object is not the same as the requested size, as it
24202 * can happen e.g. near the end of a file. A zero-length #GBytes is
24203 * returned on end of file (or if @count is zero), but never
24206 * If @cancellable is not %NULL, then the operation can be cancelled by
24207 * triggering the cancellable object from another thread. If the operation
24208 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
24209 * operation was partially finished when the operation was cancelled the
24210 * partial result will be returned, without an error.
24212 * On error %NULL is returned and @error is set accordingly.
24214 * Returns: a new #GBytes, or %NULL on error
24220 * g_input_stream_read_bytes_async:
24221 * @stream: A #GInputStream.
24222 * @count: the number of bytes that will be read from the stream
24223 * @io_priority: the [I/O priority][io-priority] of the request
24224 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
24225 * @callback: (scope async): callback to call when the request is satisfied
24226 * @user_data: (closure): the data to pass to callback function
24228 * Request an asynchronous read of @count bytes from the stream into a
24229 * new #GBytes. When the operation is finished @callback will be
24230 * called. You can then call g_input_stream_read_bytes_finish() to get the
24231 * result of the operation.
24233 * During an async request no other sync and async calls are allowed
24234 * on @stream, and will result in %G_IO_ERROR_PENDING errors.
24236 * A value of @count larger than %G_MAXSSIZE will cause a
24237 * %G_IO_ERROR_INVALID_ARGUMENT error.
24239 * On success, the new #GBytes will be passed to the callback. It is
24240 * not an error if this is smaller than the requested size, as it can
24241 * happen e.g. near the end of a file, but generally we try to read as
24242 * many bytes as requested. Zero is returned on end of file (or if
24243 * @count is zero), but never otherwise.
24245 * Any outstanding I/O request with higher priority (lower numerical
24246 * value) will be executed before an outstanding request with lower
24247 * priority. Default priority is %G_PRIORITY_DEFAULT.
24254 * g_input_stream_read_bytes_finish:
24255 * @stream: a #GInputStream.
24256 * @result: a #GAsyncResult.
24257 * @error: a #GError location to store the error occurring, or %NULL to
24260 * Finishes an asynchronous stream read-into-#GBytes operation.
24262 * Returns: the newly-allocated #GBytes, or %NULL on error
24268 * g_input_stream_read_finish:
24269 * @stream: a #GInputStream.
24270 * @result: a #GAsyncResult.
24271 * @error: a #GError location to store the error occurring, or %NULL to
24274 * Finishes an asynchronous stream read operation.
24276 * Returns: number of bytes read in, or -1 on error, or 0 on end of file.
24281 * g_input_stream_set_pending:
24282 * @stream: input stream
24283 * @error: a #GError location to store the error occurring, or %NULL to
24286 * Sets @stream to have actions pending. If the pending flag is
24287 * already set or @stream is closed, it will return %FALSE and set
24290 * Returns: %TRUE if pending was previously unset and is now set.
24295 * g_input_stream_skip:
24296 * @stream: a #GInputStream.
24297 * @count: the number of bytes that will be skipped from the stream
24298 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
24299 * @error: location to store the error occurring, or %NULL to ignore
24301 * Tries to skip @count bytes from the stream. Will block during the operation.
24303 * This is identical to g_input_stream_read(), from a behaviour standpoint,
24304 * but the bytes that are skipped are not returned to the user. Some
24305 * streams have an implementation that is more efficient than reading the data.
24307 * This function is optional for inherited classes, as the default implementation
24308 * emulates it using read.
24310 * If @cancellable is not %NULL, then the operation can be cancelled by
24311 * triggering the cancellable object from another thread. If the operation
24312 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
24313 * operation was partially finished when the operation was cancelled the
24314 * partial result will be returned, without an error.
24316 * Returns: Number of bytes skipped, or -1 on error
24321 * g_input_stream_skip_async:
24322 * @stream: A #GInputStream.
24323 * @count: the number of bytes that will be skipped from the stream
24324 * @io_priority: the [I/O priority][io-priority] of the request
24325 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
24326 * @callback: (scope async): callback to call when the request is satisfied
24327 * @user_data: (closure): the data to pass to callback function
24329 * Request an asynchronous skip of @count bytes from the stream.
24330 * When the operation is finished @callback will be called.
24331 * You can then call g_input_stream_skip_finish() to get the result
24332 * of the operation.
24334 * During an async request no other sync and async calls are allowed,
24335 * and will result in %G_IO_ERROR_PENDING errors.
24337 * A value of @count larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
24339 * On success, the number of bytes skipped will be passed to the callback.
24340 * It is not an error if this is not the same as the requested size, as it
24341 * can happen e.g. near the end of a file, but generally we try to skip
24342 * as many bytes as requested. Zero is returned on end of file
24343 * (or if @count is zero), but never otherwise.
24345 * Any outstanding i/o request with higher priority (lower numerical value)
24346 * will be executed before an outstanding request with lower priority.
24347 * Default priority is %G_PRIORITY_DEFAULT.
24349 * The asynchronous methods have a default fallback that uses threads to
24350 * implement asynchronicity, so they are optional for inheriting classes.
24351 * However, if you override one, you must override all.
24356 * g_input_stream_skip_finish:
24357 * @stream: a #GInputStream.
24358 * @result: a #GAsyncResult.
24359 * @error: a #GError location to store the error occurring, or %NULL to
24362 * Finishes a stream skip operation.
24364 * Returns: the size of the bytes skipped, or %-1 on error.
24369 * g_io_error_from_errno:
24370 * @err_no: Error number as defined in errno.h.
24372 * Converts errno.h error codes into GIO error codes. The fallback
24373 * value %G_IO_ERROR_FAILED is returned for error codes not currently
24374 * handled (but note that future GLib releases may return a more
24375 * specific value instead).
24377 * Returns: #GIOErrorEnum value for the given errno.h error number.
24382 * g_io_error_from_win32_error:
24383 * @error_code: Windows error number.
24385 * Converts some common error codes (as returned from GetLastError()
24386 * or WSAGetLastError()) into GIO error codes. The fallback value
24387 * %G_IO_ERROR_FAILED is returned for error codes not currently
24388 * handled (but note that future GLib releases may return a more
24389 * specific value instead).
24391 * You can use g_win32_error_message() to get a localized string
24392 * corresponding to @error_code. (But note that unlike g_strerror(),
24393 * g_win32_error_message() returns a string that must be freed.)
24395 * Returns: #GIOErrorEnum value for the given error number.
24401 * g_io_error_quark:
24403 * Gets the GIO Error Quark.
24405 * Returns: a #GQuark.
24410 * g_io_extension_get_name:
24411 * @extension: a #GIOExtension
24413 * Gets the name under which @extension was registered.
24415 * Note that the same type may be registered as extension
24416 * for multiple extension points, under different names.
24418 * Returns: the name of @extension.
24423 * g_io_extension_get_priority:
24424 * @extension: a #GIOExtension
24426 * Gets the priority with which @extension was registered.
24428 * Returns: the priority of @extension
24433 * g_io_extension_get_type:
24434 * @extension: a #GIOExtension
24436 * Gets the type associated with @extension.
24438 * Returns: the type of @extension
24443 * g_io_extension_point_get_extension_by_name:
24444 * @extension_point: a #GIOExtensionPoint
24445 * @name: the name of the extension to get
24447 * Finds a #GIOExtension for an extension point by name.
24449 * Returns: (transfer none): the #GIOExtension for @extension_point that has the
24450 * given name, or %NULL if there is no extension with that name
24455 * g_io_extension_point_get_extensions:
24456 * @extension_point: a #GIOExtensionPoint
24458 * Gets a list of all extensions that implement this extension point.
24459 * The list is sorted by priority, beginning with the highest priority.
24461 * Returns: (element-type GIOExtension) (transfer none): a #GList of
24462 * #GIOExtensions. The list is owned by GIO and should not be
24468 * g_io_extension_point_get_required_type:
24469 * @extension_point: a #GIOExtensionPoint
24471 * Gets the required type for @extension_point.
24473 * Returns: the #GType that all implementations must have,
24474 * or #G_TYPE_INVALID if the extension point has no required type
24479 * g_io_extension_point_implement:
24480 * @extension_point_name: the name of the extension point
24481 * @type: the #GType to register as extension
24482 * @extension_name: the name for the extension
24483 * @priority: the priority for the extension
24485 * Registers @type as extension for the extension point with name
24486 * @extension_point_name.
24488 * If @type has already been registered as an extension for this
24489 * extension point, the existing #GIOExtension object is returned.
24491 * Returns: (transfer none): a #GIOExtension object for #GType
24496 * g_io_extension_point_lookup:
24497 * @name: the name of the extension point
24499 * Looks up an existing extension point.
24501 * Returns: (transfer none): the #GIOExtensionPoint, or %NULL if there
24502 * is no registered extension point with the given name.
24507 * g_io_extension_point_register:
24508 * @name: The name of the extension point
24510 * Registers an extension point.
24512 * Returns: (transfer none): the new #GIOExtensionPoint. This object is
24513 * owned by GIO and should not be freed.
24518 * g_io_extension_point_set_required_type:
24519 * @extension_point: a #GIOExtensionPoint
24520 * @type: the #GType to require
24522 * Sets the required type for @extension_point to @type.
24523 * All implementations must henceforth have this type.
24528 * g_io_extension_ref_class:
24529 * @extension: a #GIOExtension
24531 * Gets a reference to the class for the type that is
24532 * associated with @extension.
24534 * Returns: (transfer full): the #GTypeClass for the type of @extension
24540 * @filename: filename of the shared library module.
24542 * Creates a new GIOModule that will load the specific
24543 * shared library when in use.
24545 * Returns: a #GIOModule from given @filename,
24546 * or %NULL on error.
24551 * g_io_module_scope_block:
24552 * @scope: a module loading scope
24553 * @basename: the basename to block
24555 * Block modules with the given @basename from being loaded when
24556 * this scope is used with g_io_modules_scan_all_in_directory_with_scope()
24557 * or g_io_modules_load_all_in_directory_with_scope().
24564 * g_io_module_scope_free:
24565 * @scope: a module loading scope
24567 * Free a module scope.
24574 * g_io_module_scope_new:
24575 * @flags: flags for the new scope
24577 * Create a new scope for loading of IO modules. A scope can be used for
24578 * blocking duplicate modules, or blocking a module you don't want to load.
24580 * Specify the %G_IO_MODULE_SCOPE_BLOCK_DUPLICATES flag to block modules
24581 * which have the same base name as a module that has already been seen
24584 * Returns: (transfer full): the new module scope
24590 * g_io_modules_load_all_in_directory:
24591 * @dirname: pathname for a directory containing modules to load.
24593 * Loads all the modules in the specified directory.
24595 * If don't require all modules to be initialized (and thus registering
24596 * all gtypes) then you can use g_io_modules_scan_all_in_directory()
24597 * which allows delayed/lazy loading of modules.
24599 * Returns: (element-type GIOModule) (transfer full): a list of #GIOModules loaded
24600 * from the directory,
24601 * All the modules are loaded into memory, if you want to
24602 * unload them (enabling on-demand loading) you must call
24603 * g_type_module_unuse() on all the modules. Free the list
24604 * with g_list_free().
24609 * g_io_modules_load_all_in_directory_with_scope:
24610 * @dirname: pathname for a directory containing modules to load.
24611 * @scope: a scope to use when scanning the modules.
24613 * Loads all the modules in the specified directory.
24615 * If don't require all modules to be initialized (and thus registering
24616 * all gtypes) then you can use g_io_modules_scan_all_in_directory()
24617 * which allows delayed/lazy loading of modules.
24619 * Returns: (element-type GIOModule) (transfer full): a list of #GIOModules loaded
24620 * from the directory,
24621 * All the modules are loaded into memory, if you want to
24622 * unload them (enabling on-demand loading) you must call
24623 * g_type_module_unuse() on all the modules. Free the list
24624 * with g_list_free().
24630 * g_io_modules_scan_all_in_directory:
24631 * @dirname: pathname for a directory containing modules to scan.
24633 * Scans all the modules in the specified directory, ensuring that
24634 * any extension point implemented by a module is registered.
24636 * This may not actually load and initialize all the types in each
24637 * module, some modules may be lazily loaded and initialized when
24638 * an extension point it implementes is used with e.g.
24639 * g_io_extension_point_get_extensions() or
24640 * g_io_extension_point_get_extension_by_name().
24642 * If you need to guarantee that all types are loaded in all the modules,
24643 * use g_io_modules_load_all_in_directory().
24650 * g_io_modules_scan_all_in_directory_with_scope:
24651 * @dirname: pathname for a directory containing modules to scan.
24652 * @scope: a scope to use when scanning the modules
24654 * Scans all the modules in the specified directory, ensuring that
24655 * any extension point implemented by a module is registered.
24657 * This may not actually load and initialize all the types in each
24658 * module, some modules may be lazily loaded and initialized when
24659 * an extension point it implementes is used with e.g.
24660 * g_io_extension_point_get_extensions() or
24661 * g_io_extension_point_get_extension_by_name().
24663 * If you need to guarantee that all types are loaded in all the modules,
24664 * use g_io_modules_load_all_in_directory().
24671 * g_io_scheduler_cancel_all_jobs:
24673 * Cancels all cancellable I/O jobs.
24675 * A job is cancellable if a #GCancellable was passed into
24676 * g_io_scheduler_push_job().
24678 * Deprecated: You should never call this function, since you don't
24679 * know how other libraries in your program might be making use of
24685 * g_io_scheduler_job_send_to_mainloop:
24686 * @job: a #GIOSchedulerJob
24687 * @func: a #GSourceFunc callback that will be called in the original thread
24688 * @user_data: data to pass to @func
24689 * @notify: (allow-none): a #GDestroyNotify for @user_data, or %NULL
24691 * Used from an I/O job to send a callback to be run in the thread
24692 * that the job was started from, waiting for the result (and thus
24693 * blocking the I/O job).
24695 * Returns: The return value of @func
24696 * Deprecated: Use g_main_context_invoke().
24701 * g_io_scheduler_job_send_to_mainloop_async:
24702 * @job: a #GIOSchedulerJob
24703 * @func: a #GSourceFunc callback that will be called in the original thread
24704 * @user_data: data to pass to @func
24705 * @notify: (allow-none): a #GDestroyNotify for @user_data, or %NULL
24707 * Used from an I/O job to send a callback to be run asynchronously in
24708 * the thread that the job was started from. The callback will be run
24709 * when the main loop is available, but at that time the I/O job might
24710 * have finished. The return value from the callback is ignored.
24712 * Note that if you are passing the @user_data from g_io_scheduler_push_job()
24713 * on to this function you have to ensure that it is not freed before
24714 * @func is called, either by passing %NULL as @notify to
24715 * g_io_scheduler_push_job() or by using refcounting for @user_data.
24717 * Deprecated: Use g_main_context_invoke().
24722 * g_io_scheduler_push_job:
24723 * @job_func: a #GIOSchedulerJobFunc.
24724 * @user_data: data to pass to @job_func
24725 * @notify: (allow-none): a #GDestroyNotify for @user_data, or %NULL
24726 * @io_priority: the [I/O priority][io-priority]
24728 * @cancellable: optional #GCancellable object, %NULL to ignore.
24730 * Schedules the I/O job to run in another thread.
24732 * @notify will be called on @user_data after @job_func has returned,
24733 * regardless whether the job was cancelled or has run to completion.
24735 * If @cancellable is not %NULL, it can be used to cancel the I/O job
24736 * by calling g_cancellable_cancel() or by calling
24737 * g_io_scheduler_cancel_all_jobs().
24739 * Deprecated: use #GThreadPool or g_task_run_in_thread()
24744 * g_io_stream_clear_pending:
24745 * @stream: a #GIOStream
24747 * Clears the pending flag on @stream.
24754 * g_io_stream_close:
24755 * @stream: a #GIOStream
24756 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
24757 * @error: location to store the error occurring, or %NULL to ignore
24759 * Closes the stream, releasing resources related to it. This will also
24760 * closes the individual input and output streams, if they are not already
24763 * Once the stream is closed, all other operations will return
24764 * %G_IO_ERROR_CLOSED. Closing a stream multiple times will not
24767 * Closing a stream will automatically flush any outstanding buffers
24770 * Streams will be automatically closed when the last reference
24771 * is dropped, but you might want to call this function to make sure
24772 * resources are released as early as possible.
24774 * Some streams might keep the backing store of the stream (e.g. a file
24775 * descriptor) open after the stream is closed. See the documentation for
24776 * the individual stream for details.
24778 * On failure the first error that happened will be reported, but the
24779 * close operation will finish as much as possible. A stream that failed
24780 * to close will still return %G_IO_ERROR_CLOSED for all operations.
24781 * Still, it is important to check and report the error to the user,
24782 * otherwise there might be a loss of data as all data might not be written.
24784 * If @cancellable is not NULL, then the operation can be cancelled by
24785 * triggering the cancellable object from another thread. If the operation
24786 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
24787 * Cancelling a close will still leave the stream closed, but some streams
24788 * can use a faster close that doesn't block to e.g. check errors.
24790 * The default implementation of this method just calls close on the
24791 * individual input/output streams.
24793 * Returns: %TRUE on success, %FALSE on failure
24799 * g_io_stream_close_async:
24800 * @stream: a #GIOStream
24801 * @io_priority: the io priority of the request
24802 * @cancellable: (allow-none): optional cancellable object
24803 * @callback: (scope async): callback to call when the request is satisfied
24804 * @user_data: (closure): the data to pass to callback function
24806 * Requests an asynchronous close of the stream, releasing resources
24807 * related to it. When the operation is finished @callback will be
24808 * called. You can then call g_io_stream_close_finish() to get
24809 * the result of the operation.
24811 * For behaviour details see g_io_stream_close().
24813 * The asynchronous methods have a default fallback that uses threads
24814 * to implement asynchronicity, so they are optional for inheriting
24815 * classes. However, if you override one you must override all.
24822 * g_io_stream_close_finish:
24823 * @stream: a #GIOStream
24824 * @result: a #GAsyncResult
24825 * @error: a #GError location to store the error occurring, or %NULL to
24830 * Returns: %TRUE if stream was successfully closed, %FALSE otherwise.
24836 * g_io_stream_get_input_stream:
24837 * @stream: a #GIOStream
24839 * Gets the input stream for this object. This is used
24842 * Returns: (transfer none): a #GInputStream, owned by the #GIOStream.
24849 * g_io_stream_get_output_stream:
24850 * @stream: a #GIOStream
24852 * Gets the output stream for this object. This is used for
24855 * Returns: (transfer none): a #GOutputStream, owned by the #GIOStream.
24862 * g_io_stream_has_pending:
24863 * @stream: a #GIOStream
24865 * Checks if a stream has pending actions.
24867 * Returns: %TRUE if @stream has pending actions.
24873 * g_io_stream_is_closed:
24874 * @stream: a #GIOStream
24876 * Checks if a stream is closed.
24878 * Returns: %TRUE if the stream is closed.
24884 * g_io_stream_set_pending:
24885 * @stream: a #GIOStream
24886 * @error: a #GError location to store the error occurring, or %NULL to
24889 * Sets @stream to have actions pending. If the pending flag is
24890 * already set or @stream is closed, it will return %FALSE and set
24893 * Returns: %TRUE if pending was previously unset and is now set.
24899 * g_io_stream_splice_async:
24900 * @stream1: a #GIOStream.
24901 * @stream2: a #GIOStream.
24902 * @flags: a set of #GIOStreamSpliceFlags.
24903 * @io_priority: the io priority of the request.
24904 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
24905 * @callback: (scope async): a #GAsyncReadyCallback.
24906 * @user_data: (closure): user data passed to @callback.
24908 * Asyncronously splice the output stream of @stream1 to the input stream of
24909 * @stream2, and splice the output stream of @stream2 to the input stream of
24912 * When the operation is finished @callback will be called.
24913 * You can then call g_io_stream_splice_finish() to get the
24914 * result of the operation.
24921 * g_io_stream_splice_finish:
24922 * @result: a #GAsyncResult.
24923 * @error: a #GError location to store the error occurring, or %NULL to
24926 * Finishes an asynchronous io stream splice operation.
24928 * Returns: %TRUE on success, %FALSE otherwise.
24934 * g_keyfile_settings_backend_new:
24935 * @filename: the filename of the keyfile
24936 * @root_path: the path under which all settings keys appear
24937 * @root_group: (allow-none): the group name corresponding to
24938 * @root_path, or %NULL
24940 * Creates a keyfile-backed #GSettingsBackend.
24942 * The filename of the keyfile to use is given by @filename.
24944 * All settings read to or written from the backend must fall under the
24945 * path given in @root_path (which must start and end with a slash and
24946 * not contain two consecutive slashes). @root_path may be "/".
24948 * If @root_group is non-%NULL then it specifies the name of the keyfile
24949 * group used for keys that are written directly below @root_path. For
24950 * example, if @root_path is "/apps/example/" and @root_group is
24951 * "toplevel", then settings the key "/apps/example/enabled" to a value
24952 * of %TRUE will cause the following to appear in the keyfile:
24959 * If @root_group is %NULL then it is not permitted to store keys
24960 * directly below the @root_path.
24962 * For keys not stored directly below @root_path (ie: in a sub-path),
24963 * the name of the subpath (with the final slash stripped) is used as
24964 * the name of the keyfile group. To continue the example, if
24965 * "/apps/example/profiles/default/font-size" were set to
24966 * 12 then the following would appear in the keyfile:
24969 * [profiles/default]
24973 * The backend will refuse writes (and return writability as being
24974 * %FALSE) for keys outside of @root_path and, in the event that
24975 * @root_group is %NULL, also for keys directly under @root_path.
24976 * Writes will also be refused if the backend detects that it has the
24977 * inability to rewrite the keyfile (ie: the containing directory is not
24980 * There is no checking done for your key namespace clashing with the
24981 * syntax of the key file format. For example, if you have '[' or ']'
24982 * characters in your path names or '=' in your key names you may be in
24985 * Returns: (transfer full): a keyfile-backed #GSettingsBackend
24990 * g_loadable_icon_load:
24991 * @icon: a #GLoadableIcon.
24992 * @size: an integer.
24993 * @type: (out) (optional): a location to store the type of the loaded
24994 * icon, %NULL to ignore.
24995 * @cancellable: (allow-none): optional #GCancellable object, %NULL to
24997 * @error: a #GError location to store the error occurring, or %NULL
25000 * Loads a loadable icon. For the asynchronous version of this function,
25001 * see g_loadable_icon_load_async().
25003 * Returns: (transfer full): a #GInputStream to read the icon from.
25008 * g_loadable_icon_load_async:
25009 * @icon: a #GLoadableIcon.
25010 * @size: an integer.
25011 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
25012 * @callback: (scope async): a #GAsyncReadyCallback to call when the
25013 * request is satisfied
25014 * @user_data: (closure): the data to pass to callback function
25016 * Loads an icon asynchronously. To finish this function, see
25017 * g_loadable_icon_load_finish(). For the synchronous, blocking
25018 * version of this function, see g_loadable_icon_load().
25023 * g_loadable_icon_load_finish:
25024 * @icon: a #GLoadableIcon.
25025 * @res: a #GAsyncResult.
25026 * @type: (out) (optional): a location to store the type of the loaded
25027 * icon, %NULL to ignore.
25028 * @error: a #GError location to store the error occurring, or %NULL to
25031 * Finishes an asynchronous icon load started in g_loadable_icon_load_async().
25033 * Returns: (transfer full): a #GInputStream to read the icon from.
25040 * Returns a new #GVfs handle for a local vfs.
25042 * Returns: a new #GVfs handle.
25047 * g_memory_input_stream_add_bytes:
25048 * @stream: a #GMemoryInputStream
25049 * @bytes: input data
25051 * Appends @bytes to data that can be read from the input stream.
25058 * g_memory_input_stream_add_data:
25059 * @stream: a #GMemoryInputStream
25060 * @data: (array length=len) (element-type guint8) (transfer full): input data
25061 * @len: length of the data, may be -1 if @data is a nul-terminated string
25062 * @destroy: (allow-none): function that is called to free @data, or %NULL
25064 * Appends @data to data that can be read from the input stream
25069 * g_memory_input_stream_new:
25071 * Creates a new empty #GMemoryInputStream.
25073 * Returns: a new #GInputStream
25078 * g_memory_input_stream_new_from_bytes:
25079 * @bytes: a #GBytes
25081 * Creates a new #GMemoryInputStream with data from the given @bytes.
25083 * Returns: new #GInputStream read from @bytes
25089 * g_memory_input_stream_new_from_data:
25090 * @data: (array length=len) (element-type guint8) (transfer full): input data
25091 * @len: length of the data, may be -1 if @data is a nul-terminated string
25092 * @destroy: (allow-none): function that is called to free @data, or %NULL
25094 * Creates a new #GMemoryInputStream with data in memory of a given size.
25096 * Returns: new #GInputStream read from @data of @len bytes.
25101 * g_memory_output_stream_get_data:
25102 * @ostream: a #GMemoryOutputStream
25104 * Gets any loaded data from the @ostream.
25106 * Note that the returned pointer may become invalid on the next
25107 * write or truncate operation on the stream.
25109 * Returns: (transfer none): pointer to the stream's data
25114 * g_memory_output_stream_get_data_size:
25115 * @ostream: a #GMemoryOutputStream
25117 * Returns the number of bytes from the start up to including the last
25118 * byte written in the stream that has not been truncated away.
25120 * Returns: the number of bytes written to the stream
25126 * g_memory_output_stream_get_size:
25127 * @ostream: a #GMemoryOutputStream
25129 * Gets the size of the currently allocated data area (available from
25130 * g_memory_output_stream_get_data()).
25132 * You probably don't want to use this function on resizable streams.
25133 * See g_memory_output_stream_get_data_size() instead. For resizable
25134 * streams the size returned by this function is an implementation
25135 * detail and may be change at any time in response to operations on the
25138 * If the stream is fixed-sized (ie: no realloc was passed to
25139 * g_memory_output_stream_new()) then this is the maximum size of the
25140 * stream and further writes will return %G_IO_ERROR_NO_SPACE.
25142 * In any case, if you want the number of bytes currently written to the
25143 * stream, use g_memory_output_stream_get_data_size().
25145 * Returns: the number of bytes allocated for the data buffer
25150 * g_memory_output_stream_new: (skip)
25151 * @data: (allow-none): pointer to a chunk of memory to use, or %NULL
25152 * @size: the size of @data
25153 * @realloc_function: (allow-none): a function with realloc() semantics (like g_realloc())
25154 * to be called when @data needs to be grown, or %NULL
25155 * @destroy_function: (allow-none): a function to be called on @data when the stream is
25156 * finalized, or %NULL
25158 * Creates a new #GMemoryOutputStream.
25160 * In most cases this is not the function you want. See
25161 * g_memory_output_stream_new_resizable() instead.
25163 * If @data is non-%NULL, the stream will use that for its internal storage.
25165 * If @realloc_fn is non-%NULL, it will be used for resizing the internal
25166 * storage when necessary and the stream will be considered resizable.
25167 * In that case, the stream will start out being (conceptually) empty.
25168 * @size is used only as a hint for how big @data is. Specifically,
25169 * seeking to the end of a newly-created stream will seek to zero, not
25170 * @size. Seeking past the end of the stream and then writing will
25171 * introduce a zero-filled gap.
25173 * If @realloc_fn is %NULL then the stream is fixed-sized. Seeking to
25174 * the end will seek to @size exactly. Writing past the end will give
25175 * an 'out of space' error. Attempting to seek past the end will fail.
25176 * Unlike the resizable case, seeking to an offset within the stream and
25177 * writing will preserve the bytes passed in as @data before that point
25178 * and will return them as part of g_memory_output_stream_steal_data().
25179 * If you intend to seek you should probably therefore ensure that @data
25180 * is properly initialised.
25182 * It is probably only meaningful to provide @data and @size in the case
25183 * that you want a fixed-sized stream. Put another way: if @realloc_fn
25184 * is non-%NULL then it makes most sense to give @data as %NULL and
25185 * @size as 0 (allowing #GMemoryOutputStream to do the initial
25186 * allocation for itself).
25188 * |[<!-- language="C" -->
25189 * // a stream that can grow
25190 * stream = g_memory_output_stream_new (NULL, 0, realloc, free);
25192 * // another stream that can grow
25193 * stream2 = g_memory_output_stream_new (NULL, 0, g_realloc, g_free);
25195 * // a fixed-size stream
25196 * data = malloc (200);
25197 * stream3 = g_memory_output_stream_new (data, 200, NULL, free);
25200 * Returns: A newly created #GMemoryOutputStream object.
25205 * g_memory_output_stream_new_resizable:
25207 * Creates a new #GMemoryOutputStream, using g_realloc() and g_free()
25208 * for memory allocation.
25215 * g_memory_output_stream_steal_as_bytes:
25216 * @ostream: a #GMemoryOutputStream
25218 * Returns data from the @ostream as a #GBytes. @ostream must be
25219 * closed before calling this function.
25221 * Returns: (transfer full): the stream's data
25227 * g_memory_output_stream_steal_data:
25228 * @ostream: a #GMemoryOutputStream
25230 * Gets any loaded data from the @ostream. Ownership of the data
25231 * is transferred to the caller; when no longer needed it must be
25232 * freed using the free function set in @ostream's
25233 * #GMemoryOutputStream:destroy-function property.
25235 * @ostream must be closed before calling this function.
25237 * Returns: (transfer full): the stream's data
25243 * g_memory_settings_backend_new:
25245 * Creates a memory-backed #GSettingsBackend.
25247 * This backend allows changes to settings, but does not write them
25248 * to any backing storage, so the next time you run your application,
25249 * the memory backend will start out with the default values again.
25251 * Returns: (transfer full): a newly created #GSettingsBackend
25259 * @label: (allow-none): the section label, or %NULL
25260 * @detailed_action: (allow-none): the detailed action string, or %NULL
25262 * Convenience function for appending a normal menu item to the end of
25263 * @menu. Combine g_menu_item_new() and g_menu_insert_item() for a more
25264 * flexible alternative.
25271 * g_menu_append_item:
25273 * @item: a #GMenuItem to append
25275 * Appends @item to the end of @menu.
25277 * See g_menu_insert_item() for more information.
25284 * g_menu_append_section:
25286 * @label: (allow-none): the section label, or %NULL
25287 * @section: a #GMenuModel with the items of the section
25289 * Convenience function for appending a section menu item to the end of
25290 * @menu. Combine g_menu_item_new_section() and g_menu_insert_item() for a
25291 * more flexible alternative.
25298 * g_menu_append_submenu:
25300 * @label: (allow-none): the section label, or %NULL
25301 * @submenu: a #GMenuModel with the items of the submenu
25303 * Convenience function for appending a submenu menu item to the end of
25304 * @menu. Combine g_menu_item_new_submenu() and g_menu_insert_item() for a
25305 * more flexible alternative.
25312 * g_menu_attribute_iter_get_name:
25313 * @iter: a #GMenuAttributeIter
25315 * Gets the name of the attribute at the current iterator position, as
25318 * The iterator is not advanced.
25320 * Returns: the name of the attribute
25326 * g_menu_attribute_iter_get_next:
25327 * @iter: a #GMenuAttributeIter
25328 * @out_name: (out) (allow-none) (transfer none): the type of the attribute
25329 * @value: (out) (allow-none) (transfer full): the attribute value
25331 * This function combines g_menu_attribute_iter_next() with
25332 * g_menu_attribute_iter_get_name() and g_menu_attribute_iter_get_value().
25334 * First the iterator is advanced to the next (possibly first) attribute.
25335 * If that fails, then %FALSE is returned and there are no other
25338 * If successful, @name and @value are set to the name and value of the
25339 * attribute that has just been advanced to. At this point,
25340 * g_menu_attribute_iter_get_name() and g_menu_attribute_iter_get_value() will
25341 * return the same values again.
25343 * The value returned in @name remains valid for as long as the iterator
25344 * remains at the current position. The value returned in @value must
25345 * be unreffed using g_variant_unref() when it is no longer in use.
25347 * Returns: %TRUE on success, or %FALSE if there is no additional
25354 * g_menu_attribute_iter_get_value:
25355 * @iter: a #GMenuAttributeIter
25357 * Gets the value of the attribute at the current iterator position.
25359 * The iterator is not advanced.
25361 * Returns: (transfer full): the value of the current attribute
25367 * g_menu_attribute_iter_next:
25368 * @iter: a #GMenuAttributeIter
25370 * Attempts to advance the iterator to the next (possibly first)
25373 * %TRUE is returned on success, or %FALSE if there are no more
25376 * You must call this function when you first acquire the iterator
25377 * to advance it to the first attribute (and determine if the first
25378 * attribute exists at all).
25380 * Returns: %TRUE on success, or %FALSE when there are no more attributes
25389 * Marks @menu as frozen.
25391 * After the menu is frozen, it is an error to attempt to make any
25392 * changes to it. In effect this means that the #GMenu API must no
25395 * This function causes g_menu_model_is_mutable() to begin returning
25396 * %FALSE, which has some positive performance implications.
25405 * @position: the position at which to insert the item
25406 * @label: (allow-none): the section label, or %NULL
25407 * @detailed_action: (allow-none): the detailed action string, or %NULL
25409 * Convenience function for inserting a normal menu item into @menu.
25410 * Combine g_menu_item_new() and g_menu_insert_item() for a more flexible
25418 * g_menu_insert_item:
25420 * @position: the position at which to insert the item
25421 * @item: the #GMenuItem to insert
25423 * Inserts @item into @menu.
25425 * The "insertion" is actually done by copying all of the attribute and
25426 * link values of @item and using them to form a new item within @menu.
25427 * As such, @item itself is not really inserted, but rather, a menu item
25428 * that is exactly the same as the one presently described by @item.
25430 * This means that @item is essentially useless after the insertion
25431 * occurs. Any changes you make to it are ignored unless it is inserted
25432 * again (at which point its updated values will be copied).
25434 * You should probably just free @item once you're done.
25436 * There are many convenience functions to take care of common cases.
25437 * See g_menu_insert(), g_menu_insert_section() and
25438 * g_menu_insert_submenu() as well as "prepend" and "append" variants of
25439 * each of these functions.
25446 * g_menu_insert_section:
25448 * @position: the position at which to insert the item
25449 * @label: (allow-none): the section label, or %NULL
25450 * @section: a #GMenuModel with the items of the section
25452 * Convenience function for inserting a section menu item into @menu.
25453 * Combine g_menu_item_new_section() and g_menu_insert_item() for a more
25454 * flexible alternative.
25461 * g_menu_insert_submenu:
25463 * @position: the position at which to insert the item
25464 * @label: (allow-none): the section label, or %NULL
25465 * @submenu: a #GMenuModel with the items of the submenu
25467 * Convenience function for inserting a submenu menu item into @menu.
25468 * Combine g_menu_item_new_submenu() and g_menu_insert_item() for a more
25469 * flexible alternative.
25476 * g_menu_item_get_attribute:
25477 * @menu_item: a #GMenuItem
25478 * @attribute: the attribute name to query
25479 * @format_string: a #GVariant format string
25480 * @...: positional parameters, as per @format_string
25482 * Queries the named @attribute on @menu_item.
25484 * If the attribute exists and matches the #GVariantType corresponding
25485 * to @format_string then @format_string is used to deconstruct the
25486 * value into the positional parameters and %TRUE is returned.
25488 * If the attribute does not exist, or it does exist but has the wrong
25489 * type, then the positional parameters are ignored and %FALSE is
25492 * Returns: %TRUE if the named attribute was found with the expected
25499 * g_menu_item_get_attribute_value:
25500 * @menu_item: a #GMenuItem
25501 * @attribute: the attribute name to query
25502 * @expected_type: (allow-none): the expected type of the attribute
25504 * Queries the named @attribute on @menu_item.
25506 * If @expected_type is specified and the attribute does not have this
25507 * type, %NULL is returned. %NULL is also returned if the attribute
25508 * simply does not exist.
25510 * Returns: (transfer full): the attribute value, or %NULL
25516 * g_menu_item_get_link:
25517 * @menu_item: a #GMenuItem
25518 * @link: the link name to query
25520 * Queries the named @link on @menu_item.
25522 * Returns: (transfer full): the link, or %NULL
25529 * @label: (allow-none): the section label, or %NULL
25530 * @detailed_action: (allow-none): the detailed action string, or %NULL
25532 * Creates a new #GMenuItem.
25534 * If @label is non-%NULL it is used to set the "label" attribute of the
25537 * If @detailed_action is non-%NULL it is used to set the "action" and
25538 * possibly the "target" attribute of the new item. See
25539 * g_menu_item_set_detailed_action() for more information.
25541 * Returns: a new #GMenuItem
25547 * g_menu_item_new_from_model:
25548 * @model: a #GMenuModel
25549 * @item_index: the index of an item in @model
25551 * Creates a #GMenuItem as an exact copy of an existing menu item in a
25554 * @item_index must be valid (ie: be sure to call
25555 * g_menu_model_get_n_items() first).
25557 * Returns: a new #GMenuItem.
25563 * g_menu_item_new_section:
25564 * @label: (allow-none): the section label, or %NULL
25565 * @section: a #GMenuModel with the items of the section
25567 * Creates a new #GMenuItem representing a section.
25569 * This is a convenience API around g_menu_item_new() and
25570 * g_menu_item_set_section().
25572 * The effect of having one menu appear as a section of another is
25573 * exactly as it sounds: the items from @section become a direct part of
25574 * the menu that @menu_item is added to.
25576 * Visual separation is typically displayed between two non-empty
25577 * sections. If @label is non-%NULL then it will be encorporated into
25578 * this visual indication. This allows for labeled subsections of a
25581 * As a simple example, consider a typical "Edit" menu from a simple
25582 * program. It probably contains an "Undo" and "Redo" item, followed by
25583 * a separator, followed by "Cut", "Copy" and "Paste".
25585 * This would be accomplished by creating three #GMenu instances. The
25586 * first would be populated with the "Undo" and "Redo" items, and the
25587 * second with the "Cut", "Copy" and "Paste" items. The first and
25588 * second menus would then be added as submenus of the third. In XML
25589 * format, this would look something like the following:
25591 * <menu id='edit-menu'>
25593 * <item label='Undo'/>
25594 * <item label='Redo'/>
25597 * <item label='Cut'/>
25598 * <item label='Copy'/>
25599 * <item label='Paste'/>
25604 * The following example is exactly equivalent. It is more illustrative
25605 * of the exact relationship between the menus and items (keeping in
25606 * mind that the 'link' element defines a new menu that is linked to the
25607 * containing one). The style of the second example is more verbose and
25608 * difficult to read (and therefore not recommended except for the
25609 * purpose of understanding what is really going on).
25611 * <menu id='edit-menu'>
25613 * <link name='section'>
25614 * <item label='Undo'/>
25615 * <item label='Redo'/>
25619 * <link name='section'>
25620 * <item label='Cut'/>
25621 * <item label='Copy'/>
25622 * <item label='Paste'/>
25628 * Returns: a new #GMenuItem
25634 * g_menu_item_new_submenu:
25635 * @label: (allow-none): the section label, or %NULL
25636 * @submenu: a #GMenuModel with the items of the submenu
25638 * Creates a new #GMenuItem representing a submenu.
25640 * This is a convenience API around g_menu_item_new() and
25641 * g_menu_item_set_submenu().
25643 * Returns: a new #GMenuItem
25649 * g_menu_item_set_action_and_target:
25650 * @menu_item: a #GMenuItem
25651 * @action: (allow-none): the name of the action for this item
25652 * @format_string: (allow-none): a GVariant format string
25653 * @...: positional parameters, as per @format_string
25655 * Sets or unsets the "action" and "target" attributes of @menu_item.
25657 * If @action is %NULL then both the "action" and "target" attributes
25658 * are unset (and @format_string is ignored along with the positional
25661 * If @action is non-%NULL then the "action" attribute is set.
25662 * @format_string is then inspected. If it is non-%NULL then the proper
25663 * position parameters are collected to create a #GVariant instance to
25664 * use as the target value. If it is %NULL then the positional
25665 * parameters are ignored and the "target" attribute is unset.
25667 * See also g_menu_item_set_action_and_target_value() for an equivalent
25668 * call that directly accepts a #GVariant. See
25669 * g_menu_item_set_detailed_action() for a more convenient version that
25670 * works with string-typed targets.
25672 * See also g_menu_item_set_action_and_target_value() for a
25673 * description of the semantics of the action and target attributes.
25680 * g_menu_item_set_action_and_target_value:
25681 * @menu_item: a #GMenuItem
25682 * @action: (allow-none): the name of the action for this item
25683 * @target_value: (allow-none): a #GVariant to use as the action target
25685 * Sets or unsets the "action" and "target" attributes of @menu_item.
25687 * If @action is %NULL then both the "action" and "target" attributes
25688 * are unset (and @target_value is ignored).
25690 * If @action is non-%NULL then the "action" attribute is set. The
25691 * "target" attribute is then set to the value of @target_value if it is
25692 * non-%NULL or unset otherwise.
25694 * Normal menu items (ie: not submenu, section or other custom item
25695 * types) are expected to have the "action" attribute set to identify
25696 * the action that they are associated with. The state type of the
25697 * action help to determine the disposition of the menu item. See
25698 * #GAction and #GActionGroup for an overview of actions.
25700 * In general, clicking on the menu item will result in activation of
25701 * the named action with the "target" attribute given as the parameter
25702 * to the action invocation. If the "target" attribute is not set then
25703 * the action is invoked with no parameter.
25705 * If the action has no state then the menu item is usually drawn as a
25706 * plain menu item (ie: with no additional decoration).
25708 * If the action has a boolean state then the menu item is usually drawn
25709 * as a toggle menu item (ie: with a checkmark or equivalent
25710 * indication). The item should be marked as 'toggled' or 'checked'
25711 * when the boolean state is %TRUE.
25713 * If the action has a string state then the menu item is usually drawn
25714 * as a radio menu item (ie: with a radio bullet or equivalent
25715 * indication). The item should be marked as 'selected' when the string
25716 * state is equal to the value of the @target property.
25718 * See g_menu_item_set_action_and_target() or
25719 * g_menu_item_set_detailed_action() for two equivalent calls that are
25720 * probably more convenient for most uses.
25727 * g_menu_item_set_attribute:
25728 * @menu_item: a #GMenuItem
25729 * @attribute: the attribute to set
25730 * @format_string: (allow-none): a #GVariant format string, or %NULL
25731 * @...: positional parameters, as per @format_string
25733 * Sets or unsets an attribute on @menu_item.
25735 * The attribute to set or unset is specified by @attribute. This
25736 * can be one of the standard attribute names %G_MENU_ATTRIBUTE_LABEL,
25737 * %G_MENU_ATTRIBUTE_ACTION, %G_MENU_ATTRIBUTE_TARGET, or a custom
25739 * Attribute names are restricted to lowercase characters, numbers
25740 * and '-'. Furthermore, the names must begin with a lowercase character,
25741 * must not end with a '-', and must not contain consecutive dashes.
25743 * If @format_string is non-%NULL then the proper position parameters
25744 * are collected to create a #GVariant instance to use as the attribute
25745 * value. If it is %NULL then the positional parameterrs are ignored
25746 * and the named attribute is unset.
25748 * See also g_menu_item_set_attribute_value() for an equivalent call
25749 * that directly accepts a #GVariant.
25756 * g_menu_item_set_attribute_value:
25757 * @menu_item: a #GMenuItem
25758 * @attribute: the attribute to set
25759 * @value: (allow-none): a #GVariant to use as the value, or %NULL
25761 * Sets or unsets an attribute on @menu_item.
25763 * The attribute to set or unset is specified by @attribute. This
25764 * can be one of the standard attribute names %G_MENU_ATTRIBUTE_LABEL,
25765 * %G_MENU_ATTRIBUTE_ACTION, %G_MENU_ATTRIBUTE_TARGET, or a custom
25767 * Attribute names are restricted to lowercase characters, numbers
25768 * and '-'. Furthermore, the names must begin with a lowercase character,
25769 * must not end with a '-', and must not contain consecutive dashes.
25771 * must consist only of lowercase
25772 * ASCII characters, digits and '-'.
25774 * If @value is non-%NULL then it is used as the new value for the
25775 * attribute. If @value is %NULL then the attribute is unset. If
25776 * the @value #GVariant is floating, it is consumed.
25778 * See also g_menu_item_set_attribute() for a more convenient way to do
25786 * g_menu_item_set_detailed_action:
25787 * @menu_item: a #GMenuItem
25788 * @detailed_action: the "detailed" action string
25790 * Sets the "action" and possibly the "target" attribute of @menu_item.
25792 * The format of @detailed_action is the same format parsed by
25793 * g_action_parse_detailed_name().
25795 * See g_menu_item_set_action_and_target() or
25796 * g_menu_item_set_action_and_target_value() for more flexible (but
25797 * slightly less convenient) alternatives.
25799 * See also g_menu_item_set_action_and_target_value() for a description of
25800 * the semantics of the action and target attributes.
25807 * g_menu_item_set_icon:
25808 * @menu_item: a #GMenuItem
25809 * @icon: a #GIcon, or %NULL
25811 * Sets (or unsets) the icon on @menu_item.
25813 * This call is the same as calling g_icon_serialize() and using the
25814 * result as the value to g_menu_item_set_attribute_value() for
25815 * %G_MENU_ATTRIBUTE_ICON.
25817 * This API is only intended for use with "noun" menu items; things like
25818 * bookmarks or applications in an "Open With" menu. Don't use it on
25819 * menu items corresponding to verbs (eg: stock icons for 'Save' or
25822 * If @icon is %NULL then the icon is unset.
25829 * g_menu_item_set_label:
25830 * @menu_item: a #GMenuItem
25831 * @label: (allow-none): the label to set, or %NULL to unset
25833 * Sets or unsets the "label" attribute of @menu_item.
25835 * If @label is non-%NULL it is used as the label for the menu item. If
25836 * it is %NULL then the label attribute is unset.
25843 * g_menu_item_set_link:
25844 * @menu_item: a #GMenuItem
25845 * @link: type of link to establish or unset
25846 * @model: (allow-none): the #GMenuModel to link to (or %NULL to unset)
25848 * Creates a link from @menu_item to @model if non-%NULL, or unsets it.
25850 * Links are used to establish a relationship between a particular menu
25851 * item and another menu. For example, %G_MENU_LINK_SUBMENU is used to
25852 * associate a submenu with a particular menu item, and %G_MENU_LINK_SECTION
25853 * is used to create a section. Other types of link can be used, but there
25854 * is no guarantee that clients will be able to make sense of them.
25855 * Link types are restricted to lowercase characters, numbers
25856 * and '-'. Furthermore, the names must begin with a lowercase character,
25857 * must not end with a '-', and must not contain consecutive dashes.
25864 * g_menu_item_set_section:
25865 * @menu_item: a #GMenuItem
25866 * @section: (allow-none): a #GMenuModel, or %NULL
25868 * Sets or unsets the "section" link of @menu_item to @section.
25870 * The effect of having one menu appear as a section of another is
25871 * exactly as it sounds: the items from @section become a direct part of
25872 * the menu that @menu_item is added to. See g_menu_item_new_section()
25873 * for more information about what it means for a menu item to be a
25881 * g_menu_item_set_submenu:
25882 * @menu_item: a #GMenuItem
25883 * @submenu: (allow-none): a #GMenuModel, or %NULL
25885 * Sets or unsets the "submenu" link of @menu_item to @submenu.
25887 * If @submenu is non-%NULL, it is linked to. If it is %NULL then the
25890 * The effect of having one menu appear as a submenu of another is
25891 * exactly as it sounds.
25898 * g_menu_link_iter_get_name:
25899 * @iter: a #GMenuLinkIter
25901 * Gets the name of the link at the current iterator position.
25903 * The iterator is not advanced.
25905 * Returns: the type of the link
25911 * g_menu_link_iter_get_next:
25912 * @iter: a #GMenuLinkIter
25913 * @out_link: (out) (allow-none) (transfer none): the name of the link
25914 * @value: (out) (allow-none) (transfer full): the linked #GMenuModel
25916 * This function combines g_menu_link_iter_next() with
25917 * g_menu_link_iter_get_name() and g_menu_link_iter_get_value().
25919 * First the iterator is advanced to the next (possibly first) link.
25920 * If that fails, then %FALSE is returned and there are no other effects.
25922 * If successful, @out_link and @value are set to the name and #GMenuModel
25923 * of the link that has just been advanced to. At this point,
25924 * g_menu_link_iter_get_name() and g_menu_link_iter_get_value() will return the
25925 * same values again.
25927 * The value returned in @out_link remains valid for as long as the iterator
25928 * remains at the current position. The value returned in @value must
25929 * be unreffed using g_object_unref() when it is no longer in use.
25931 * Returns: %TRUE on success, or %FALSE if there is no additional link
25937 * g_menu_link_iter_get_value:
25938 * @iter: a #GMenuLinkIter
25940 * Gets the linked #GMenuModel at the current iterator position.
25942 * The iterator is not advanced.
25944 * Returns: (transfer full): the #GMenuModel that is linked to
25950 * g_menu_link_iter_next:
25951 * @iter: a #GMenuLinkIter
25953 * Attempts to advance the iterator to the next (possibly first)
25956 * %TRUE is returned on success, or %FALSE if there are no more links.
25958 * You must call this function when you first acquire the iterator to
25959 * advance it to the first link (and determine if the first link exists
25962 * Returns: %TRUE on success, or %FALSE when there are no more links
25968 * g_menu_model_get_item_attribute:
25969 * @model: a #GMenuModel
25970 * @item_index: the index of the item
25971 * @attribute: the attribute to query
25972 * @format_string: a #GVariant format string
25973 * @...: positional parameters, as per @format_string
25975 * Queries item at position @item_index in @model for the attribute
25976 * specified by @attribute.
25978 * If the attribute exists and matches the #GVariantType corresponding
25979 * to @format_string then @format_string is used to deconstruct the
25980 * value into the positional parameters and %TRUE is returned.
25982 * If the attribute does not exist, or it does exist but has the wrong
25983 * type, then the positional parameters are ignored and %FALSE is
25986 * This function is a mix of g_menu_model_get_item_attribute_value() and
25987 * g_variant_get(), followed by a g_variant_unref(). As such,
25988 * @format_string must make a complete copy of the data (since the
25989 * #GVariant may go away after the call to g_variant_unref()). In
25990 * particular, no '&' characters are allowed in @format_string.
25992 * Returns: %TRUE if the named attribute was found with the expected
25999 * g_menu_model_get_item_attribute_value:
26000 * @model: a #GMenuModel
26001 * @item_index: the index of the item
26002 * @attribute: the attribute to query
26003 * @expected_type: (allow-none): the expected type of the attribute, or
26006 * Queries the item at position @item_index in @model for the attribute
26007 * specified by @attribute.
26009 * If @expected_type is non-%NULL then it specifies the expected type of
26010 * the attribute. If it is %NULL then any type will be accepted.
26012 * If the attribute exists and matches @expected_type (or if the
26013 * expected type is unspecified) then the value is returned.
26015 * If the attribute does not exist, or does not match the expected type
26016 * then %NULL is returned.
26018 * Returns: (transfer full): the value of the attribute
26024 * g_menu_model_get_item_link:
26025 * @model: a #GMenuModel
26026 * @item_index: the index of the item
26027 * @link: the link to query
26029 * Queries the item at position @item_index in @model for the link
26030 * specified by @link.
26032 * If the link exists, the linked #GMenuModel is returned. If the link
26033 * does not exist, %NULL is returned.
26035 * Returns: (transfer full): the linked #GMenuModel, or %NULL
26041 * g_menu_model_get_n_items:
26042 * @model: a #GMenuModel
26044 * Query the number of items in @model.
26046 * Returns: the number of items
26052 * g_menu_model_is_mutable:
26053 * @model: a #GMenuModel
26055 * Queries if @model is mutable.
26057 * An immutable #GMenuModel will never emit the #GMenuModel::items-changed
26058 * signal. Consumers of the model may make optimisations accordingly.
26060 * Returns: %TRUE if the model is mutable (ie: "items-changed" may be
26067 * g_menu_model_items_changed:
26068 * @model: a #GMenuModel
26069 * @position: the position of the change
26070 * @removed: the number of items removed
26071 * @added: the number of items added
26073 * Requests emission of the #GMenuModel::items-changed signal on @model.
26075 * This function should never be called except by #GMenuModel
26076 * subclasses. Any other calls to this function will very likely lead
26077 * to a violation of the interface of the model.
26079 * The implementation should update its internal representation of the
26080 * menu before emitting the signal. The implementation should further
26081 * expect to receive queries about the new state of the menu (and
26082 * particularly added menu items) while signal handlers are running.
26084 * The implementation must dispatch this call directly from a mainloop
26085 * entry and not in response to calls -- particularly those from the
26086 * #GMenuModel API. Said another way: the menu must not change while
26087 * user code is running without returning to the mainloop.
26094 * g_menu_model_iterate_item_attributes:
26095 * @model: a #GMenuModel
26096 * @item_index: the index of the item
26098 * Creates a #GMenuAttributeIter to iterate over the attributes of
26099 * the item at position @item_index in @model.
26101 * You must free the iterator with g_object_unref() when you are done.
26103 * Returns: (transfer full): a new #GMenuAttributeIter
26109 * g_menu_model_iterate_item_links:
26110 * @model: a #GMenuModel
26111 * @item_index: the index of the item
26113 * Creates a #GMenuLinkIter to iterate over the links of the item at
26114 * position @item_index in @model.
26116 * You must free the iterator with g_object_unref() when you are done.
26118 * Returns: (transfer full): a new #GMenuLinkIter
26126 * Creates a new #GMenu.
26128 * The new menu has no items.
26130 * Returns: a new #GMenu
26138 * @label: (allow-none): the section label, or %NULL
26139 * @detailed_action: (allow-none): the detailed action string, or %NULL
26141 * Convenience function for prepending a normal menu item to the start
26142 * of @menu. Combine g_menu_item_new() and g_menu_insert_item() for a more
26143 * flexible alternative.
26150 * g_menu_prepend_item:
26152 * @item: a #GMenuItem to prepend
26154 * Prepends @item to the start of @menu.
26156 * See g_menu_insert_item() for more information.
26163 * g_menu_prepend_section:
26165 * @label: (allow-none): the section label, or %NULL
26166 * @section: a #GMenuModel with the items of the section
26168 * Convenience function for prepending a section menu item to the start
26169 * of @menu. Combine g_menu_item_new_section() and g_menu_insert_item() for
26170 * a more flexible alternative.
26177 * g_menu_prepend_submenu:
26179 * @label: (allow-none): the section label, or %NULL
26180 * @submenu: a #GMenuModel with the items of the submenu
26182 * Convenience function for prepending a submenu menu item to the start
26183 * of @menu. Combine g_menu_item_new_submenu() and g_menu_insert_item() for
26184 * a more flexible alternative.
26193 * @position: the position of the item to remove
26195 * Removes an item from the menu.
26197 * @position gives the index of the item to remove.
26199 * It is an error if position is not in range the range from 0 to one
26200 * less than the number of items in the menu.
26202 * It is not possible to remove items by identity since items are added
26203 * to the menu simply by copying their links and attributes (ie:
26204 * identity of the item itself is not preserved).
26211 * g_menu_remove_all:
26214 * Removes all items in the menu.
26221 * g_mount_can_eject:
26222 * @mount: a #GMount.
26224 * Checks if @mount can be eject.
26226 * Returns: %TRUE if the @mount can be ejected.
26231 * g_mount_can_unmount:
26232 * @mount: a #GMount.
26234 * Checks if @mount can be mounted.
26236 * Returns: %TRUE if the @mount can be unmounted.
26242 * @mount: a #GMount.
26243 * @flags: flags affecting the unmount if required for eject
26244 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
26245 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
26246 * @user_data: user data passed to @callback.
26248 * Ejects a mount. This is an asynchronous operation, and is
26249 * finished by calling g_mount_eject_finish() with the @mount
26250 * and #GAsyncResult data returned in the @callback.
26252 * Deprecated: 2.22: Use g_mount_eject_with_operation() instead.
26257 * g_mount_eject_finish:
26258 * @mount: a #GMount.
26259 * @result: a #GAsyncResult.
26260 * @error: a #GError location to store the error occurring, or %NULL to
26263 * Finishes ejecting a mount. If any errors occurred during the operation,
26264 * @error will be set to contain the errors and %FALSE will be returned.
26266 * Returns: %TRUE if the mount was successfully ejected. %FALSE otherwise.
26267 * Deprecated: 2.22: Use g_mount_eject_with_operation_finish() instead.
26272 * g_mount_eject_with_operation:
26273 * @mount: a #GMount.
26274 * @flags: flags affecting the unmount if required for eject
26275 * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid
26276 * user interaction.
26277 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
26278 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
26279 * @user_data: user data passed to @callback.
26281 * Ejects a mount. This is an asynchronous operation, and is
26282 * finished by calling g_mount_eject_with_operation_finish() with the @mount
26283 * and #GAsyncResult data returned in the @callback.
26290 * g_mount_eject_with_operation_finish:
26291 * @mount: a #GMount.
26292 * @result: a #GAsyncResult.
26293 * @error: a #GError location to store the error occurring, or %NULL to
26296 * Finishes ejecting a mount. If any errors occurred during the operation,
26297 * @error will be set to contain the errors and %FALSE will be returned.
26299 * Returns: %TRUE if the mount was successfully ejected. %FALSE otherwise.
26305 * g_mount_get_default_location:
26306 * @mount: a #GMount.
26308 * Gets the default location of @mount. The default location of the given
26309 * @mount is a path that reflects the main entry point for the user (e.g.
26310 * the home directory, or the root of the volume).
26312 * Returns: (transfer full): a #GFile.
26313 * The returned object should be unreffed with
26314 * g_object_unref() when no longer needed.
26319 * g_mount_get_drive:
26320 * @mount: a #GMount.
26322 * Gets the drive for the @mount.
26324 * This is a convenience method for getting the #GVolume and then
26325 * using that object to get the #GDrive.
26327 * Returns: (transfer full): a #GDrive or %NULL if @mount is not associated with a volume or a drive.
26328 * The returned object should be unreffed with
26329 * g_object_unref() when no longer needed.
26334 * g_mount_get_icon:
26335 * @mount: a #GMount.
26337 * Gets the icon for @mount.
26339 * Returns: (transfer full): a #GIcon.
26340 * The returned object should be unreffed with
26341 * g_object_unref() when no longer needed.
26346 * g_mount_get_name:
26347 * @mount: a #GMount.
26349 * Gets the name of @mount.
26351 * Returns: the name for the given @mount.
26352 * The returned string should be freed with g_free()
26353 * when no longer needed.
26358 * g_mount_get_root:
26359 * @mount: a #GMount.
26361 * Gets the root directory on @mount.
26363 * Returns: (transfer full): a #GFile.
26364 * The returned object should be unreffed with
26365 * g_object_unref() when no longer needed.
26370 * g_mount_get_sort_key:
26371 * @mount: A #GMount.
26373 * Gets the sort key for @mount, if any.
26375 * Returns: Sorting key for @mount or %NULL if no such key is available.
26381 * g_mount_get_symbolic_icon:
26382 * @mount: a #GMount.
26384 * Gets the symbolic icon for @mount.
26386 * Returns: (transfer full): a #GIcon.
26387 * The returned object should be unreffed with
26388 * g_object_unref() when no longer needed.
26394 * g_mount_get_uuid:
26395 * @mount: a #GMount.
26397 * Gets the UUID for the @mount. The reference is typically based on
26398 * the file system UUID for the mount in question and should be
26399 * considered an opaque string. Returns %NULL if there is no UUID
26402 * Returns: the UUID for @mount or %NULL if no UUID can be computed.
26403 * The returned string should be freed with g_free()
26404 * when no longer needed.
26409 * g_mount_get_volume:
26410 * @mount: a #GMount.
26412 * Gets the volume for the @mount.
26414 * Returns: (transfer full): a #GVolume or %NULL if @mount is not associated with a volume.
26415 * The returned object should be unreffed with
26416 * g_object_unref() when no longer needed.
26421 * g_mount_guess_content_type:
26422 * @mount: a #GMount
26423 * @force_rescan: Whether to force a rescan of the content.
26424 * Otherwise a cached result will be used if available
26425 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
26426 * @callback: a #GAsyncReadyCallback
26427 * @user_data: user data passed to @callback
26429 * Tries to guess the type of content stored on @mount. Returns one or
26430 * more textual identifiers of well-known content types (typically
26431 * prefixed with "x-content/"), e.g. x-content/image-dcf for camera
26432 * memory cards. See the
26433 * [shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec)
26434 * specification for more on x-content types.
26436 * This is an asynchronous operation (see
26437 * g_mount_guess_content_type_sync() for the synchronous version), and
26438 * is finished by calling g_mount_guess_content_type_finish() with the
26439 * @mount and #GAsyncResult data returned in the @callback.
26446 * g_mount_guess_content_type_finish:
26447 * @mount: a #GMount
26448 * @result: a #GAsyncResult
26449 * @error: a #GError location to store the error occurring, or %NULL to
26452 * Finishes guessing content types of @mount. If any errors occurred
26453 * during the operation, @error will be set to contain the errors and
26454 * %FALSE will be returned. In particular, you may get an
26455 * %G_IO_ERROR_NOT_SUPPORTED if the mount does not support content
26458 * Returns: (transfer full) (element-type utf8): a %NULL-terminated array of content types or %NULL on error.
26459 * Caller should free this array with g_strfreev() when done with it.
26465 * g_mount_guess_content_type_sync:
26466 * @mount: a #GMount
26467 * @force_rescan: Whether to force a rescan of the content.
26468 * Otherwise a cached result will be used if available
26469 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
26470 * @error: a #GError location to store the error occurring, or %NULL to
26473 * Tries to guess the type of content stored on @mount. Returns one or
26474 * more textual identifiers of well-known content types (typically
26475 * prefixed with "x-content/"), e.g. x-content/image-dcf for camera
26476 * memory cards. See the
26477 * [shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec)
26478 * specification for more on x-content types.
26480 * This is an synchronous operation and as such may block doing IO;
26481 * see g_mount_guess_content_type() for the asynchronous version.
26483 * Returns: (transfer full) (element-type utf8): a %NULL-terminated array of content types or %NULL on error.
26484 * Caller should free this array with g_strfreev() when done with it.
26490 * g_mount_is_shadowed:
26491 * @mount: A #GMount.
26493 * Determines if @mount is shadowed. Applications or libraries should
26494 * avoid displaying @mount in the user interface if it is shadowed.
26496 * A mount is said to be shadowed if there exists one or more user
26497 * visible objects (currently #GMount objects) with a root that is
26498 * inside the root of @mount.
26500 * One application of shadow mounts is when exposing a single file
26501 * system that is used to address several logical volumes. In this
26502 * situation, a #GVolumeMonitor implementation would create two
26503 * #GVolume objects (for example, one for the camera functionality of
26504 * the device and one for a SD card reader on the device) with
26505 * activation URIs `gphoto2://[usb:001,002]/store1/`
26506 * and `gphoto2://[usb:001,002]/store2/`. When the
26507 * underlying mount (with root
26508 * `gphoto2://[usb:001,002]/`) is mounted, said
26509 * #GVolumeMonitor implementation would create two #GMount objects
26510 * (each with their root matching the corresponding volume activation
26511 * root) that would shadow the original mount.
26513 * The proxy monitor in GVfs 2.26 and later, automatically creates and
26514 * manage shadow mounts (and shadows the underlying mount) if the
26515 * activation root on a #GVolume is set.
26517 * Returns: %TRUE if @mount is shadowed.
26523 * g_mount_operation_get_anonymous:
26524 * @op: a #GMountOperation.
26526 * Check to see whether the mount operation is being used
26527 * for an anonymous user.
26529 * Returns: %TRUE if mount operation is anonymous.
26534 * g_mount_operation_get_choice:
26535 * @op: a #GMountOperation.
26537 * Gets a choice from the mount operation.
26539 * Returns: an integer containing an index of the user's choice from
26540 * the choice's list, or %0.
26545 * g_mount_operation_get_domain:
26546 * @op: a #GMountOperation.
26548 * Gets the domain of the mount operation.
26550 * Returns: a string set to the domain.
26555 * g_mount_operation_get_password:
26556 * @op: a #GMountOperation.
26558 * Gets a password from the mount operation.
26560 * Returns: a string containing the password within @op.
26565 * g_mount_operation_get_password_save:
26566 * @op: a #GMountOperation.
26568 * Gets the state of saving passwords for the mount operation.
26570 * Returns: a #GPasswordSave flag.
26575 * g_mount_operation_get_username:
26576 * @op: a #GMountOperation.
26578 * Get the user name from the mount operation.
26580 * Returns: a string containing the user name.
26585 * g_mount_operation_new:
26587 * Creates a new mount operation.
26589 * Returns: a #GMountOperation.
26594 * g_mount_operation_reply:
26595 * @op: a #GMountOperation
26596 * @result: a #GMountOperationResult
26598 * Emits the #GMountOperation::reply signal.
26603 * g_mount_operation_set_anonymous:
26604 * @op: a #GMountOperation.
26605 * @anonymous: boolean value.
26607 * Sets the mount operation to use an anonymous user if @anonymous is %TRUE.
26612 * g_mount_operation_set_choice:
26613 * @op: a #GMountOperation.
26614 * @choice: an integer.
26616 * Sets a default choice for the mount operation.
26621 * g_mount_operation_set_domain:
26622 * @op: a #GMountOperation.
26623 * @domain: the domain to set.
26625 * Sets the mount operation's domain.
26630 * g_mount_operation_set_password:
26631 * @op: a #GMountOperation.
26632 * @password: password to set.
26634 * Sets the mount operation's password to @password.
26639 * g_mount_operation_set_password_save:
26640 * @op: a #GMountOperation.
26641 * @save: a set of #GPasswordSave flags.
26643 * Sets the state of saving passwords for the mount operation.
26648 * g_mount_operation_set_username:
26649 * @op: a #GMountOperation.
26650 * @username: input username.
26652 * Sets the user name within @op to @username.
26658 * @mount: a #GMount.
26659 * @flags: flags affecting the operation
26660 * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid
26661 * user interaction.
26662 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
26663 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
26664 * @user_data: user data passed to @callback.
26666 * Remounts a mount. This is an asynchronous operation, and is
26667 * finished by calling g_mount_remount_finish() with the @mount
26668 * and #GAsyncResults data returned in the @callback.
26670 * Remounting is useful when some setting affecting the operation
26671 * of the volume has been changed, as these may need a remount to
26672 * take affect. While this is semantically equivalent with unmounting
26673 * and then remounting not all backends might need to actually be
26679 * g_mount_remount_finish:
26680 * @mount: a #GMount.
26681 * @result: a #GAsyncResult.
26682 * @error: a #GError location to store the error occurring, or %NULL to
26685 * Finishes remounting a mount. If any errors occurred during the operation,
26686 * @error will be set to contain the errors and %FALSE will be returned.
26688 * Returns: %TRUE if the mount was successfully remounted. %FALSE otherwise.
26694 * @mount: A #GMount.
26696 * Increments the shadow count on @mount. Usually used by
26697 * #GVolumeMonitor implementations when creating a shadow mount for
26698 * @mount, see g_mount_is_shadowed() for more information. The caller
26699 * will need to emit the #GMount::changed signal on @mount manually.
26707 * @mount: a #GMount.
26708 * @flags: flags affecting the operation
26709 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
26710 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
26711 * @user_data: user data passed to @callback.
26713 * Unmounts a mount. This is an asynchronous operation, and is
26714 * finished by calling g_mount_unmount_finish() with the @mount
26715 * and #GAsyncResult data returned in the @callback.
26717 * Deprecated: 2.22: Use g_mount_unmount_with_operation() instead.
26722 * g_mount_unmount_finish:
26723 * @mount: a #GMount.
26724 * @result: a #GAsyncResult.
26725 * @error: a #GError location to store the error occurring, or %NULL to
26728 * Finishes unmounting a mount. If any errors occurred during the operation,
26729 * @error will be set to contain the errors and %FALSE will be returned.
26731 * Returns: %TRUE if the mount was successfully unmounted. %FALSE otherwise.
26732 * Deprecated: 2.22: Use g_mount_unmount_with_operation_finish() instead.
26737 * g_mount_unmount_with_operation:
26738 * @mount: a #GMount.
26739 * @flags: flags affecting the operation
26740 * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid
26741 * user interaction.
26742 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
26743 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
26744 * @user_data: user data passed to @callback.
26746 * Unmounts a mount. This is an asynchronous operation, and is
26747 * finished by calling g_mount_unmount_with_operation_finish() with the @mount
26748 * and #GAsyncResult data returned in the @callback.
26755 * g_mount_unmount_with_operation_finish:
26756 * @mount: a #GMount.
26757 * @result: a #GAsyncResult.
26758 * @error: a #GError location to store the error occurring, or %NULL to
26761 * Finishes unmounting a mount. If any errors occurred during the operation,
26762 * @error will be set to contain the errors and %FALSE will be returned.
26764 * Returns: %TRUE if the mount was successfully unmounted. %FALSE otherwise.
26770 * g_mount_unshadow:
26771 * @mount: A #GMount.
26773 * Decrements the shadow count on @mount. Usually used by
26774 * #GVolumeMonitor implementations when destroying a shadow mount for
26775 * @mount, see g_mount_is_shadowed() for more information. The caller
26776 * will need to emit the #GMount::changed signal on @mount manually.
26783 * g_network_address_get_hostname:
26784 * @addr: a #GNetworkAddress
26786 * Gets @addr's hostname. This might be either UTF-8 or ASCII-encoded,
26787 * depending on what @addr was created with.
26789 * Returns: @addr's hostname
26795 * g_network_address_get_port:
26796 * @addr: a #GNetworkAddress
26798 * Gets @addr's port number
26800 * Returns: @addr's port (which may be 0)
26806 * g_network_address_get_scheme:
26807 * @addr: a #GNetworkAddress
26809 * Gets @addr's scheme
26811 * Returns: @addr's scheme (%NULL if not built from URI)
26817 * g_network_address_new:
26818 * @hostname: the hostname
26821 * Creates a new #GSocketConnectable for connecting to the given
26822 * @hostname and @port.
26824 * Returns: (transfer full) (type GNetworkAddress): the new #GNetworkAddress
26830 * g_network_address_parse:
26831 * @host_and_port: the hostname and optionally a port
26832 * @default_port: the default port if not in @host_and_port
26833 * @error: a pointer to a #GError, or %NULL
26835 * Creates a new #GSocketConnectable for connecting to the given
26836 * @hostname and @port. May fail and return %NULL in case
26837 * parsing @host_and_port fails.
26839 * @host_and_port may be in any of a number of recognised formats; an IPv6
26840 * address, an IPv4 address, or a domain name (in which case a DNS
26841 * lookup is performed). Quoting with [] is supported for all address
26842 * types. A port override may be specified in the usual way with a
26845 * If no port is specified in @host_and_port then @default_port will be
26846 * used as the port number to connect to.
26848 * In general, @host_and_port is expected to be provided by the user
26849 * (allowing them to give the hostname, and a port overide if necessary)
26850 * and @default_port is expected to be provided by the application.
26852 * (The port component of @host_and_port can also be specified as a
26853 * service name rather than as a numeric port, but this functionality
26854 * is deprecated, because it depends on the contents of /etc/services,
26855 * which is generally quite sparse on platforms other than Linux.)
26857 * Returns: (transfer full): the new #GNetworkAddress, or %NULL on error
26863 * g_network_address_parse_uri:
26864 * @uri: the hostname and optionally a port
26865 * @default_port: The default port if none is found in the URI
26866 * @error: a pointer to a #GError, or %NULL
26868 * Creates a new #GSocketConnectable for connecting to the given
26869 * @uri. May fail and return %NULL in case parsing @uri fails.
26871 * Using this rather than g_network_address_new() or
26872 * g_network_address_parse() allows #GSocketClient to determine
26873 * when to use application-specific proxy protocols.
26875 * Returns: (transfer full): the new #GNetworkAddress, or %NULL on error
26881 * g_network_monitor_base_add_network:
26882 * @monitor: the #GNetworkMonitorBase
26883 * @network: a #GInetAddressMask
26885 * Adds @network to @monitor's list of available networks.
26892 * g_network_monitor_base_remove_network:
26893 * @monitor: the #GNetworkMonitorBase
26894 * @network: a #GInetAddressMask
26896 * Removes @network from @monitor's list of available networks.
26903 * g_network_monitor_base_set_networks:
26904 * @monitor: the #GNetworkMonitorBase
26905 * @networks: (array length=length): an array of #GInetAddressMask
26906 * @length: length of @networks
26908 * Drops @monitor's current list of available networks and replaces
26909 * it with @networks.
26914 * g_network_monitor_can_reach:
26915 * @monitor: a #GNetworkMonitor
26916 * @connectable: a #GSocketConnectable
26917 * @cancellable: (allow-none): a #GCancellable, or %NULL
26918 * @error: return location for a #GError, or %NULL
26920 * Attempts to determine whether or not the host pointed to by
26921 * @connectable can be reached, without actually trying to connect to
26924 * This may return %TRUE even when #GNetworkMonitor:network-available
26925 * is %FALSE, if, for example, @monitor can determine that
26926 * @connectable refers to a host on a local network.
26928 * If @monitor believes that an attempt to connect to @connectable
26929 * will succeed, it will return %TRUE. Otherwise, it will return
26930 * %FALSE and set @error to an appropriate error (such as
26931 * %G_IO_ERROR_HOST_UNREACHABLE).
26933 * Note that although this does not attempt to connect to
26934 * @connectable, it may still block for a brief period of time (eg,
26935 * trying to do multicast DNS on the local network), so if you do not
26936 * want to block, you should use g_network_monitor_can_reach_async().
26938 * Returns: %TRUE if @connectable is reachable, %FALSE if not.
26944 * g_network_monitor_can_reach_async:
26945 * @monitor: a #GNetworkMonitor
26946 * @connectable: a #GSocketConnectable
26947 * @cancellable: (allow-none): a #GCancellable, or %NULL
26948 * @callback: (scope async): a #GAsyncReadyCallback to call when the
26949 * request is satisfied
26950 * @user_data: (closure): the data to pass to callback function
26952 * Asynchronously attempts to determine whether or not the host
26953 * pointed to by @connectable can be reached, without actually
26954 * trying to connect to it.
26956 * For more details, see g_network_monitor_can_reach().
26958 * When the operation is finished, @callback will be called.
26959 * You can then call g_network_monitor_can_reach_finish()
26960 * to get the result of the operation.
26965 * g_network_monitor_can_reach_finish:
26966 * @monitor: a #GNetworkMonitor
26967 * @result: a #GAsyncResult
26968 * @error: return location for errors, or %NULL
26970 * Finishes an async network connectivity test.
26971 * See g_network_monitor_can_reach_async().
26973 * Returns: %TRUE if network is reachable, %FALSE if not.
26978 * g_network_monitor_get_default:
26980 * Gets the default #GNetworkMonitor for the system.
26982 * Returns: (transfer none): a #GNetworkMonitor
26988 * g_network_monitor_get_network_available:
26989 * @monitor: the #GNetworkMonitor
26991 * Checks if the network is available. "Available" here means that the
26992 * system has a default route available for at least one of IPv4 or
26993 * IPv6. It does not necessarily imply that the public Internet is
26994 * reachable. See #GNetworkMonitor:network-available for more details.
26996 * Returns: whether the network is available
27002 * g_network_service_get_domain:
27003 * @srv: a #GNetworkService
27005 * Gets the domain that @srv serves. This might be either UTF-8 or
27006 * ASCII-encoded, depending on what @srv was created with.
27008 * Returns: @srv's domain name
27014 * g_network_service_get_protocol:
27015 * @srv: a #GNetworkService
27017 * Gets @srv's protocol name (eg, "tcp").
27019 * Returns: @srv's protocol name
27025 * g_network_service_get_scheme:
27026 * @srv: a #GNetworkService
27028 * Get's the URI scheme used to resolve proxies. By default, the service name
27029 * is used as scheme.
27031 * Returns: @srv's scheme name
27037 * g_network_service_get_service:
27038 * @srv: a #GNetworkService
27040 * Gets @srv's service name (eg, "ldap").
27042 * Returns: @srv's service name
27048 * g_network_service_new:
27049 * @service: the service type to look up (eg, "ldap")
27050 * @protocol: the networking protocol to use for @service (eg, "tcp")
27051 * @domain: the DNS domain to look up the service in
27053 * Creates a new #GNetworkService representing the given @service,
27054 * @protocol, and @domain. This will initially be unresolved; use the
27055 * #GSocketConnectable interface to resolve it.
27057 * Returns: (transfer full) (type GNetworkService): a new #GNetworkService
27063 * g_network_service_set_scheme:
27064 * @srv: a #GNetworkService
27065 * @scheme: a URI scheme
27067 * Set's the URI scheme used to resolve proxies. By default, the service name
27068 * is used as scheme.
27075 * g_networking_init:
27077 * Initializes the platform networking libraries (eg, on Windows, this
27078 * calls WSAStartup()). GLib will call this itself if it is needed, so
27079 * you only need to call it if you directly call system networking
27080 * functions (without calling any GLib networking functions first).
27087 * g_notification_add_button:
27088 * @notification: a #GNotification
27089 * @label: label of the button
27090 * @detailed_action: a detailed action name
27092 * Adds a button to @notification that activates the action in
27093 * @detailed_action when clicked. That action must be an
27094 * application-wide action (starting with "app."). If @detailed_action
27095 * contains a target, the action will be activated with that target as
27098 * See g_action_parse_detailed_name() for a description of the format
27099 * for @detailed_action.
27106 * g_notification_add_button_with_target: (skip)
27107 * @notification: a #GNotification
27108 * @label: label of the button
27109 * @action: an action name
27110 * @target_format: (allow-none): a #GVariant format string, or %NULL
27111 * @...: positional parameters, as determined by @target_format
27113 * Adds a button to @notification that activates @action when clicked.
27114 * @action must be an application-wide action (it must start with "app.").
27116 * If @target_format is given, it is used to collect remaining
27117 * positional parameters into a #GVariant instance, similar to
27118 * g_variant_new(). @action will be activated with that #GVariant as its
27126 * g_notification_add_button_with_target_value: (rename-to g_notification_add_button_with_target)
27127 * @notification: a #GNotification
27128 * @label: label of the button
27129 * @action: an action name
27130 * @target: (allow-none): a #GVariant to use as @action's parameter, or %NULL
27132 * Adds a button to @notification that activates @action when clicked.
27133 * @action must be an application-wide action (it must start with "app.").
27135 * If @target is non-%NULL, @action will be activated with @target as
27143 * g_notification_new:
27144 * @title: the title of the notification
27146 * Creates a new #GNotification with @title as its title.
27148 * After populating @notification with more details, it can be sent to
27149 * the desktop shell with g_application_send_notification(). Changing
27150 * any properties after this call will not have any effect until
27151 * resending @notification.
27153 * Returns: a new #GNotification instance
27159 * g_notification_set_body:
27160 * @notification: a #GNotification
27161 * @body: (allow-none): the new body for @notification, or %NULL
27163 * Sets the body of @notification to @body.
27170 * g_notification_set_default_action:
27171 * @notification: a #GNotification
27172 * @detailed_action: a detailed action name
27174 * Sets the default action of @notification to @detailed_action. This
27175 * action is activated when the notification is clicked on.
27177 * The action in @detailed_action must be an application-wide action (it
27178 * must start with "app."). If @detailed_action contains a target, the
27179 * given action will be activated with that target as its parameter.
27180 * See g_action_parse_detailed_name() for a description of the format
27181 * for @detailed_action.
27183 * When no default action is set, the application that the notification
27184 * was sent on is activated.
27191 * g_notification_set_default_action_and_target: (skip)
27192 * @notification: a #GNotification
27193 * @action: an action name
27194 * @target_format: (allow-none): a #GVariant format string, or %NULL
27195 * @...: positional parameters, as determined by @target_format
27197 * Sets the default action of @notification to @action. This action is
27198 * activated when the notification is clicked on. It must be an
27199 * application-wide action (it must start with "app.").
27201 * If @target_format is given, it is used to collect remaining
27202 * positional parameters into a #GVariant instance, similar to
27203 * g_variant_new(). @action will be activated with that #GVariant as its
27206 * When no default action is set, the application that the notification
27207 * was sent on is activated.
27214 * g_notification_set_default_action_and_target_value: (rename-to g_notification_set_default_action_and_target)
27215 * @notification: a #GNotification
27216 * @action: an action name
27217 * @target: (allow-none): a #GVariant to use as @action's parameter, or %NULL
27219 * Sets the default action of @notification to @action. This action is
27220 * activated when the notification is clicked on. It must be an
27221 * application-wide action (start with "app.").
27223 * If @target is non-%NULL, @action will be activated with @target as
27226 * When no default action is set, the application that the notification
27227 * was sent on is activated.
27234 * g_notification_set_icon:
27235 * @notification: a #GNotification
27236 * @icon: the icon to be shown in @notification, as a #GIcon
27238 * Sets the icon of @notification to @icon.
27245 * g_notification_set_priority:
27246 * @notification: a #GNotification
27247 * @priority: a #GNotificationPriority
27249 * Sets the priority of @notification to @priority. See
27250 * #GNotificationPriority for possible values.
27255 * g_notification_set_title:
27256 * @notification: a #GNotification
27257 * @title: the new title for @notification
27259 * Sets the title of @notification to @title.
27266 * g_notification_set_urgent:
27267 * @notification: a #GNotification
27268 * @urgent: %TRUE if @notification is urgent
27270 * Deprecated in favor of g_notification_set_priority().
27277 * g_null_settings_backend_new:
27279 * Creates a readonly #GSettingsBackend.
27281 * This backend does not allow changes to settings, so all settings
27282 * will always have their default values.
27284 * Returns: (transfer full): a newly created #GSettingsBackend
27290 * g_output_stream_async_write_is_via_threads:
27291 * @stream: a #GOutputStream.
27293 * Checks if an ouput stream's write_async function uses threads.
27295 * Returns: %TRUE if @stream's write_async function uses threads.
27300 * g_output_stream_clear_pending:
27301 * @stream: output stream
27303 * Clears the pending flag on @stream.
27308 * g_output_stream_close:
27309 * @stream: A #GOutputStream.
27310 * @cancellable: (allow-none): optional cancellable object
27311 * @error: location to store the error occurring, or %NULL to ignore
27313 * Closes the stream, releasing resources related to it.
27315 * Once the stream is closed, all other operations will return %G_IO_ERROR_CLOSED.
27316 * Closing a stream multiple times will not return an error.
27318 * Closing a stream will automatically flush any outstanding buffers in the
27321 * Streams will be automatically closed when the last reference
27322 * is dropped, but you might want to call this function to make sure
27323 * resources are released as early as possible.
27325 * Some streams might keep the backing store of the stream (e.g. a file descriptor)
27326 * open after the stream is closed. See the documentation for the individual
27327 * stream for details.
27329 * On failure the first error that happened will be reported, but the close
27330 * operation will finish as much as possible. A stream that failed to
27331 * close will still return %G_IO_ERROR_CLOSED for all operations. Still, it
27332 * is important to check and report the error to the user, otherwise
27333 * there might be a loss of data as all data might not be written.
27335 * If @cancellable is not %NULL, then the operation can be cancelled by
27336 * triggering the cancellable object from another thread. If the operation
27337 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
27338 * Cancelling a close will still leave the stream closed, but there some streams
27339 * can use a faster close that doesn't block to e.g. check errors. On
27340 * cancellation (as with any error) there is no guarantee that all written
27341 * data will reach the target.
27343 * Returns: %TRUE on success, %FALSE on failure
27348 * g_output_stream_close_async:
27349 * @stream: A #GOutputStream.
27350 * @io_priority: the io priority of the request.
27351 * @cancellable: (allow-none): optional cancellable object
27352 * @callback: (scope async): callback to call when the request is satisfied
27353 * @user_data: (closure): the data to pass to callback function
27355 * Requests an asynchronous close of the stream, releasing resources
27356 * related to it. When the operation is finished @callback will be
27357 * called. You can then call g_output_stream_close_finish() to get
27358 * the result of the operation.
27360 * For behaviour details see g_output_stream_close().
27362 * The asyncronous methods have a default fallback that uses threads
27363 * to implement asynchronicity, so they are optional for inheriting
27364 * classes. However, if you override one you must override all.
27369 * g_output_stream_close_finish:
27370 * @stream: a #GOutputStream.
27371 * @result: a #GAsyncResult.
27372 * @error: a #GError location to store the error occurring, or %NULL to
27375 * Closes an output stream.
27377 * Returns: %TRUE if stream was successfully closed, %FALSE otherwise.
27382 * g_output_stream_flush:
27383 * @stream: a #GOutputStream.
27384 * @cancellable: (allow-none): optional cancellable object
27385 * @error: location to store the error occurring, or %NULL to ignore
27387 * Forces a write of all user-space buffered data for the given
27388 * @stream. Will block during the operation. Closing the stream will
27389 * implicitly cause a flush.
27391 * This function is optional for inherited classes.
27393 * If @cancellable is not %NULL, then the operation can be cancelled by
27394 * triggering the cancellable object from another thread. If the operation
27395 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
27397 * Returns: %TRUE on success, %FALSE on error
27402 * g_output_stream_flush_async:
27403 * @stream: a #GOutputStream.
27404 * @io_priority: the io priority of the request.
27405 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
27406 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
27407 * @user_data: (closure): the data to pass to callback function
27409 * Forces an asynchronous write of all user-space buffered data for
27410 * the given @stream.
27411 * For behaviour details see g_output_stream_flush().
27413 * When the operation is finished @callback will be
27414 * called. You can then call g_output_stream_flush_finish() to get the
27415 * result of the operation.
27420 * g_output_stream_flush_finish:
27421 * @stream: a #GOutputStream.
27422 * @result: a GAsyncResult.
27423 * @error: a #GError location to store the error occurring, or %NULL to
27426 * Finishes flushing an output stream.
27428 * Returns: %TRUE if flush operation succeeded, %FALSE otherwise.
27433 * g_output_stream_has_pending:
27434 * @stream: a #GOutputStream.
27436 * Checks if an ouput stream has pending actions.
27438 * Returns: %TRUE if @stream has pending actions.
27443 * g_output_stream_is_closed:
27444 * @stream: a #GOutputStream.
27446 * Checks if an output stream has already been closed.
27448 * Returns: %TRUE if @stream is closed. %FALSE otherwise.
27453 * g_output_stream_is_closing:
27454 * @stream: a #GOutputStream.
27456 * Checks if an output stream is being closed. This can be
27457 * used inside e.g. a flush implementation to see if the
27458 * flush (or other i/o operation) is called from within
27459 * the closing operation.
27461 * Returns: %TRUE if @stream is being closed. %FALSE otherwise.
27467 * g_output_stream_printf:
27468 * @stream: a #GOutputStream.
27469 * @bytes_written: (out): location to store the number of bytes that was
27470 * written to the stream
27471 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
27472 * @error: location to store the error occurring, or %NULL to ignore
27473 * @format: the format string. See the printf() documentation
27474 * @...: the parameters to insert into the format string
27476 * This is a utility function around g_output_stream_write_all(). It
27477 * uses g_strdup_vprintf() to turn @format and @... into a string that
27478 * is then written to @stream.
27480 * See the documentation of g_output_stream_write_all() about the
27481 * behavior of the actual write operation.
27483 * Note that partial writes cannot be properly checked with this
27484 * function due to the variable length of the written string, if you
27485 * need precise control over partial write failures, you need to
27486 * create you own printf()-like wrapper around g_output_stream_write()
27487 * or g_output_stream_write_all().
27490 * Returns: %TRUE on success, %FALSE if there was an error
27495 * g_output_stream_set_pending:
27496 * @stream: a #GOutputStream.
27497 * @error: a #GError location to store the error occurring, or %NULL to
27500 * Sets @stream to have actions pending. If the pending flag is
27501 * already set or @stream is closed, it will return %FALSE and set
27504 * Returns: %TRUE if pending was previously unset and is now set.
27509 * g_output_stream_splice:
27510 * @stream: a #GOutputStream.
27511 * @source: a #GInputStream.
27512 * @flags: a set of #GOutputStreamSpliceFlags.
27513 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
27514 * @error: a #GError location to store the error occurring, or %NULL to
27517 * Splices an input stream into an output stream.
27519 * Returns: a #gssize containing the size of the data spliced, or
27520 * -1 if an error occurred. Note that if the number of bytes
27521 * spliced is greater than %G_MAXSSIZE, then that will be
27522 * returned, and there is no way to determine the actual number
27523 * of bytes spliced.
27528 * g_output_stream_splice_async:
27529 * @stream: a #GOutputStream.
27530 * @source: a #GInputStream.
27531 * @flags: a set of #GOutputStreamSpliceFlags.
27532 * @io_priority: the io priority of the request.
27533 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
27534 * @callback: (scope async): a #GAsyncReadyCallback.
27535 * @user_data: (closure): user data passed to @callback.
27537 * Splices a stream asynchronously.
27538 * When the operation is finished @callback will be called.
27539 * You can then call g_output_stream_splice_finish() to get the
27540 * result of the operation.
27542 * For the synchronous, blocking version of this function, see
27543 * g_output_stream_splice().
27548 * g_output_stream_splice_finish:
27549 * @stream: a #GOutputStream.
27550 * @result: a #GAsyncResult.
27551 * @error: a #GError location to store the error occurring, or %NULL to
27554 * Finishes an asynchronous stream splice operation.
27556 * Returns: a #gssize of the number of bytes spliced. Note that if the
27557 * number of bytes spliced is greater than %G_MAXSSIZE, then that
27558 * will be returned, and there is no way to determine the actual
27559 * number of bytes spliced.
27564 * g_output_stream_vprintf:
27565 * @stream: a #GOutputStream.
27566 * @bytes_written: (out): location to store the number of bytes that was
27567 * written to the stream
27568 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
27569 * @error: location to store the error occurring, or %NULL to ignore
27570 * @format: the format string. See the printf() documentation
27571 * @args: the parameters to insert into the format string
27573 * This is a utility function around g_output_stream_write_all(). It
27574 * uses g_strdup_vprintf() to turn @format and @args into a string that
27575 * is then written to @stream.
27577 * See the documentation of g_output_stream_write_all() about the
27578 * behavior of the actual write operation.
27580 * Note that partial writes cannot be properly checked with this
27581 * function due to the variable length of the written string, if you
27582 * need precise control over partial write failures, you need to
27583 * create you own printf()-like wrapper around g_output_stream_write()
27584 * or g_output_stream_write_all().
27587 * Returns: %TRUE on success, %FALSE if there was an error
27592 * g_output_stream_write: (virtual write_fn)
27593 * @stream: a #GOutputStream.
27594 * @buffer: (array length=count) (element-type guint8): the buffer containing the data to write.
27595 * @count: the number of bytes to write
27596 * @cancellable: (allow-none): optional cancellable object
27597 * @error: location to store the error occurring, or %NULL to ignore
27599 * Tries to write @count bytes from @buffer into the stream. Will block
27600 * during the operation.
27602 * If count is 0, returns 0 and does nothing. A value of @count
27603 * larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
27605 * On success, the number of bytes written to the stream is returned.
27606 * It is not an error if this is not the same as the requested size, as it
27607 * can happen e.g. on a partial I/O error, or if there is not enough
27608 * storage in the stream. All writes block until at least one byte
27609 * is written or an error occurs; 0 is never returned (unless
27612 * If @cancellable is not %NULL, then the operation can be cancelled by
27613 * triggering the cancellable object from another thread. If the operation
27614 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
27615 * operation was partially finished when the operation was cancelled the
27616 * partial result will be returned, without an error.
27618 * On error -1 is returned and @error is set accordingly.
27620 * Returns: Number of bytes written, or -1 on error
27625 * g_output_stream_write_all:
27626 * @stream: a #GOutputStream.
27627 * @buffer: (array length=count) (element-type guint8): the buffer containing the data to write.
27628 * @count: the number of bytes to write
27629 * @bytes_written: (out): location to store the number of bytes that was
27630 * written to the stream
27631 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
27632 * @error: location to store the error occurring, or %NULL to ignore
27634 * Tries to write @count bytes from @buffer into the stream. Will block
27635 * during the operation.
27637 * This function is similar to g_output_stream_write(), except it tries to
27638 * write as many bytes as requested, only stopping on an error.
27640 * On a successful write of @count bytes, %TRUE is returned, and @bytes_written
27641 * is set to @count.
27643 * If there is an error during the operation %FALSE is returned and @error
27644 * is set to indicate the error status, @bytes_written is updated to contain
27645 * the number of bytes written into the stream before the error occurred.
27647 * Returns: %TRUE on success, %FALSE if there was an error
27652 * g_output_stream_write_async:
27653 * @stream: A #GOutputStream.
27654 * @buffer: (array length=count) (element-type guint8): the buffer containing the data to write.
27655 * @count: the number of bytes to write
27656 * @io_priority: the io priority of the request.
27657 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
27658 * @callback: (scope async): callback to call when the request is satisfied
27659 * @user_data: (closure): the data to pass to callback function
27661 * Request an asynchronous write of @count bytes from @buffer into
27662 * the stream. When the operation is finished @callback will be called.
27663 * You can then call g_output_stream_write_finish() to get the result of the
27666 * During an async request no other sync and async calls are allowed,
27667 * and will result in %G_IO_ERROR_PENDING errors.
27669 * A value of @count larger than %G_MAXSSIZE will cause a
27670 * %G_IO_ERROR_INVALID_ARGUMENT error.
27672 * On success, the number of bytes written will be passed to the
27673 * @callback. It is not an error if this is not the same as the
27674 * requested size, as it can happen e.g. on a partial I/O error,
27675 * but generally we try to write as many bytes as requested.
27677 * You are guaranteed that this method will never fail with
27678 * %G_IO_ERROR_WOULD_BLOCK - if @stream can't accept more data, the
27679 * method will just wait until this changes.
27681 * Any outstanding I/O request with higher priority (lower numerical
27682 * value) will be executed before an outstanding request with lower
27683 * priority. Default priority is %G_PRIORITY_DEFAULT.
27685 * The asyncronous methods have a default fallback that uses threads
27686 * to implement asynchronicity, so they are optional for inheriting
27687 * classes. However, if you override one you must override all.
27689 * For the synchronous, blocking version of this function, see
27690 * g_output_stream_write().
27692 * Note that no copy of @buffer will be made, so it must stay valid
27693 * until @callback is called. See g_output_stream_write_bytes_async()
27694 * for a #GBytes version that will automatically hold a reference to
27695 * the contents (without copying) for the duration of the call.
27700 * g_output_stream_write_bytes:
27701 * @stream: a #GOutputStream.
27702 * @bytes: the #GBytes to write
27703 * @cancellable: (allow-none): optional cancellable object
27704 * @error: location to store the error occurring, or %NULL to ignore
27706 * A wrapper function for g_output_stream_write() which takes a
27707 * #GBytes as input. This can be more convenient for use by language
27708 * bindings or in other cases where the refcounted nature of #GBytes
27709 * is helpful over a bare pointer interface.
27711 * However, note that this function may still perform partial writes,
27712 * just like g_output_stream_write(). If that occurs, to continue
27713 * writing, you will need to create a new #GBytes containing just the
27714 * remaining bytes, using g_bytes_new_from_bytes(). Passing the same
27715 * #GBytes instance multiple times potentially can result in duplicated
27716 * data in the output stream.
27718 * Returns: Number of bytes written, or -1 on error
27723 * g_output_stream_write_bytes_async:
27724 * @stream: A #GOutputStream.
27725 * @bytes: The bytes to write
27726 * @io_priority: the io priority of the request.
27727 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
27728 * @callback: (scope async): callback to call when the request is satisfied
27729 * @user_data: (closure): the data to pass to callback function
27731 * This function is similar to g_output_stream_write_async(), but
27732 * takes a #GBytes as input. Due to the refcounted nature of #GBytes,
27733 * this allows the stream to avoid taking a copy of the data.
27735 * However, note that this function may still perform partial writes,
27736 * just like g_output_stream_write_async(). If that occurs, to continue
27737 * writing, you will need to create a new #GBytes containing just the
27738 * remaining bytes, using g_bytes_new_from_bytes(). Passing the same
27739 * #GBytes instance multiple times potentially can result in duplicated
27740 * data in the output stream.
27742 * For the synchronous, blocking version of this function, see
27743 * g_output_stream_write_bytes().
27748 * g_output_stream_write_bytes_finish:
27749 * @stream: a #GOutputStream.
27750 * @result: a #GAsyncResult.
27751 * @error: a #GError location to store the error occurring, or %NULL to
27754 * Finishes a stream write-from-#GBytes operation.
27756 * Returns: a #gssize containing the number of bytes written to the stream.
27761 * g_output_stream_write_finish:
27762 * @stream: a #GOutputStream.
27763 * @result: a #GAsyncResult.
27764 * @error: a #GError location to store the error occurring, or %NULL to
27767 * Finishes a stream write operation.
27769 * Returns: a #gssize containing the number of bytes written to the stream.
27774 * g_permission_acquire:
27775 * @permission: a #GPermission instance
27776 * @cancellable: (allow-none): a #GCancellable, or %NULL
27777 * @error: a pointer to a %NULL #GError, or %NULL
27779 * Attempts to acquire the permission represented by @permission.
27781 * The precise method by which this happens depends on the permission
27782 * and the underlying authentication mechanism. A simple example is
27783 * that a dialog may appear asking the user to enter their password.
27785 * You should check with g_permission_get_can_acquire() before calling
27788 * If the permission is acquired then %TRUE is returned. Otherwise,
27789 * %FALSE is returned and @error is set appropriately.
27791 * This call is blocking, likely for a very long time (in the case that
27792 * user interaction is required). See g_permission_acquire_async() for
27793 * the non-blocking version.
27795 * Returns: %TRUE if the permission was successfully acquired
27801 * g_permission_acquire_async:
27802 * @permission: a #GPermission instance
27803 * @cancellable: (allow-none): a #GCancellable, or %NULL
27804 * @callback: the #GAsyncReadyCallback to call when done
27805 * @user_data: the user data to pass to @callback
27807 * Attempts to acquire the permission represented by @permission.
27809 * This is the first half of the asynchronous version of
27810 * g_permission_acquire().
27817 * g_permission_acquire_finish:
27818 * @permission: a #GPermission instance
27819 * @result: the #GAsyncResult given to the #GAsyncReadyCallback
27820 * @error: a pointer to a %NULL #GError, or %NULL
27822 * Collects the result of attempting to acquire the permission
27823 * represented by @permission.
27825 * This is the second half of the asynchronous version of
27826 * g_permission_acquire().
27828 * Returns: %TRUE if the permission was successfully acquired
27834 * g_permission_get_allowed:
27835 * @permission: a #GPermission instance
27837 * Gets the value of the 'allowed' property. This property is %TRUE if
27838 * the caller currently has permission to perform the action that
27839 * @permission represents the permission to perform.
27841 * Returns: the value of the 'allowed' property
27847 * g_permission_get_can_acquire:
27848 * @permission: a #GPermission instance
27850 * Gets the value of the 'can-acquire' property. This property is %TRUE
27851 * if it is generally possible to acquire the permission by calling
27852 * g_permission_acquire().
27854 * Returns: the value of the 'can-acquire' property
27860 * g_permission_get_can_release:
27861 * @permission: a #GPermission instance
27863 * Gets the value of the 'can-release' property. This property is %TRUE
27864 * if it is generally possible to release the permission by calling
27865 * g_permission_release().
27867 * Returns: the value of the 'can-release' property
27873 * g_permission_impl_update:
27874 * @permission: a #GPermission instance
27875 * @allowed: the new value for the 'allowed' property
27876 * @can_acquire: the new value for the 'can-acquire' property
27877 * @can_release: the new value for the 'can-release' property
27879 * This function is called by the #GPermission implementation to update
27880 * the properties of the permission. You should never call this
27881 * function except from a #GPermission implementation.
27883 * GObject notify signals are generated, as appropriate.
27890 * g_permission_release:
27891 * @permission: a #GPermission instance
27892 * @cancellable: (allow-none): a #GCancellable, or %NULL
27893 * @error: a pointer to a %NULL #GError, or %NULL
27895 * Attempts to release the permission represented by @permission.
27897 * The precise method by which this happens depends on the permission
27898 * and the underlying authentication mechanism. In most cases the
27899 * permission will be dropped immediately without further action.
27901 * You should check with g_permission_get_can_release() before calling
27904 * If the permission is released then %TRUE is returned. Otherwise,
27905 * %FALSE is returned and @error is set appropriately.
27907 * This call is blocking, likely for a very long time (in the case that
27908 * user interaction is required). See g_permission_release_async() for
27909 * the non-blocking version.
27911 * Returns: %TRUE if the permission was successfully released
27917 * g_permission_release_async:
27918 * @permission: a #GPermission instance
27919 * @cancellable: (allow-none): a #GCancellable, or %NULL
27920 * @callback: the #GAsyncReadyCallback to call when done
27921 * @user_data: the user data to pass to @callback
27923 * Attempts to release the permission represented by @permission.
27925 * This is the first half of the asynchronous version of
27926 * g_permission_release().
27933 * g_permission_release_finish:
27934 * @permission: a #GPermission instance
27935 * @result: the #GAsyncResult given to the #GAsyncReadyCallback
27936 * @error: a pointer to a %NULL #GError, or %NULL
27938 * Collects the result of attempting to release the permission
27939 * represented by @permission.
27941 * This is the second half of the asynchronous version of
27942 * g_permission_release().
27944 * Returns: %TRUE if the permission was successfully released
27950 * g_poll_file_monitor_new:
27953 * Polls @file for changes.
27955 * Returns: a new #GFileMonitor for the given #GFile.
27960 * g_pollable_input_stream_can_poll:
27961 * @stream: a #GPollableInputStream.
27963 * Checks if @stream is actually pollable. Some classes may implement
27964 * #GPollableInputStream but have only certain instances of that class
27965 * be pollable. If this method returns %FALSE, then the behavior of
27966 * other #GPollableInputStream methods is undefined.
27968 * For any given stream, the value returned by this method is constant;
27969 * a stream cannot switch from pollable to non-pollable or vice versa.
27971 * Returns: %TRUE if @stream is pollable, %FALSE if not.
27977 * g_pollable_input_stream_create_source:
27978 * @stream: a #GPollableInputStream.
27979 * @cancellable: (allow-none): a #GCancellable, or %NULL
27981 * Creates a #GSource that triggers when @stream can be read, or
27982 * @cancellable is triggered or an error occurs. The callback on the
27983 * source is of the #GPollableSourceFunc type.
27985 * As with g_pollable_input_stream_is_readable(), it is possible that
27986 * the stream may not actually be readable even after the source
27987 * triggers, so you should use g_pollable_input_stream_read_nonblocking()
27988 * rather than g_input_stream_read() from the callback.
27990 * Returns: (transfer full): a new #GSource
27996 * g_pollable_input_stream_is_readable:
27997 * @stream: a #GPollableInputStream.
27999 * Checks if @stream can be read.
28001 * Note that some stream types may not be able to implement this 100%
28002 * reliably, and it is possible that a call to g_input_stream_read()
28003 * after this returns %TRUE would still block. To guarantee
28004 * non-blocking behavior, you should always use
28005 * g_pollable_input_stream_read_nonblocking(), which will return a
28006 * %G_IO_ERROR_WOULD_BLOCK error rather than blocking.
28008 * Returns: %TRUE if @stream is readable, %FALSE if not. If an error
28009 * has occurred on @stream, this will result in
28010 * g_pollable_input_stream_is_readable() returning %TRUE, and the
28011 * next attempt to read will return the error.
28017 * g_pollable_input_stream_read_nonblocking: (virtual read_nonblocking)
28018 * @stream: a #GPollableInputStream
28019 * @buffer: (array length=count) (element-type guint8): a buffer to
28020 * read data into (which should be at least @count bytes long).
28021 * @count: the number of bytes you want to read
28022 * @cancellable: (allow-none): a #GCancellable, or %NULL
28023 * @error: #GError for error reporting, or %NULL to ignore.
28025 * Attempts to read up to @count bytes from @stream into @buffer, as
28026 * with g_input_stream_read(). If @stream is not currently readable,
28027 * this will immediately return %G_IO_ERROR_WOULD_BLOCK, and you can
28028 * use g_pollable_input_stream_create_source() to create a #GSource
28029 * that will be triggered when @stream is readable.
28031 * Note that since this method never blocks, you cannot actually
28032 * use @cancellable to cancel it. However, it will return an error
28033 * if @cancellable has already been cancelled when you call, which
28034 * may happen if you call this method after a source triggers due
28035 * to having been cancelled.
28037 * Returns: the number of bytes read, or -1 on error (including
28038 * %G_IO_ERROR_WOULD_BLOCK).
28043 * g_pollable_output_stream_can_poll:
28044 * @stream: a #GPollableOutputStream.
28046 * Checks if @stream is actually pollable. Some classes may implement
28047 * #GPollableOutputStream but have only certain instances of that
28048 * class be pollable. If this method returns %FALSE, then the behavior
28049 * of other #GPollableOutputStream methods is undefined.
28051 * For any given stream, the value returned by this method is constant;
28052 * a stream cannot switch from pollable to non-pollable or vice versa.
28054 * Returns: %TRUE if @stream is pollable, %FALSE if not.
28060 * g_pollable_output_stream_create_source:
28061 * @stream: a #GPollableOutputStream.
28062 * @cancellable: (allow-none): a #GCancellable, or %NULL
28064 * Creates a #GSource that triggers when @stream can be written, or
28065 * @cancellable is triggered or an error occurs. The callback on the
28066 * source is of the #GPollableSourceFunc type.
28068 * As with g_pollable_output_stream_is_writable(), it is possible that
28069 * the stream may not actually be writable even after the source
28070 * triggers, so you should use g_pollable_output_stream_write_nonblocking()
28071 * rather than g_output_stream_write() from the callback.
28073 * Returns: (transfer full): a new #GSource
28079 * g_pollable_output_stream_is_writable:
28080 * @stream: a #GPollableOutputStream.
28082 * Checks if @stream can be written.
28084 * Note that some stream types may not be able to implement this 100%
28085 * reliably, and it is possible that a call to g_output_stream_write()
28086 * after this returns %TRUE would still block. To guarantee
28087 * non-blocking behavior, you should always use
28088 * g_pollable_output_stream_write_nonblocking(), which will return a
28089 * %G_IO_ERROR_WOULD_BLOCK error rather than blocking.
28091 * Returns: %TRUE if @stream is writable, %FALSE if not. If an error
28092 * has occurred on @stream, this will result in
28093 * g_pollable_output_stream_is_writable() returning %TRUE, and the
28094 * next attempt to write will return the error.
28100 * g_pollable_output_stream_write_nonblocking: (virtual write_nonblocking)
28101 * @stream: a #GPollableOutputStream
28102 * @buffer: (array length=count) (element-type guint8): a buffer to write
28104 * @count: the number of bytes you want to write
28105 * @cancellable: (allow-none): a #GCancellable, or %NULL
28106 * @error: #GError for error reporting, or %NULL to ignore.
28108 * Attempts to write up to @count bytes from @buffer to @stream, as
28109 * with g_output_stream_write(). If @stream is not currently writable,
28110 * this will immediately return %G_IO_ERROR_WOULD_BLOCK, and you can
28111 * use g_pollable_output_stream_create_source() to create a #GSource
28112 * that will be triggered when @stream is writable.
28114 * Note that since this method never blocks, you cannot actually
28115 * use @cancellable to cancel it. However, it will return an error
28116 * if @cancellable has already been cancelled when you call, which
28117 * may happen if you call this method after a source triggers due
28118 * to having been cancelled.
28120 * Returns: the number of bytes written, or -1 on error (including
28121 * %G_IO_ERROR_WOULD_BLOCK).
28126 * g_pollable_source_new:
28127 * @pollable_stream: the stream associated with the new source
28129 * Utility method for #GPollableInputStream and #GPollableOutputStream
28130 * implementations. Creates a new #GSource that expects a callback of
28131 * type #GPollableSourceFunc. The new source does not actually do
28132 * anything on its own; use g_source_add_child_source() to add other
28133 * sources to it to cause it to trigger.
28135 * Returns: (transfer full): the new #GSource.
28141 * g_pollable_source_new_full:
28142 * @pollable_stream: (type GObject): the stream associated with the
28144 * @child_source: (allow-none): optional child source to attach
28145 * @cancellable: (allow-none): optional #GCancellable to attach
28147 * Utility method for #GPollableInputStream and #GPollableOutputStream
28148 * implementations. Creates a new #GSource, as with
28149 * g_pollable_source_new(), but also attaching @child_source (with a
28150 * dummy callback), and @cancellable, if they are non-%NULL.
28152 * Returns: (transfer full): the new #GSource.
28158 * g_pollable_stream_read:
28159 * @stream: a #GInputStream
28160 * @buffer: (array length=count) (element-type guint8): a buffer to
28162 * @count: the number of bytes to read
28163 * @blocking: whether to do blocking I/O
28164 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
28165 * @error: location to store the error occurring, or %NULL to ignore
28167 * Tries to read from @stream, as with g_input_stream_read() (if
28168 * @blocking is %TRUE) or g_pollable_input_stream_read_nonblocking()
28169 * (if @blocking is %FALSE). This can be used to more easily share
28170 * code between blocking and non-blocking implementations of a method.
28172 * If @blocking is %FALSE, then @stream must be a
28173 * #GPollableInputStream for which g_pollable_input_stream_can_poll()
28174 * returns %TRUE, or else the behavior is undefined. If @blocking is
28175 * %TRUE, then @stream does not need to be a #GPollableInputStream.
28177 * Returns: the number of bytes read, or -1 on error.
28183 * g_pollable_stream_write:
28184 * @stream: a #GOutputStream.
28185 * @buffer: (array length=count) (element-type guint8): the buffer
28186 * containing the data to write.
28187 * @count: the number of bytes to write
28188 * @blocking: whether to do blocking I/O
28189 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
28190 * @error: location to store the error occurring, or %NULL to ignore
28192 * Tries to write to @stream, as with g_output_stream_write() (if
28193 * @blocking is %TRUE) or g_pollable_output_stream_write_nonblocking()
28194 * (if @blocking is %FALSE). This can be used to more easily share
28195 * code between blocking and non-blocking implementations of a method.
28197 * If @blocking is %FALSE, then @stream must be a
28198 * #GPollableOutputStream for which
28199 * g_pollable_output_stream_can_poll() returns %TRUE or else the
28200 * behavior is undefined. If @blocking is %TRUE, then @stream does not
28201 * need to be a #GPollableOutputStream.
28203 * Returns: the number of bytes written, or -1 on error.
28209 * g_pollable_stream_write_all:
28210 * @stream: a #GOutputStream.
28211 * @buffer: (array length=count) (element-type guint8): the buffer
28212 * containing the data to write.
28213 * @count: the number of bytes to write
28214 * @blocking: whether to do blocking I/O
28215 * @bytes_written: (out): location to store the number of bytes that was
28216 * written to the stream
28217 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
28218 * @error: location to store the error occurring, or %NULL to ignore
28220 * Tries to write @count bytes to @stream, as with
28221 * g_output_stream_write_all(), but using g_pollable_stream_write()
28222 * rather than g_output_stream_write().
28224 * On a successful write of @count bytes, %TRUE is returned, and
28225 * @bytes_written is set to @count.
28227 * If there is an error during the operation (including
28228 * %G_IO_ERROR_WOULD_BLOCK in the non-blocking case), %FALSE is
28229 * returned and @error is set to indicate the error status,
28230 * @bytes_written is updated to contain the number of bytes written
28231 * into the stream before the error occurred.
28233 * As with g_pollable_stream_write(), if @blocking is %FALSE, then
28234 * @stream must be a #GPollableOutputStream for which
28235 * g_pollable_output_stream_can_poll() returns %TRUE or else the
28236 * behavior is undefined. If @blocking is %TRUE, then @stream does not
28237 * need to be a #GPollableOutputStream.
28239 * Returns: %TRUE on success, %FALSE if there was an error
28245 * g_property_action_new:
28246 * @name: the name of the action to create
28247 * @object: the object that has the property to wrap
28248 * @property_name: the name of the property
28250 * Creates a #GAction corresponding to the value of property
28251 * @property_name on @object.
28253 * The property must be existent and readable and writable (and not
28256 * This function takes a reference on @object and doesn't release it
28257 * until the action is destroyed.
28259 * Returns: a new #GPropertyAction
28265 * g_proxy_address_get_destination_hostname:
28266 * @proxy: a #GProxyAddress
28268 * Gets @proxy's destination hostname; that is, the name of the host
28269 * that will be connected to via the proxy, not the name of the proxy
28272 * Returns: the @proxy's destination hostname
28278 * g_proxy_address_get_destination_port:
28279 * @proxy: a #GProxyAddress
28281 * Gets @proxy's destination port; that is, the port on the
28282 * destination host that will be connected to via the proxy, not the
28283 * port number of the proxy itself.
28285 * Returns: the @proxy's destination port
28291 * g_proxy_address_get_destination_protocol:
28292 * @proxy: a #GProxyAddress
28294 * Gets the protocol that is being spoken to the destination
28295 * server; eg, "http" or "ftp".
28297 * Returns: the @proxy's destination protocol
28303 * g_proxy_address_get_password:
28304 * @proxy: a #GProxyAddress
28306 * Gets @proxy's password.
28308 * Returns: the @proxy's password
28314 * g_proxy_address_get_protocol:
28315 * @proxy: a #GProxyAddress
28317 * Gets @proxy's protocol. eg, "socks" or "http"
28319 * Returns: the @proxy's protocol
28325 * g_proxy_address_get_uri:
28326 * @proxy: a #GProxyAddress
28328 * Gets the proxy URI that @proxy was constructed from.
28330 * Returns: the @proxy's URI, or %NULL if unknown
28336 * g_proxy_address_get_username:
28337 * @proxy: a #GProxyAddress
28339 * Gets @proxy's username.
28341 * Returns: the @proxy's username
28347 * g_proxy_address_new:
28348 * @inetaddr: The proxy server #GInetAddress.
28349 * @port: The proxy server port.
28350 * @protocol: The proxy protocol to support, in lower case (e.g. socks, http).
28351 * @dest_hostname: The destination hostname the proxy should tunnel to.
28352 * @dest_port: The destination port to tunnel to.
28353 * @username: (allow-none): The username to authenticate to the proxy server
28355 * @password: (allow-none): The password to authenticate to the proxy server
28358 * Creates a new #GProxyAddress for @inetaddr with @protocol that should
28359 * tunnel through @dest_hostname and @dest_port.
28361 * (Note that this method doesn't set the #GProxyAddress:uri or
28362 * #GProxyAddress:destination-protocol fields; use g_object_new()
28363 * directly if you want to set those.)
28365 * Returns: a new #GProxyAddress
28372 * @proxy: a #GProxy
28373 * @connection: a #GIOStream
28374 * @proxy_address: a #GProxyAddress
28375 * @cancellable: (allow-none): a #GCancellable
28376 * @error: return #GError
28378 * Given @connection to communicate with a proxy (eg, a
28379 * #GSocketConnection that is connected to the proxy server), this
28380 * does the necessary handshake to connect to @proxy_address, and if
28381 * required, wraps the #GIOStream to handle proxy payload.
28383 * Returns: (transfer full): a #GIOStream that will replace @connection. This might
28384 * be the same as @connection, in which case a reference
28391 * g_proxy_connect_async:
28392 * @proxy: a #GProxy
28393 * @connection: a #GIOStream
28394 * @proxy_address: a #GProxyAddress
28395 * @cancellable: (allow-none): a #GCancellable
28396 * @callback: (scope async): a #GAsyncReadyCallback
28397 * @user_data: (closure): callback data
28399 * Asynchronous version of g_proxy_connect().
28406 * g_proxy_connect_finish:
28407 * @proxy: a #GProxy
28408 * @result: a #GAsyncResult
28409 * @error: return #GError
28411 * See g_proxy_connect().
28413 * Returns: (transfer full): a #GIOStream.
28419 * g_proxy_get_default_for_protocol:
28420 * @protocol: the proxy protocol name (e.g. http, socks, etc)
28422 * Lookup "gio-proxy" extension point for a proxy implementation that supports
28423 * specified protocol.
28425 * Returns: (transfer full): return a #GProxy or NULL if protocol
28426 * is not supported.
28432 * g_proxy_resolver_get_default:
28434 * Gets the default #GProxyResolver for the system.
28436 * Returns: (transfer none): the default #GProxyResolver.
28442 * g_proxy_resolver_is_supported:
28443 * @resolver: a #GProxyResolver
28445 * Checks if @resolver can be used on this system. (This is used
28446 * internally; g_proxy_resolver_get_default() will only return a proxy
28447 * resolver that returns %TRUE for this method.)
28449 * Returns: %TRUE if @resolver is supported.
28455 * g_proxy_resolver_lookup:
28456 * @resolver: a #GProxyResolver
28457 * @uri: a URI representing the destination to connect to
28458 * @cancellable: (allow-none): a #GCancellable, or %NULL
28459 * @error: return location for a #GError, or %NULL
28461 * Looks into the system proxy configuration to determine what proxy,
28462 * if any, to use to connect to @uri. The returned proxy URIs are of
28463 * the form `<protocol>://[user[:password]@]host:port` or
28464 * `direct://`, where <protocol> could be http, rtsp, socks
28465 * or other proxying protocol.
28467 * If you don't know what network protocol is being used on the
28468 * socket, you should use `none` as the URI protocol.
28469 * In this case, the resolver might still return a generic proxy type
28470 * (such as SOCKS), but would not return protocol-specific proxy types
28473 * `direct://` is used when no proxy is needed.
28474 * Direct connection should not be attempted unless it is part of the
28475 * returned array of proxies.
28477 * Returns: (transfer full) (array zero-terminated=1): A
28478 * NULL-terminated array of proxy URIs. Must be freed
28479 * with g_strfreev().
28485 * g_proxy_resolver_lookup_async:
28486 * @resolver: a #GProxyResolver
28487 * @uri: a URI representing the destination to connect to
28488 * @cancellable: (allow-none): a #GCancellable, or %NULL
28489 * @callback: (scope async): callback to call after resolution completes
28490 * @user_data: (closure): data for @callback
28492 * Asynchronous lookup of proxy. See g_proxy_resolver_lookup() for more
28500 * g_proxy_resolver_lookup_finish:
28501 * @resolver: a #GProxyResolver
28502 * @result: the result passed to your #GAsyncReadyCallback
28503 * @error: return location for a #GError, or %NULL
28505 * Call this function to obtain the array of proxy URIs when
28506 * g_proxy_resolver_lookup_async() is complete. See
28507 * g_proxy_resolver_lookup() for more details.
28509 * Returns: (transfer full) (array zero-terminated=1): A
28510 * NULL-terminated array of proxy URIs. Must be freed
28511 * with g_strfreev().
28517 * g_proxy_supports_hostname:
28518 * @proxy: a #GProxy
28520 * Some proxy protocols expect to be passed a hostname, which they
28521 * will resolve to an IP address themselves. Others, like SOCKS4, do
28522 * not allow this. This function will return %FALSE if @proxy is
28523 * implementing such a protocol. When %FALSE is returned, the caller
28524 * should resolve the destination hostname first, and then pass a
28525 * #GProxyAddress containing the stringified IP address to
28526 * g_proxy_connect() or g_proxy_connect_async().
28528 * Returns: %TRUE if hostname resolution is supported.
28534 * g_remote_action_group_activate_action_full:
28535 * @remote: a #GDBusActionGroup
28536 * @action_name: the name of the action to activate
28537 * @parameter: (allow-none): the optional parameter to the activation
28538 * @platform_data: the platform data to send
28540 * Activates the remote action.
28542 * This is the same as g_action_group_activate_action() except that it
28543 * allows for provision of "platform data" to be sent along with the
28544 * activation request. This typically contains details such as the user
28545 * interaction timestamp or startup notification information.
28547 * @platform_data must be non-%NULL and must have the type
28548 * %G_VARIANT_TYPE_VARDICT. If it is floating, it will be consumed.
28555 * g_remote_action_group_change_action_state_full:
28556 * @remote: a #GRemoteActionGroup
28557 * @action_name: the name of the action to change the state of
28558 * @value: the new requested value for the state
28559 * @platform_data: the platform data to send
28561 * Changes the state of a remote action.
28563 * This is the same as g_action_group_change_action_state() except that
28564 * it allows for provision of "platform data" to be sent along with the
28565 * state change request. This typically contains details such as the
28566 * user interaction timestamp or startup notification information.
28568 * @platform_data must be non-%NULL and must have the type
28569 * %G_VARIANT_TYPE_VARDICT. If it is floating, it will be consumed.
28576 * g_resolver_error_quark:
28578 * Gets the #GResolver Error Quark.
28580 * Returns: a #GQuark.
28586 * g_resolver_free_addresses: (skip)
28587 * @addresses: a #GList of #GInetAddress
28589 * Frees @addresses (which should be the return value from
28590 * g_resolver_lookup_by_name() or g_resolver_lookup_by_name_finish()).
28591 * (This is a convenience method; you can also simply free the results
28599 * g_resolver_free_targets: (skip)
28600 * @targets: a #GList of #GSrvTarget
28602 * Frees @targets (which should be the return value from
28603 * g_resolver_lookup_service() or g_resolver_lookup_service_finish()).
28604 * (This is a convenience method; you can also simply free the
28605 * results by hand.)
28612 * g_resolver_get_default:
28614 * Gets the default #GResolver. You should unref it when you are done
28615 * with it. #GResolver may use its reference count as a hint about how
28616 * many threads it should allocate for concurrent DNS resolutions.
28618 * Returns: (transfer full): the default #GResolver.
28624 * g_resolver_lookup_by_address:
28625 * @resolver: a #GResolver
28626 * @address: the address to reverse-resolve
28627 * @cancellable: (allow-none): a #GCancellable, or %NULL
28628 * @error: return location for a #GError, or %NULL
28630 * Synchronously reverse-resolves @address to determine its
28631 * associated hostname.
28633 * If the DNS resolution fails, @error (if non-%NULL) will be set to
28634 * a value from #GResolverError.
28636 * If @cancellable is non-%NULL, it can be used to cancel the
28637 * operation, in which case @error (if non-%NULL) will be set to
28638 * %G_IO_ERROR_CANCELLED.
28640 * Returns: a hostname (either ASCII-only, or in ASCII-encoded
28641 * form), or %NULL on error.
28647 * g_resolver_lookup_by_address_async:
28648 * @resolver: a #GResolver
28649 * @address: the address to reverse-resolve
28650 * @cancellable: (allow-none): a #GCancellable, or %NULL
28651 * @callback: (scope async): callback to call after resolution completes
28652 * @user_data: (closure): data for @callback
28654 * Begins asynchronously reverse-resolving @address to determine its
28655 * associated hostname, and eventually calls @callback, which must
28656 * call g_resolver_lookup_by_address_finish() to get the final result.
28663 * g_resolver_lookup_by_address_finish:
28664 * @resolver: a #GResolver
28665 * @result: the result passed to your #GAsyncReadyCallback
28666 * @error: return location for a #GError, or %NULL
28668 * Retrieves the result of a previous call to
28669 * g_resolver_lookup_by_address_async().
28671 * If the DNS resolution failed, @error (if non-%NULL) will be set to
28672 * a value from #GResolverError. If the operation was cancelled,
28673 * @error will be set to %G_IO_ERROR_CANCELLED.
28675 * Returns: a hostname (either ASCII-only, or in ASCII-encoded
28676 * form), or %NULL on error.
28682 * g_resolver_lookup_by_name:
28683 * @resolver: a #GResolver
28684 * @hostname: the hostname to look up
28685 * @cancellable: (allow-none): a #GCancellable, or %NULL
28686 * @error: return location for a #GError, or %NULL
28688 * Synchronously resolves @hostname to determine its associated IP
28689 * address(es). @hostname may be an ASCII-only or UTF-8 hostname, or
28690 * the textual form of an IP address (in which case this just becomes
28691 * a wrapper around g_inet_address_new_from_string()).
28693 * On success, g_resolver_lookup_by_name() will return a non-empty #GList of
28694 * #GInetAddress, sorted in order of preference and guaranteed to not
28695 * contain duplicates. That is, if using the result to connect to
28696 * @hostname, you should attempt to connect to the first address
28697 * first, then the second if the first fails, etc. If you are using
28698 * the result to listen on a socket, it is appropriate to add each
28699 * result using e.g. g_socket_listener_add_address().
28701 * If the DNS resolution fails, @error (if non-%NULL) will be set to a
28702 * value from #GResolverError and %NULL will be returned.
28704 * If @cancellable is non-%NULL, it can be used to cancel the
28705 * operation, in which case @error (if non-%NULL) will be set to
28706 * %G_IO_ERROR_CANCELLED.
28708 * If you are planning to connect to a socket on the resolved IP
28709 * address, it may be easier to create a #GNetworkAddress and use its
28710 * #GSocketConnectable interface.
28712 * Returns: (element-type GInetAddress) (transfer full): a non-empty #GList
28713 * of #GInetAddress, or %NULL on error. You
28714 * must unref each of the addresses and free the list when you are
28715 * done with it. (You can use g_resolver_free_addresses() to do this.)
28721 * g_resolver_lookup_by_name_async:
28722 * @resolver: a #GResolver
28723 * @hostname: the hostname to look up the address of
28724 * @cancellable: (allow-none): a #GCancellable, or %NULL
28725 * @callback: (scope async): callback to call after resolution completes
28726 * @user_data: (closure): data for @callback
28728 * Begins asynchronously resolving @hostname to determine its
28729 * associated IP address(es), and eventually calls @callback, which
28730 * must call g_resolver_lookup_by_name_finish() to get the result.
28731 * See g_resolver_lookup_by_name() for more details.
28738 * g_resolver_lookup_by_name_finish:
28739 * @resolver: a #GResolver
28740 * @result: the result passed to your #GAsyncReadyCallback
28741 * @error: return location for a #GError, or %NULL
28743 * Retrieves the result of a call to
28744 * g_resolver_lookup_by_name_async().
28746 * If the DNS resolution failed, @error (if non-%NULL) will be set to
28747 * a value from #GResolverError. If the operation was cancelled,
28748 * @error will be set to %G_IO_ERROR_CANCELLED.
28750 * Returns: (element-type GInetAddress) (transfer full): a #GList
28751 * of #GInetAddress, or %NULL on error. See g_resolver_lookup_by_name()
28752 * for more details.
28758 * g_resolver_lookup_records:
28759 * @resolver: a #GResolver
28760 * @rrname: the DNS name to lookup the record for
28761 * @record_type: the type of DNS record to lookup
28762 * @cancellable: (allow-none): a #GCancellable, or %NULL
28763 * @error: return location for a #GError, or %NULL
28765 * Synchronously performs a DNS record lookup for the given @rrname and returns
28766 * a list of records as #GVariant tuples. See #GResolverRecordType for
28767 * information on what the records contain for each @record_type.
28769 * If the DNS resolution fails, @error (if non-%NULL) will be set to
28770 * a value from #GResolverError and %NULL will be returned.
28772 * If @cancellable is non-%NULL, it can be used to cancel the
28773 * operation, in which case @error (if non-%NULL) will be set to
28774 * %G_IO_ERROR_CANCELLED.
28776 * Returns: (element-type GVariant) (transfer full): a non-empty #GList of
28777 * #GVariant, or %NULL on error. You must free each of the records and the list
28778 * when you are done with it. (You can use g_list_free_full() with
28779 * g_variant_unref() to do this.)
28785 * g_resolver_lookup_records_async:
28786 * @resolver: a #GResolver
28787 * @rrname: the DNS name to lookup the record for
28788 * @record_type: the type of DNS record to lookup
28789 * @cancellable: (allow-none): a #GCancellable, or %NULL
28790 * @callback: (scope async): callback to call after resolution completes
28791 * @user_data: (closure): data for @callback
28793 * Begins asynchronously performing a DNS lookup for the given
28794 * @rrname, and eventually calls @callback, which must call
28795 * g_resolver_lookup_records_finish() to get the final result. See
28796 * g_resolver_lookup_records() for more details.
28803 * g_resolver_lookup_records_finish:
28804 * @resolver: a #GResolver
28805 * @result: the result passed to your #GAsyncReadyCallback
28806 * @error: return location for a #GError, or %NULL
28808 * Retrieves the result of a previous call to
28809 * g_resolver_lookup_records_async(). Returns a non-empty list of records as
28810 * #GVariant tuples. See #GResolverRecordType for information on what the
28813 * If the DNS resolution failed, @error (if non-%NULL) will be set to
28814 * a value from #GResolverError. If the operation was cancelled,
28815 * @error will be set to %G_IO_ERROR_CANCELLED.
28817 * Returns: (element-type GVariant) (transfer full): a non-empty #GList of
28818 * #GVariant, or %NULL on error. You must free each of the records and the list
28819 * when you are done with it. (You can use g_list_free_full() with
28820 * g_variant_unref() to do this.)
28826 * g_resolver_lookup_service:
28827 * @resolver: a #GResolver
28828 * @service: the service type to look up (eg, "ldap")
28829 * @protocol: the networking protocol to use for @service (eg, "tcp")
28830 * @domain: the DNS domain to look up the service in
28831 * @cancellable: (allow-none): a #GCancellable, or %NULL
28832 * @error: return location for a #GError, or %NULL
28834 * Synchronously performs a DNS SRV lookup for the given @service and
28835 * @protocol in the given @domain and returns an array of #GSrvTarget.
28836 * @domain may be an ASCII-only or UTF-8 hostname. Note also that the
28837 * @service and @protocol arguments do not include the leading underscore
28838 * that appears in the actual DNS entry.
28840 * On success, g_resolver_lookup_service() will return a non-empty #GList of
28841 * #GSrvTarget, sorted in order of preference. (That is, you should
28842 * attempt to connect to the first target first, then the second if
28843 * the first fails, etc.)
28845 * If the DNS resolution fails, @error (if non-%NULL) will be set to
28846 * a value from #GResolverError and %NULL will be returned.
28848 * If @cancellable is non-%NULL, it can be used to cancel the
28849 * operation, in which case @error (if non-%NULL) will be set to
28850 * %G_IO_ERROR_CANCELLED.
28852 * If you are planning to connect to the service, it is usually easier
28853 * to create a #GNetworkService and use its #GSocketConnectable
28856 * Returns: (element-type GSrvTarget) (transfer full): a non-empty #GList of
28857 * #GSrvTarget, or %NULL on error. You must free each of the targets and the
28858 * list when you are done with it. (You can use g_resolver_free_targets() to do
28865 * g_resolver_lookup_service_async:
28866 * @resolver: a #GResolver
28867 * @service: the service type to look up (eg, "ldap")
28868 * @protocol: the networking protocol to use for @service (eg, "tcp")
28869 * @domain: the DNS domain to look up the service in
28870 * @cancellable: (allow-none): a #GCancellable, or %NULL
28871 * @callback: (scope async): callback to call after resolution completes
28872 * @user_data: (closure): data for @callback
28874 * Begins asynchronously performing a DNS SRV lookup for the given
28875 * @service and @protocol in the given @domain, and eventually calls
28876 * @callback, which must call g_resolver_lookup_service_finish() to
28877 * get the final result. See g_resolver_lookup_service() for more
28885 * g_resolver_lookup_service_finish:
28886 * @resolver: a #GResolver
28887 * @result: the result passed to your #GAsyncReadyCallback
28888 * @error: return location for a #GError, or %NULL
28890 * Retrieves the result of a previous call to
28891 * g_resolver_lookup_service_async().
28893 * If the DNS resolution failed, @error (if non-%NULL) will be set to
28894 * a value from #GResolverError. If the operation was cancelled,
28895 * @error will be set to %G_IO_ERROR_CANCELLED.
28897 * Returns: (element-type GSrvTarget) (transfer full): a non-empty #GList of
28898 * #GSrvTarget, or %NULL on error. See g_resolver_lookup_service() for more
28905 * g_resolver_set_default:
28906 * @resolver: the new default #GResolver
28908 * Sets @resolver to be the application's default resolver (reffing
28909 * @resolver, and unreffing the previous default resolver, if any).
28910 * Future calls to g_resolver_get_default() will return this resolver.
28912 * This can be used if an application wants to perform any sort of DNS
28913 * caching or "pinning"; it can implement its own #GResolver that
28914 * calls the original default resolver for DNS operations, and
28915 * implements its own cache policies on top of that, and then set
28916 * itself as the default resolver for all later code to use.
28923 * g_resource_enumerate_children:
28924 * @resource: A #GResource
28925 * @path: A pathname inside the resource
28926 * @lookup_flags: A #GResourceLookupFlags
28927 * @error: return location for a #GError, or %NULL
28929 * Returns all the names of children at the specified @path in the resource.
28930 * The return result is a %NULL terminated list of strings which should
28931 * be released with g_strfreev().
28933 * @lookup_flags controls the behaviour of the lookup.
28935 * Returns: (array zero-terminated=1) (transfer full): an array of constant strings
28941 * g_resource_error_quark:
28943 * Gets the #GResource Error Quark.
28945 * Returns: a #GQuark
28951 * g_resource_get_info:
28952 * @resource: A #GResource
28953 * @path: A pathname inside the resource
28954 * @lookup_flags: A #GResourceLookupFlags
28955 * @size: (out) (allow-none): a location to place the length of the contents of the file,
28956 * or %NULL if the length is not needed
28957 * @flags: (out) (allow-none): a location to place the flags about the file,
28958 * or %NULL if the length is not needed
28959 * @error: return location for a #GError, or %NULL
28961 * Looks for a file at the specified @path in the resource and
28962 * if found returns information about it.
28964 * @lookup_flags controls the behaviour of the lookup.
28966 * Returns: %TRUE if the file was found. %FALSE if there were errors
28973 * @filename: (type filename): the path of a filename to load, in the GLib filename encoding
28974 * @error: return location for a #GError, or %NULL
28976 * Loads a binary resource bundle and creates a #GResource representation of it, allowing
28977 * you to query it for data.
28979 * If you want to use this resource in the global resource namespace you need
28980 * to register it with g_resources_register().
28982 * Returns: (transfer full): a new #GResource, or %NULL on error
28988 * g_resource_lookup_data:
28989 * @resource: A #GResource
28990 * @path: A pathname inside the resource
28991 * @lookup_flags: A #GResourceLookupFlags
28992 * @error: return location for a #GError, or %NULL
28994 * Looks for a file at the specified @path in the resource and
28995 * returns a #GBytes that lets you directly access the data in
28998 * The data is always followed by a zero byte, so you
28999 * can safely use the data as a C string. However, that byte
29000 * is not included in the size of the GBytes.
29002 * For uncompressed resource files this is a pointer directly into
29003 * the resource bundle, which is typically in some readonly data section
29004 * in the program binary. For compressed files we allocate memory on
29005 * the heap and automatically uncompress the data.
29007 * @lookup_flags controls the behaviour of the lookup.
29009 * Returns: (transfer full): #GBytes or %NULL on error.
29010 * Free the returned object with g_bytes_unref()
29016 * g_resource_new_from_data:
29018 * @error: return location for a #GError, or %NULL
29020 * Creates a GResource from a reference to the binary resource bundle.
29021 * This will keep a reference to @data while the resource lives, so
29022 * the data should not be modified or freed.
29024 * If you want to use this resource in the global resource namespace you need
29025 * to register it with g_resources_register().
29027 * Returns: (transfer full): a new #GResource, or %NULL on error
29033 * g_resource_open_stream:
29034 * @resource: A #GResource
29035 * @path: A pathname inside the resource
29036 * @lookup_flags: A #GResourceLookupFlags
29037 * @error: return location for a #GError, or %NULL
29039 * Looks for a file at the specified @path in the resource and
29040 * returns a #GInputStream that lets you read the data.
29042 * @lookup_flags controls the behaviour of the lookup.
29044 * Returns: (transfer full): #GInputStream or %NULL on error.
29045 * Free the returned object with g_object_unref()
29052 * @resource: A #GResource
29054 * Atomically increments the reference count of @array by one. This
29055 * function is MT-safe and may be called from any thread.
29057 * Returns: The passed in #GResource
29063 * g_resource_unref:
29064 * @resource: A #GResource
29066 * Atomically decrements the reference count of @resource by one. If the
29067 * reference count drops to 0, all memory allocated by the array is
29068 * released. This function is MT-safe and may be called from any
29076 * g_resources_enumerate_children:
29077 * @path: A pathname inside the resource
29078 * @lookup_flags: A #GResourceLookupFlags
29079 * @error: return location for a #GError, or %NULL
29081 * Returns all the names of children at the specified @path in the set of
29082 * globally registered resources.
29083 * The return result is a %NULL terminated list of strings which should
29084 * be released with g_strfreev().
29086 * @lookup_flags controls the behaviour of the lookup.
29088 * Returns: (array zero-terminated=1) (transfer full): an array of constant strings
29094 * g_resources_get_info:
29095 * @path: A pathname inside the resource
29096 * @lookup_flags: A #GResourceLookupFlags
29097 * @size: (out) (allow-none): a location to place the length of the contents of the file,
29098 * or %NULL if the length is not needed
29099 * @flags: (out) (allow-none): a location to place the flags about the file,
29100 * or %NULL if the length is not needed
29101 * @error: return location for a #GError, or %NULL
29103 * Looks for a file at the specified @path in the set of
29104 * globally registered resources and if found returns information about it.
29106 * @lookup_flags controls the behaviour of the lookup.
29108 * Returns: %TRUE if the file was found. %FALSE if there were errors
29114 * g_resources_lookup_data:
29115 * @path: A pathname inside the resource
29116 * @lookup_flags: A #GResourceLookupFlags
29117 * @error: return location for a #GError, or %NULL
29119 * Looks for a file at the specified @path in the set of
29120 * globally registered resources and returns a #GBytes that
29121 * lets you directly access the data in memory.
29123 * The data is always followed by a zero byte, so you
29124 * can safely use the data as a C string. However, that byte
29125 * is not included in the size of the GBytes.
29127 * For uncompressed resource files this is a pointer directly into
29128 * the resource bundle, which is typically in some readonly data section
29129 * in the program binary. For compressed files we allocate memory on
29130 * the heap and automatically uncompress the data.
29132 * @lookup_flags controls the behaviour of the lookup.
29134 * Returns: (transfer full): #GBytes or %NULL on error.
29135 * Free the returned object with g_bytes_unref()
29141 * g_resources_open_stream:
29142 * @path: A pathname inside the resource
29143 * @lookup_flags: A #GResourceLookupFlags
29144 * @error: return location for a #GError, or %NULL
29146 * Looks for a file at the specified @path in the set of
29147 * globally registered resources and returns a #GInputStream
29148 * that lets you read the data.
29150 * @lookup_flags controls the behaviour of the lookup.
29152 * Returns: (transfer full): #GInputStream or %NULL on error.
29153 * Free the returned object with g_object_unref()
29159 * g_resources_register:
29160 * @resource: A #GResource
29162 * Registers the resource with the process-global set of resources.
29163 * Once a resource is registered the files in it can be accessed
29164 * with the global resource lookup functions like g_resources_lookup_data().
29171 * g_resources_unregister:
29172 * @resource: A #GResource
29174 * Unregisters the resource from the process-global set of resources.
29181 * g_seekable_can_seek:
29182 * @seekable: a #GSeekable.
29184 * Tests if the stream supports the #GSeekableIface.
29186 * Returns: %TRUE if @seekable can be seeked. %FALSE otherwise.
29191 * g_seekable_can_truncate:
29192 * @seekable: a #GSeekable.
29194 * Tests if the stream can be truncated.
29196 * Returns: %TRUE if the stream can be truncated, %FALSE otherwise.
29202 * @seekable: a #GSeekable.
29203 * @offset: a #goffset.
29204 * @type: a #GSeekType.
29205 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
29206 * @error: a #GError location to store the error occurring, or %NULL to
29209 * Seeks in the stream by the given @offset, modified by @type.
29211 * Attempting to seek past the end of the stream will have different
29212 * results depending on if the stream is fixed-sized or resizable. If
29213 * the stream is resizable then seeking past the end and then writing
29214 * will result in zeros filling the empty space. Seeking past the end
29215 * of a resizable stream and reading will result in EOF. Seeking past
29216 * the end of a fixed-sized stream will fail.
29218 * Any operation that would result in a negative offset will fail.
29220 * If @cancellable is not %NULL, then the operation can be cancelled by
29221 * triggering the cancellable object from another thread. If the operation
29222 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
29224 * Returns: %TRUE if successful. If an error
29225 * has occurred, this function will return %FALSE and set @error
29226 * appropriately if present.
29232 * @seekable: a #GSeekable.
29234 * Tells the current position within the stream.
29236 * Returns: the offset from the beginning of the buffer.
29241 * g_seekable_truncate: (virtual truncate_fn)
29242 * @seekable: a #GSeekable.
29243 * @offset: a #goffset.
29244 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
29245 * @error: a #GError location to store the error occurring, or %NULL to
29248 * Truncates a stream with a given #offset.
29250 * If @cancellable is not %NULL, then the operation can be cancelled by
29251 * triggering the cancellable object from another thread. If the operation
29252 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
29253 * operation was partially finished when the operation was cancelled the
29254 * partial result will be returned, without an error.
29256 * Returns: %TRUE if successful. If an error
29257 * has occurred, this function will return %FALSE and set @error
29258 * appropriately if present.
29263 * g_settings_apply:
29264 * @settings: a #GSettings instance
29266 * Applies any changes that have been made to the settings. This
29267 * function does nothing unless @settings is in 'delay-apply' mode;
29268 * see g_settings_delay(). In the normal case settings are always
29269 * applied immediately.
29274 * g_settings_backend_changed:
29275 * @backend: a #GSettingsBackend implementation
29276 * @key: the name of the key
29277 * @origin_tag: the origin tag
29279 * Signals that a single key has possibly changed. Backend
29280 * implementations should call this if a key has possibly changed its
29283 * @key must be a valid key (ie starting with a slash, not containing
29284 * '//', and not ending with a slash).
29286 * The implementation must call this function during any call to
29287 * g_settings_backend_write(), before the call returns (except in the
29288 * case that no keys are actually changed and it cares to detect this
29289 * fact). It may not rely on the existence of a mainloop for
29290 * dispatching the signal later.
29292 * The implementation may call this function at any other time it likes
29293 * in response to other events (such as changes occurring outside of the
29294 * program). These calls may originate from a mainloop or may originate
29295 * in response to any other action (including from calls to
29296 * g_settings_backend_write()).
29298 * In the case that this call is in response to a call to
29299 * g_settings_backend_write() then @origin_tag must be set to the same
29300 * value that was passed to that call.
29307 * g_settings_backend_changed_tree:
29308 * @backend: a #GSettingsBackend implementation
29309 * @tree: a #GTree containing the changes
29310 * @origin_tag: the origin tag
29312 * This call is a convenience wrapper. It gets the list of changes from
29313 * @tree, computes the longest common prefix and calls
29314 * g_settings_backend_changed().
29321 * g_settings_backend_flatten_tree:
29322 * @tree: a #GTree containing the changes
29323 * @path: (out): the location to save the path
29324 * @keys: (out) (transfer container) (array zero-terminated=1): the
29325 * location to save the relative keys
29326 * @values: (out) (allow-none) (transfer container) (array zero-terminated=1):
29327 * the location to save the values, or %NULL
29329 * Calculate the longest common prefix of all keys in a tree and write
29330 * out an array of the key names relative to that prefix and,
29331 * optionally, the value to store at each of those keys.
29333 * You must free the value returned in @path, @keys and @values using
29334 * g_free(). You should not attempt to free or unref the contents of
29335 * @keys or @values.
29342 * g_settings_backend_get_default:
29344 * Returns the default #GSettingsBackend. It is possible to override
29345 * the default by setting the `GSETTINGS_BACKEND` environment variable
29346 * to the name of a settings backend.
29348 * The user gets a reference to the backend.
29350 * Returns: (transfer full): the default #GSettingsBackend
29356 * g_settings_backend_keys_changed:
29357 * @backend: a #GSettingsBackend implementation
29358 * @path: the path containing the changes
29359 * @items: (array zero-terminated=1): the %NULL-terminated list of changed keys
29360 * @origin_tag: the origin tag
29362 * Signals that a list of keys have possibly changed. Backend
29363 * implementations should call this if keys have possibly changed their
29366 * @path must be a valid path (ie starting and ending with a slash and
29367 * not containing '//'). Each string in @items must form a valid key
29368 * name when @path is prefixed to it (ie: each item must not start or
29369 * end with '/' and must not contain '//').
29371 * The meaning of this signal is that any of the key names resulting
29372 * from the contatenation of @path with each item in @items may have
29375 * The same rules for when notifications must occur apply as per
29376 * g_settings_backend_changed(). These two calls can be used
29377 * interchangeably if exactly one item has changed (although in that
29378 * case g_settings_backend_changed() is definitely preferred).
29380 * For efficiency reasons, the implementation should strive for @path to
29381 * be as long as possible (ie: the longest common prefix of all of the
29382 * keys that were changed) but this is not strictly required.
29389 * g_settings_backend_path_changed:
29390 * @backend: a #GSettingsBackend implementation
29391 * @path: the path containing the changes
29392 * @origin_tag: the origin tag
29394 * Signals that all keys below a given path may have possibly changed.
29395 * Backend implementations should call this if an entire path of keys
29396 * have possibly changed their values.
29398 * @path must be a valid path (ie starting and ending with a slash and
29399 * not containing '//').
29401 * The meaning of this signal is that any of the key which has a name
29402 * starting with @path may have changed.
29404 * The same rules for when notifications must occur apply as per
29405 * g_settings_backend_changed(). This call might be an appropriate
29406 * reasponse to a 'reset' call but implementations are also free to
29407 * explicitly list the keys that were affected by that call if they can
29410 * For efficiency reasons, the implementation should strive for @path to
29411 * be as long as possible (ie: the longest common prefix of all of the
29412 * keys that were changed) but this is not strictly required. As an
29413 * example, if this function is called with the path of "/" then every
29414 * single key in the application will be notified of a possible change.
29421 * g_settings_backend_path_writable_changed:
29422 * @backend: a #GSettingsBackend implementation
29423 * @path: the name of the path
29425 * Signals that the writability of all keys below a given path may have
29428 * Since GSettings performs no locking operations for itself, this call
29429 * will always be made in response to external events.
29436 * g_settings_backend_writable_changed:
29437 * @backend: a #GSettingsBackend implementation
29438 * @key: the name of the key
29440 * Signals that the writability of a single key has possibly changed.
29442 * Since GSettings performs no locking operations for itself, this call
29443 * will always be made in response to external events.
29451 * @settings: a #GSettings object
29452 * @key: the key to bind
29453 * @object: (type GObject.Object): a #GObject
29454 * @property: the name of the property to bind
29455 * @flags: flags for the binding
29457 * Create a binding between the @key in the @settings object
29458 * and the property @property of @object.
29460 * The binding uses the default GIO mapping functions to map
29461 * between the settings and property values. These functions
29462 * handle booleans, numeric types and string types in a
29463 * straightforward way. Use g_settings_bind_with_mapping() if
29464 * you need a custom mapping, or map between types that are not
29465 * supported by the default mapping functions.
29467 * Unless the @flags include %G_SETTINGS_BIND_NO_SENSITIVITY, this
29468 * function also establishes a binding between the writability of
29469 * @key and the "sensitive" property of @object (if @object has
29470 * a boolean property by that name). See g_settings_bind_writable()
29471 * for more details about writable bindings.
29473 * Note that the lifecycle of the binding is tied to the object,
29474 * and that you can have only one binding per object property.
29475 * If you bind the same property twice on the same object, the second
29476 * binding overrides the first one.
29483 * g_settings_bind_with_mapping: (skip)
29484 * @settings: a #GSettings object
29485 * @key: the key to bind
29486 * @object: (type GObject.Object): a #GObject
29487 * @property: the name of the property to bind
29488 * @flags: flags for the binding
29489 * @get_mapping: a function that gets called to convert values
29490 * from @settings to @object, or %NULL to use the default GIO mapping
29491 * @set_mapping: a function that gets called to convert values
29492 * from @object to @settings, or %NULL to use the default GIO mapping
29493 * @user_data: data that gets passed to @get_mapping and @set_mapping
29494 * @destroy: #GDestroyNotify function for @user_data
29496 * Create a binding between the @key in the @settings object
29497 * and the property @property of @object.
29499 * The binding uses the provided mapping functions to map between
29500 * settings and property values.
29502 * Note that the lifecycle of the binding is tied to the object,
29503 * and that you can have only one binding per object property.
29504 * If you bind the same property twice on the same object, the second
29505 * binding overrides the first one.
29512 * g_settings_bind_writable:
29513 * @settings: a #GSettings object
29514 * @key: the key to bind
29515 * @object: (type GObject.Object): a #GObject
29516 * @property: the name of a boolean property to bind
29517 * @inverted: whether to 'invert' the value
29519 * Create a binding between the writability of @key in the
29520 * @settings object and the property @property of @object.
29521 * The property must be boolean; "sensitive" or "visible"
29522 * properties of widgets are the most likely candidates.
29524 * Writable bindings are always uni-directional; changes of the
29525 * writability of the setting will be propagated to the object
29526 * property, not the other way.
29528 * When the @inverted argument is %TRUE, the binding inverts the
29529 * value as it passes from the setting to the object, i.e. @property
29530 * will be set to %TRUE if the key is not writable.
29532 * Note that the lifecycle of the binding is tied to the object,
29533 * and that you can have only one binding per object property.
29534 * If you bind the same property twice on the same object, the second
29535 * binding overrides the first one.
29542 * g_settings_create_action:
29543 * @settings: a #GSettings
29544 * @key: the name of a key in @settings
29546 * Creates a #GAction corresponding to a given #GSettings key.
29548 * The action has the same name as the key.
29550 * The value of the key becomes the state of the action and the action
29551 * is enabled when the key is writable. Changing the state of the
29552 * action results in the key being written to. Changes to the value or
29553 * writability of the key cause appropriate change notifications to be
29554 * emitted for the action.
29556 * For boolean-valued keys, action activations take no parameter and
29557 * result in the toggling of the value. For all other types,
29558 * activations take the new value for the key (which must have the
29561 * Returns: (transfer full): a new #GAction
29567 * g_settings_delay:
29568 * @settings: a #GSettings object
29570 * Changes the #GSettings object into 'delay-apply' mode. In this
29571 * mode, changes to @settings are not immediately propagated to the
29572 * backend, but kept locally until g_settings_apply() is called.
29580 * @settings: a #GSettings object
29581 * @key: the key to get the value for
29582 * @format: a #GVariant format string
29583 * @...: arguments as per @format
29585 * Gets the value that is stored at @key in @settings.
29587 * A convenience function that combines g_settings_get_value() with
29590 * It is a programmer error to give a @key that isn't contained in the
29591 * schema for @settings or for the #GVariantType of @format to mismatch
29592 * the type given in the schema.
29599 * g_settings_get_boolean:
29600 * @settings: a #GSettings object
29601 * @key: the key to get the value for
29603 * Gets the value that is stored at @key in @settings.
29605 * A convenience variant of g_settings_get() for booleans.
29607 * It is a programmer error to give a @key that isn't specified as
29608 * having a boolean type in the schema for @settings.
29610 * Returns: a boolean
29616 * g_settings_get_child:
29617 * @settings: a #GSettings object
29618 * @name: the name of the child schema
29620 * Creates a child settings object which has a base path of
29621 * `base-path/@name`, where `base-path` is the base path of
29624 * The schema for the child settings object must have been declared
29625 * in the schema of @settings using a <child> element.
29627 * Returns: (transfer full): a 'child' settings object
29633 * g_settings_get_default_value:
29634 * @settings: a #GSettings object
29635 * @key: the key to get the default value for
29637 * Gets the "default value" of a key.
29639 * This is the value that would be read if g_settings_reset() were to be
29640 * called on the key.
29642 * Note that this may be a different value than returned by
29643 * g_settings_schema_key_get_default_value() if the system administrator
29644 * has provided a default value.
29646 * Comparing the return values of g_settings_get_default_value() and
29647 * g_settings_get_value() is not sufficient for determining if a value
29648 * has been set because the user may have explicitly set the value to
29649 * something that happens to be equal to the default. The difference
29650 * here is that if the default changes in the future, the user's key
29651 * will still be set.
29653 * This function may be useful for adding an indication to a UI of what
29654 * the default value was before the user set it.
29656 * It is a programmer error to give a @key that isn't contained in the
29657 * schema for @settings.
29659 * Returns: (allow-none) (transfer full): the default value
29665 * g_settings_get_double:
29666 * @settings: a #GSettings object
29667 * @key: the key to get the value for
29669 * Gets the value that is stored at @key in @settings.
29671 * A convenience variant of g_settings_get() for doubles.
29673 * It is a programmer error to give a @key that isn't specified as
29674 * having a 'double' type in the schema for @settings.
29676 * Returns: a double
29682 * g_settings_get_enum:
29683 * @settings: a #GSettings object
29684 * @key: the key to get the value for
29686 * Gets the value that is stored in @settings for @key and converts it
29687 * to the enum value that it represents.
29689 * In order to use this function the type of the value must be a string
29690 * and it must be marked in the schema file as an enumerated type.
29692 * It is a programmer error to give a @key that isn't contained in the
29693 * schema for @settings or is not marked as an enumerated type.
29695 * If the value stored in the configuration database is not a valid
29696 * value for the enumerated type then this function will return the
29699 * Returns: the enum value
29705 * g_settings_get_flags:
29706 * @settings: a #GSettings object
29707 * @key: the key to get the value for
29709 * Gets the value that is stored in @settings for @key and converts it
29710 * to the flags value that it represents.
29712 * In order to use this function the type of the value must be an array
29713 * of strings and it must be marked in the schema file as an flags type.
29715 * It is a programmer error to give a @key that isn't contained in the
29716 * schema for @settings or is not marked as a flags type.
29718 * If the value stored in the configuration database is not a valid
29719 * value for the flags type then this function will return the default
29722 * Returns: the flags value
29728 * g_settings_get_has_unapplied:
29729 * @settings: a #GSettings object
29731 * Returns whether the #GSettings object has any unapplied
29732 * changes. This can only be the case if it is in 'delayed-apply' mode.
29734 * Returns: %TRUE if @settings has unapplied changes
29740 * g_settings_get_int:
29741 * @settings: a #GSettings object
29742 * @key: the key to get the value for
29744 * Gets the value that is stored at @key in @settings.
29746 * A convenience variant of g_settings_get() for 32-bit integers.
29748 * It is a programmer error to give a @key that isn't specified as
29749 * having a int32 type in the schema for @settings.
29751 * Returns: an integer
29757 * g_settings_get_mapped:
29758 * @settings: a #GSettings object
29759 * @key: the key to get the value for
29760 * @mapping: (scope call): the function to map the value in the
29761 * settings database to the value used by the application
29762 * @user_data: user data for @mapping
29764 * Gets the value that is stored at @key in @settings, subject to
29765 * application-level validation/mapping.
29767 * You should use this function when the application needs to perform
29768 * some processing on the value of the key (for example, parsing). The
29769 * @mapping function performs that processing. If the function
29770 * indicates that the processing was unsuccessful (due to a parse error,
29771 * for example) then the mapping is tried again with another value.
29773 * This allows a robust 'fall back to defaults' behaviour to be
29774 * implemented somewhat automatically.
29776 * The first value that is tried is the user's setting for the key. If
29777 * the mapping function fails to map this value, other values may be
29778 * tried in an unspecified order (system or site defaults, translated
29779 * schema default values, untranslated schema default values, etc).
29781 * If the mapping function fails for all possible values, one additional
29782 * attempt is made: the mapping function is called with a %NULL value.
29783 * If the mapping function still indicates failure at this point then
29784 * the application will be aborted.
29786 * The result parameter for the @mapping function is pointed to a
29787 * #gpointer which is initially set to %NULL. The same pointer is given
29788 * to each invocation of @mapping. The final value of that #gpointer is
29789 * what is returned by this function. %NULL is valid; it is returned
29790 * just as any other value would be.
29792 * Returns: (transfer full): the result, which may be %NULL
29797 * g_settings_get_range:
29798 * @settings: a #GSettings
29799 * @key: the key to query the range of
29801 * Queries the range of a key.
29804 * Deprecated: 2.40: Use g_settings_schema_key_get_range() instead.
29809 * g_settings_get_string:
29810 * @settings: a #GSettings object
29811 * @key: the key to get the value for
29813 * Gets the value that is stored at @key in @settings.
29815 * A convenience variant of g_settings_get() for strings.
29817 * It is a programmer error to give a @key that isn't specified as
29818 * having a string type in the schema for @settings.
29820 * Returns: a newly-allocated string
29826 * g_settings_get_strv:
29827 * @settings: a #GSettings object
29828 * @key: the key to get the value for
29830 * A convenience variant of g_settings_get() for string arrays.
29832 * It is a programmer error to give a @key that isn't specified as
29833 * having an array of strings type in the schema for @settings.
29835 * Returns: (array zero-terminated=1) (transfer full): a
29836 * newly-allocated, %NULL-terminated array of strings, the value that
29837 * is stored at @key in @settings.
29843 * g_settings_get_uint:
29844 * @settings: a #GSettings object
29845 * @key: the key to get the value for
29847 * Gets the value that is stored at @key in @settings.
29849 * A convenience variant of g_settings_get() for 32-bit unsigned
29852 * It is a programmer error to give a @key that isn't specified as
29853 * having a uint32 type in the schema for @settings.
29855 * Returns: an unsigned integer
29861 * g_settings_get_user_value:
29862 * @settings: a #GSettings object
29863 * @key: the key to get the user value for
29865 * Checks the "user value" of a key, if there is one.
29867 * The user value of a key is the last value that was set by the user.
29869 * After calling g_settings_reset() this function should always return
29870 * %NULL (assuming something is not wrong with the system
29873 * It is possible that g_settings_get_value() will return a different
29874 * value than this function. This can happen in the case that the user
29875 * set a value for a key that was subsequently locked down by the system
29876 * administrator -- this function will return the user's old value.
29878 * This function may be useful for adding a "reset" option to a UI or
29879 * for providing indication that a particular value has been changed.
29881 * It is a programmer error to give a @key that isn't contained in the
29882 * schema for @settings.
29884 * Returns: (allow-none) (transfer full): the user's value, if set
29890 * g_settings_get_value:
29891 * @settings: a #GSettings object
29892 * @key: the key to get the value for
29894 * Gets the value that is stored in @settings for @key.
29896 * It is a programmer error to give a @key that isn't contained in the
29897 * schema for @settings.
29899 * Returns: a new #GVariant
29905 * g_settings_is_writable:
29906 * @settings: a #GSettings object
29907 * @name: the name of a key
29909 * Finds out if a key can be written or not
29911 * Returns: %TRUE if the key @name is writable
29917 * g_settings_list_children:
29918 * @settings: a #GSettings object
29920 * Gets the list of children on @settings.
29922 * The list is exactly the list of strings for which it is not an error
29923 * to call g_settings_get_child().
29925 * For GSettings objects that are lists, this value can change at any
29926 * time and you should connect to the "children-changed" signal to watch
29927 * for those changes. Note that there is a race condition here: you may
29928 * request a child after listing it only for it to have been destroyed
29929 * in the meantime. For this reason, g_settings_get_child() may return
29930 * %NULL even for a child that was listed by this function.
29932 * For GSettings objects that are not lists, you should probably not be
29933 * calling this function from "normal" code (since you should already
29934 * know what children are in your schema). This function may still be
29935 * useful there for introspection reasons, however.
29937 * You should free the return value with g_strfreev() when you are done
29940 * Returns: (transfer full) (element-type utf8): a list of the children on @settings
29945 * g_settings_list_keys:
29946 * @settings: a #GSettings object
29948 * Introspects the list of keys on @settings.
29950 * You should probably not be calling this function from "normal" code
29951 * (since you should already know what keys are in your schema). This
29952 * function is intended for introspection reasons.
29954 * You should free the return value with g_strfreev() when you are done
29957 * Returns: (transfer full) (element-type utf8): a list of the keys on @settings
29962 * g_settings_list_relocatable_schemas:
29964 * Returns: (element-type utf8) (transfer none): a list of relocatable
29965 * #GSettings schemas that are available. The list must not be
29966 * modified or freed.
29968 * Deprecated: 2.40: Use g_settings_schema_source_list_schemas() instead
29973 * g_settings_list_schemas:
29975 * Returns: (element-type utf8) (transfer none): a list of #GSettings
29976 * schemas that are available. The list must not be modified or
29979 * Deprecated: 2.40: Use g_settings_schema_source_list_schemas() instead.
29980 * If you used g_settings_list_schemas() to check for the presence of
29981 * a particular schema, use g_settings_schema_source_lookup() instead
29982 * of your whole loop.
29988 * @schema_id: the id of the schema
29990 * Creates a new #GSettings object with the schema specified by
29993 * Signals on the newly created #GSettings object will be dispatched
29994 * via the thread-default #GMainContext in effect at the time of the
29995 * call to g_settings_new(). The new #GSettings will hold a reference
29996 * on the context. See g_main_context_push_thread_default().
29998 * Returns: a new #GSettings object
30004 * g_settings_new_full:
30005 * @schema: a #GSettingsSchema
30006 * @backend: (allow-none): a #GSettingsBackend
30007 * @path: (allow-none): the path to use
30009 * Creates a new #GSettings object with a given schema, backend and
30012 * It should be extremely rare that you ever want to use this function.
30013 * It is made available for advanced use-cases (such as plugin systems
30014 * that want to provide access to schemas loaded from custom locations,
30017 * At the most basic level, a #GSettings object is a pure composition of
30018 * 4 things: a #GSettingsSchema, a #GSettingsBackend, a path within that
30019 * backend, and a #GMainContext to which signals are dispatched.
30021 * This constructor therefore gives you full control over constructing
30022 * #GSettings instances. The first 4 parameters are given directly as
30023 * @schema, @backend and @path, and the main context is taken from the
30024 * thread-default (as per g_settings_new()).
30026 * If @backend is %NULL then the default backend is used.
30028 * If @path is %NULL then the path from the schema is used. It is an
30029 * error f @path is %NULL and the schema has no path of its own or if
30030 * @path is non-%NULL and not equal to the path that the schema does
30033 * Returns: a new #GSettings object
30039 * g_settings_new_with_backend:
30040 * @schema_id: the id of the schema
30041 * @backend: the #GSettingsBackend to use
30043 * Creates a new #GSettings object with the schema specified by
30044 * @schema_id and a given #GSettingsBackend.
30046 * Creating a #GSettings object with a different backend allows accessing
30047 * settings from a database other than the usual one. For example, it may make
30048 * sense to pass a backend corresponding to the "defaults" settings database on
30049 * the system to get a settings object that modifies the system default
30050 * settings instead of the settings for this user.
30052 * Returns: a new #GSettings object
30058 * g_settings_new_with_backend_and_path:
30059 * @schema_id: the id of the schema
30060 * @backend: the #GSettingsBackend to use
30061 * @path: the path to use
30063 * Creates a new #GSettings object with the schema specified by
30064 * @schema_id and a given #GSettingsBackend and path.
30066 * This is a mix of g_settings_new_with_backend() and
30067 * g_settings_new_with_path().
30069 * Returns: a new #GSettings object
30075 * g_settings_new_with_path:
30076 * @schema_id: the id of the schema
30077 * @path: the path to use
30079 * Creates a new #GSettings object with the relocatable schema specified
30080 * by @schema_id and a given path.
30082 * You only need to do this if you want to directly create a settings
30083 * object with a schema that doesn't have a specified path of its own.
30084 * That's quite rare.
30086 * It is a programmer error to call this function for a schema that
30087 * has an explicitly specified path.
30089 * It is a programmer error if @path is not a valid path. A valid path
30090 * begins and ends with '/' and does not contain two consecutive '/'
30093 * Returns: a new #GSettings object
30099 * g_settings_range_check:
30100 * @settings: a #GSettings
30101 * @key: the key to check
30102 * @value: the value to check
30104 * Checks if the given @value is of the correct type and within the
30105 * permitted range for @key.
30107 * Returns: %TRUE if @value is valid for @key
30109 * Deprecated: 2.40: Use g_settings_schema_key_range_check() instead.
30114 * g_settings_reset:
30115 * @settings: a #GSettings object
30116 * @key: the name of a key
30118 * Resets @key to its default value.
30120 * This call resets the key, as much as possible, to its default value.
30121 * That might the value specified in the schema or the one set by the
30127 * g_settings_revert:
30128 * @settings: a #GSettings instance
30130 * Reverts all non-applied changes to the settings. This function
30131 * does nothing unless @settings is in 'delay-apply' mode; see
30132 * g_settings_delay(). In the normal case settings are always applied
30135 * Change notifications will be emitted for affected keys.
30140 * g_settings_schema_get_id:
30141 * @schema: a #GSettingsSchema
30143 * Get the ID of @schema.
30145 * Returns: (transfer none): the ID
30150 * g_settings_schema_get_key:
30151 * @schema: a #GSettingsSchema
30152 * @name: the name of a key
30154 * Gets the key named @name from @schema.
30156 * It is a programmer error to request a key that does not exist. See
30157 * g_settings_schema_list_keys().
30159 * Returns: (transfer full): the #GSettingsSchemaKey for @name
30165 * g_settings_schema_get_path:
30166 * @schema: a #GSettingsSchema
30168 * Gets the path associated with @schema, or %NULL.
30170 * Schemas may be single-instance or relocatable. Single-instance
30171 * schemas correspond to exactly one set of keys in the backend
30172 * database: those located at the path returned by this function.
30174 * Relocatable schemas can be referenced by other schemas and can
30175 * threfore describe multiple sets of keys at different locations. For
30176 * relocatable schemas, this function will return %NULL.
30178 * Returns: (transfer none): the path of the schema, or %NULL
30184 * g_settings_schema_has_key:
30185 * @schema: a #GSettingsSchema
30186 * @name: the name of a key
30188 * Checks if @schema has a key named @name.
30190 * Returns: %TRUE if such a key exists
30196 * g_settings_schema_key_get_default_value:
30197 * @key: a #GSettingsSchemaKey
30199 * Gets the default value for @key.
30201 * Note that this is the default value according to the schema. System
30202 * administrator defaults and lockdown are not visible via this API.
30204 * Returns: (transfer full): the default value for the key
30210 * g_settings_schema_key_get_description:
30211 * @key: a #GSettingsSchemaKey
30213 * Gets the description for @key.
30215 * If no description has been provided in the schema for @key, returns
30218 * The description can be one sentence to several paragraphs in length.
30219 * Paragraphs are delimited with a double newline. Descriptions can be
30220 * translated and the value returned from this function is is the
30223 * This function is slow. The summary and description information for
30224 * the schemas is not stored in the compiled schema database so this
30225 * function has to parse all of the source XML files in the schema
30228 * Returns: the description for @key, or %NULL
30234 * g_settings_schema_key_get_range:
30235 * @key: a #GSettingsSchemaKey
30237 * Queries the range of a key.
30239 * This function will return a #GVariant that fully describes the range
30240 * of values that are valid for @key.
30242 * The type of #GVariant returned is `(sv)`. The string describes
30243 * the type of range restriction in effect. The type and meaning of
30244 * the value contained in the variant depends on the string.
30246 * If the string is `'type'` then the variant contains an empty array.
30247 * The element type of that empty array is the expected type of value
30248 * and all values of that type are valid.
30250 * If the string is `'enum'` then the variant contains an array
30251 * enumerating the possible values. Each item in the array is
30252 * a possible valid value and no other values are valid.
30254 * If the string is `'flags'` then the variant contains an array. Each
30255 * item in the array is a value that may appear zero or one times in an
30256 * array to be used as the value for this key. For example, if the
30257 * variant contained the array `['x', 'y']` then the valid values for
30258 * the key would be `[]`, `['x']`, `['y']`, `['x', 'y']` and
30261 * Finally, if the string is `'range'` then the variant contains a pair
30262 * of like-typed values -- the minimum and maximum permissible values
30265 * This information should not be used by normal programs. It is
30266 * considered to be a hint for introspection purposes. Normal programs
30267 * should already know what is permitted by their own schema. The
30268 * format may change in any way in the future -- but particularly, new
30269 * forms may be added to the possibilities described above.
30271 * You should free the returned value with g_variant_unref() when it is
30272 * no longer needed.
30274 * Returns: (transfer full): a #GVariant describing the range
30280 * g_settings_schema_key_get_summary:
30281 * @key: a #GSettingsSchemaKey
30283 * Gets the summary for @key.
30285 * If no summary has been provided in the schema for @key, returns
30288 * The summary is a short description of the purpose of the key; usually
30289 * one short sentence. Summaries can be translated and the value
30290 * returned from this function is is the current locale.
30292 * This function is slow. The summary and description information for
30293 * the schemas is not stored in the compiled schema database so this
30294 * function has to parse all of the source XML files in the schema
30297 * Returns: the summary for @key, or %NULL
30303 * g_settings_schema_key_get_value_type:
30304 * @key: a #GSettingsSchemaKey
30306 * Gets the #GVariantType of @key.
30308 * Returns: (transfer none): the type of @key
30314 * g_settings_schema_key_range_check:
30315 * @key: a #GSettingsSchemaKey
30316 * @value: the value to check
30318 * Checks if the given @value is of the correct type and within the
30319 * permitted range for @key.
30321 * It is a programmer error if @value is not of the correct type -- you
30322 * must check for this first.
30324 * Returns: %TRUE if @value is valid for @key
30330 * g_settings_schema_key_ref:
30331 * @key: a #GSettingsSchemaKey
30333 * Increase the reference count of @key, returning a new reference.
30335 * Returns: a new reference to @key
30341 * g_settings_schema_key_unref:
30342 * @key: a #GSettingsSchemaKey
30344 * Decrease the reference count of @key, possibly freeing it.
30351 * g_settings_schema_ref:
30352 * @schema: a #GSettingsSchema
30354 * Increase the reference count of @schema, returning a new reference.
30356 * Returns: a new reference to @schema
30362 * g_settings_schema_source_get_default:
30364 * Gets the default system schema source.
30366 * This function is not required for normal uses of #GSettings but it
30367 * may be useful to authors of plugin management systems or to those who
30368 * want to introspect the content of schemas.
30370 * If no schemas are installed, %NULL will be returned.
30372 * The returned source may actually consist of multiple schema sources
30373 * from different directories, depending on which directories were given
30374 * in `XDG_DATA_DIRS` and `GSETTINGS_SCHEMA_DIR`. For this reason, all
30375 * lookups performed against the default source should probably be done
30378 * Returns: (transfer none): the default schema source
30384 * g_settings_schema_source_list_schemas:
30385 * @source: a #GSettingsSchemaSource
30386 * @recursive: if we should recurse
30387 * @non_relocatable: (out) (transfer full) (array zero-terminated=1): the
30388 * list of non-relocatable schemas
30389 * @relocatable: (out) (transfer full) (array zero-terminated=1): the list
30390 * of relocatable schemas
30392 * Lists the schemas in a given source.
30394 * If @recursive is %TRUE then include parent sources. If %FALSE then
30395 * only include the schemas from one source (ie: one directory). You
30396 * probably want %TRUE.
30398 * Non-relocatable schemas are those for which you can call
30399 * g_settings_new(). Relocatable schemas are those for which you must
30400 * use g_settings_new_with_path().
30402 * Do not call this function from normal programs. This is designed for
30403 * use by database editors, commandline tools, etc.
30410 * g_settings_schema_source_lookup:
30411 * @source: a #GSettingsSchemaSource
30412 * @schema_id: a schema ID
30413 * @recursive: %TRUE if the lookup should be recursive
30415 * Looks up a schema with the identifier @schema_id in @source.
30417 * This function is not required for normal uses of #GSettings but it
30418 * may be useful to authors of plugin management systems or to those who
30419 * want to introspect the content of schemas.
30421 * If the schema isn't found directly in @source and @recursive is %TRUE
30422 * then the parent sources will also be checked.
30424 * If the schema isn't found, %NULL is returned.
30426 * Returns: (nullable) (transfer full): a new #GSettingsSchema
30432 * g_settings_schema_source_new_from_directory:
30433 * @directory: the filename of a directory
30434 * @parent: (allow-none): a #GSettingsSchemaSource, or %NULL
30435 * @trusted: %TRUE, if the directory is trusted
30436 * @error: a pointer to a #GError pointer set to %NULL, or %NULL
30438 * Attempts to create a new schema source corresponding to the contents
30439 * of the given directory.
30441 * This function is not required for normal uses of #GSettings but it
30442 * may be useful to authors of plugin management systems.
30444 * The directory should contain a file called `gschemas.compiled` as
30445 * produced by the [glib-compile-schemas][glib-compile-schemas] tool.
30447 * If @trusted is %TRUE then `gschemas.compiled` is trusted not to be
30448 * corrupted. This assumption has a performance advantage, but can result
30449 * in crashes or inconsistent behaviour in the case of a corrupted file.
30450 * Generally, you should set @trusted to %TRUE for files installed by the
30451 * system and to %FALSE for files in the home directory.
30453 * If @parent is non-%NULL then there are two effects.
30455 * First, if g_settings_schema_source_lookup() is called with the
30456 * @recursive flag set to %TRUE and the schema can not be found in the
30457 * source, the lookup will recurse to the parent.
30459 * Second, any references to other schemas specified within this
30460 * source (ie: `child` or `extends`) references may be resolved
30461 * from the @parent.
30463 * For this second reason, except in very unusual situations, the
30464 * @parent should probably be given as the default schema source, as
30465 * returned by g_settings_schema_source_get_default().
30472 * g_settings_schema_source_ref:
30473 * @source: a #GSettingsSchemaSource
30475 * Increase the reference count of @source, returning a new reference.
30477 * Returns: a new reference to @source
30483 * g_settings_schema_source_unref:
30484 * @source: a #GSettingsSchemaSource
30486 * Decrease the reference count of @source, possibly freeing it.
30493 * g_settings_schema_unref:
30494 * @schema: a #GSettingsSchema
30496 * Decrease the reference count of @schema, possibly freeing it.
30504 * @settings: a #GSettings object
30505 * @key: the name of the key to set
30506 * @format: a #GVariant format string
30507 * @...: arguments as per @format
30509 * Sets @key in @settings to @value.
30511 * A convenience function that combines g_settings_set_value() with
30514 * It is a programmer error to give a @key that isn't contained in the
30515 * schema for @settings or for the #GVariantType of @format to mismatch
30516 * the type given in the schema.
30518 * Returns: %TRUE if setting the key succeeded,
30519 * %FALSE if the key was not writable
30525 * g_settings_set_boolean:
30526 * @settings: a #GSettings object
30527 * @key: the name of the key to set
30528 * @value: the value to set it to
30530 * Sets @key in @settings to @value.
30532 * A convenience variant of g_settings_set() for booleans.
30534 * It is a programmer error to give a @key that isn't specified as
30535 * having a boolean type in the schema for @settings.
30537 * Returns: %TRUE if setting the key succeeded,
30538 * %FALSE if the key was not writable
30544 * g_settings_set_double:
30545 * @settings: a #GSettings object
30546 * @key: the name of the key to set
30547 * @value: the value to set it to
30549 * Sets @key in @settings to @value.
30551 * A convenience variant of g_settings_set() for doubles.
30553 * It is a programmer error to give a @key that isn't specified as
30554 * having a 'double' type in the schema for @settings.
30556 * Returns: %TRUE if setting the key succeeded,
30557 * %FALSE if the key was not writable
30563 * g_settings_set_enum:
30564 * @settings: a #GSettings object
30565 * @key: a key, within @settings
30566 * @value: an enumerated value
30568 * Looks up the enumerated type nick for @value and writes it to @key,
30569 * within @settings.
30571 * It is a programmer error to give a @key that isn't contained in the
30572 * schema for @settings or is not marked as an enumerated type, or for
30573 * @value not to be a valid value for the named type.
30575 * After performing the write, accessing @key directly with
30576 * g_settings_get_string() will return the 'nick' associated with
30579 * Returns: %TRUE, if the set succeeds
30584 * g_settings_set_flags:
30585 * @settings: a #GSettings object
30586 * @key: a key, within @settings
30587 * @value: a flags value
30589 * Looks up the flags type nicks for the bits specified by @value, puts
30590 * them in an array of strings and writes the array to @key, within
30593 * It is a programmer error to give a @key that isn't contained in the
30594 * schema for @settings or is not marked as a flags type, or for @value
30595 * to contain any bits that are not value for the named type.
30597 * After performing the write, accessing @key directly with
30598 * g_settings_get_strv() will return an array of 'nicks'; one for each
30601 * Returns: %TRUE, if the set succeeds
30606 * g_settings_set_int:
30607 * @settings: a #GSettings object
30608 * @key: the name of the key to set
30609 * @value: the value to set it to
30611 * Sets @key in @settings to @value.
30613 * A convenience variant of g_settings_set() for 32-bit integers.
30615 * It is a programmer error to give a @key that isn't specified as
30616 * having a int32 type in the schema for @settings.
30618 * Returns: %TRUE if setting the key succeeded,
30619 * %FALSE if the key was not writable
30625 * g_settings_set_string:
30626 * @settings: a #GSettings object
30627 * @key: the name of the key to set
30628 * @value: the value to set it to
30630 * Sets @key in @settings to @value.
30632 * A convenience variant of g_settings_set() for strings.
30634 * It is a programmer error to give a @key that isn't specified as
30635 * having a string type in the schema for @settings.
30637 * Returns: %TRUE if setting the key succeeded,
30638 * %FALSE if the key was not writable
30644 * g_settings_set_strv:
30645 * @settings: a #GSettings object
30646 * @key: the name of the key to set
30647 * @value: (allow-none) (array zero-terminated=1): the value to set it to, or %NULL
30649 * Sets @key in @settings to @value.
30651 * A convenience variant of g_settings_set() for string arrays. If
30652 * @value is %NULL, then @key is set to be the empty array.
30654 * It is a programmer error to give a @key that isn't specified as
30655 * having an array of strings type in the schema for @settings.
30657 * Returns: %TRUE if setting the key succeeded,
30658 * %FALSE if the key was not writable
30664 * g_settings_set_uint:
30665 * @settings: a #GSettings object
30666 * @key: the name of the key to set
30667 * @value: the value to set it to
30669 * Sets @key in @settings to @value.
30671 * A convenience variant of g_settings_set() for 32-bit unsigned
30674 * It is a programmer error to give a @key that isn't specified as
30675 * having a uint32 type in the schema for @settings.
30677 * Returns: %TRUE if setting the key succeeded,
30678 * %FALSE if the key was not writable
30684 * g_settings_set_value:
30685 * @settings: a #GSettings object
30686 * @key: the name of the key to set
30687 * @value: a #GVariant of the correct type
30689 * Sets @key in @settings to @value.
30691 * It is a programmer error to give a @key that isn't contained in the
30692 * schema for @settings or for @value to have the incorrect type, per
30695 * If @value is floating then this function consumes the reference.
30697 * Returns: %TRUE if setting the key succeeded,
30698 * %FALSE if the key was not writable
30706 * Ensures that all pending operations for the given are complete for
30707 * the default backend.
30709 * Writes made to a #GSettings are handled asynchronously. For this
30710 * reason, it is very unlikely that the changes have it to disk by the
30711 * time g_settings_set() returns.
30713 * This call will block until all of the writes have made it to the
30714 * backend. Since the mainloop is not running, no change notifications
30715 * will be dispatched during this call (but some may be queued by the
30716 * time the call is done).
30721 * g_settings_unbind:
30722 * @object: the object
30723 * @property: the property whose binding is removed
30725 * Removes an existing binding for @property on @object.
30727 * Note that bindings are automatically removed when the
30728 * object is finalized, so it is rarely necessary to call this
30736 * g_simple_action_group_add_entries:
30737 * @simple: a #GSimpleActionGroup
30738 * @entries: (array length=n_entries): a pointer to the first item in
30739 * an array of #GActionEntry structs
30740 * @n_entries: the length of @entries, or -1
30741 * @user_data: the user data for signal connections
30743 * A convenience function for creating multiple #GSimpleAction instances
30744 * and adding them to the action group.
30747 * Deprecated: 2.38: Use g_action_map_add_action_entries()
30752 * g_simple_action_group_insert:
30753 * @simple: a #GSimpleActionGroup
30754 * @action: a #GAction
30756 * Adds an action to the action group.
30758 * If the action group already contains an action with the same name as
30759 * @action then the old action is dropped from the group.
30761 * The action group takes its own reference on @action.
30764 * Deprecated: 2.38: Use g_action_map_add_action()
30769 * g_simple_action_group_lookup:
30770 * @simple: a #GSimpleActionGroup
30771 * @action_name: the name of an action
30773 * Looks up the action with the name @action_name in the group.
30775 * If no such action exists, returns %NULL.
30777 * Returns: (transfer none): a #GAction, or %NULL
30779 * Deprecated: 2.38: Use g_action_map_lookup_action()
30784 * g_simple_action_group_new:
30786 * Creates a new, empty, #GSimpleActionGroup.
30788 * Returns: a new #GSimpleActionGroup
30794 * g_simple_action_group_remove:
30795 * @simple: a #GSimpleActionGroup
30796 * @action_name: the name of the action
30798 * Removes the named action from the action group.
30800 * If no action of this name is in the group then nothing happens.
30803 * Deprecated: 2.38: Use g_action_map_remove_action()
30808 * g_simple_action_new:
30809 * @name: the name of the action
30810 * @parameter_type: (allow-none): the type of parameter to the activate function
30812 * Creates a new action.
30814 * The created action is stateless. See g_simple_action_new_stateful().
30816 * Returns: a new #GSimpleAction
30822 * g_simple_action_new_stateful:
30823 * @name: the name of the action
30824 * @parameter_type: (allow-none): the type of the parameter to the activate function
30825 * @state: the initial state of the action
30827 * Creates a new stateful action.
30829 * @state is the initial state of the action. All future state values
30830 * must have the same #GVariantType as the initial state.
30832 * If the @state GVariant is floating, it is consumed.
30834 * Returns: a new #GSimpleAction
30840 * g_simple_action_set_enabled:
30841 * @simple: a #GSimpleAction
30842 * @enabled: whether the action is enabled
30844 * Sets the action as enabled or not.
30846 * An action must be enabled in order to be activated or in order to
30847 * have its state changed from outside callers.
30849 * This should only be called by the implementor of the action. Users
30850 * of the action should not attempt to modify its enabled flag.
30857 * g_simple_action_set_state:
30858 * @simple: a #GSimpleAction
30859 * @value: the new #GVariant for the state
30861 * Sets the state of the action.
30863 * This directly updates the 'state' property to the given value.
30865 * This should only be called by the implementor of the action. Users
30866 * of the action should not attempt to directly modify the 'state'
30867 * property. Instead, they should call g_action_change_state() to
30868 * request the change.
30870 * If the @value GVariant is floating, it is consumed.
30877 * g_simple_async_report_error_in_idle: (skip)
30878 * @object: (allow-none): a #GObject, or %NULL.
30879 * @callback: a #GAsyncReadyCallback.
30880 * @user_data: user data passed to @callback.
30881 * @domain: a #GQuark containing the error domain (usually #G_IO_ERROR).
30882 * @code: a specific error code.
30883 * @format: a formatted error reporting string.
30884 * @...: a list of variables to fill in @format.
30886 * Reports an error in an asynchronous function in an idle function by
30887 * directly setting the contents of the #GAsyncResult with the given error
30893 * g_simple_async_report_gerror_in_idle:
30894 * @object: (allow-none): a #GObject, or %NULL
30895 * @callback: (scope async): a #GAsyncReadyCallback.
30896 * @user_data: (closure): user data passed to @callback.
30897 * @error: the #GError to report
30899 * Reports an error in an idle function. Similar to
30900 * g_simple_async_report_error_in_idle(), but takes a #GError rather
30901 * than building a new one.
30906 * g_simple_async_report_take_gerror_in_idle: (skip)
30907 * @object: (allow-none): a #GObject, or %NULL
30908 * @callback: a #GAsyncReadyCallback.
30909 * @user_data: user data passed to @callback.
30910 * @error: the #GError to report
30912 * Reports an error in an idle function. Similar to
30913 * g_simple_async_report_gerror_in_idle(), but takes over the caller's
30914 * ownership of @error, so the caller does not have to free it any more.
30921 * g_simple_async_result_complete:
30922 * @simple: a #GSimpleAsyncResult.
30924 * Completes an asynchronous I/O job immediately. Must be called in
30925 * the thread where the asynchronous result was to be delivered, as it
30926 * invokes the callback directly. If you are in a different thread use
30927 * g_simple_async_result_complete_in_idle().
30929 * Calling this function takes a reference to @simple for as long as
30930 * is needed to complete the call.
30935 * g_simple_async_result_complete_in_idle:
30936 * @simple: a #GSimpleAsyncResult.
30938 * Completes an asynchronous function in an idle handler in the
30939 * [thread-default main context][g-main-context-push-thread-default]
30940 * of the thread that @simple was initially created in
30941 * (and re-pushes that context around the invocation of the callback).
30943 * Calling this function takes a reference to @simple for as long as
30944 * is needed to complete the call.
30949 * g_simple_async_result_get_op_res_gboolean:
30950 * @simple: a #GSimpleAsyncResult.
30952 * Gets the operation result boolean from within the asynchronous result.
30954 * Returns: %TRUE if the operation's result was %TRUE, %FALSE
30955 * if the operation's result was %FALSE.
30960 * g_simple_async_result_get_op_res_gpointer: (skip)
30961 * @simple: a #GSimpleAsyncResult.
30963 * Gets a pointer result as returned by the asynchronous function.
30965 * Returns: a pointer from the result.
30970 * g_simple_async_result_get_op_res_gssize:
30971 * @simple: a #GSimpleAsyncResult.
30973 * Gets a gssize from the asynchronous result.
30975 * Returns: a gssize returned from the asynchronous function.
30980 * g_simple_async_result_get_source_tag: (skip)
30981 * @simple: a #GSimpleAsyncResult.
30983 * Gets the source tag for the #GSimpleAsyncResult.
30985 * Returns: a #gpointer to the source object for the #GSimpleAsyncResult.
30990 * g_simple_async_result_is_valid:
30991 * @result: the #GAsyncResult passed to the _finish function.
30992 * @source: (allow-none): the #GObject passed to the _finish function.
30993 * @source_tag: (allow-none): the asynchronous function.
30995 * Ensures that the data passed to the _finish function of an async
30996 * operation is consistent. Three checks are performed.
30998 * First, @result is checked to ensure that it is really a
30999 * #GSimpleAsyncResult. Second, @source is checked to ensure that it
31000 * matches the source object of @result. Third, @source_tag is
31001 * checked to ensure that it is equal to the @source_tag argument given
31002 * to g_simple_async_result_new() (which, by convention, is a pointer
31003 * to the _async function corresponding to the _finish function from
31004 * which this function is called). (Alternatively, if either
31005 * @source_tag or @result's source tag is %NULL, then the source tag
31006 * check is skipped.)
31008 * Returns: #TRUE if all checks passed or #FALSE if any failed.
31014 * g_simple_async_result_new:
31015 * @source_object: (allow-none): a #GObject, or %NULL.
31016 * @callback: (scope async): a #GAsyncReadyCallback.
31017 * @user_data: (closure): user data passed to @callback.
31018 * @source_tag: the asynchronous function.
31020 * Creates a #GSimpleAsyncResult.
31022 * The common convention is to create the #GSimpleAsyncResult in the
31023 * function that starts the asynchronous operation and use that same
31024 * function as the @source_tag.
31026 * If your operation supports cancellation with #GCancellable (which it
31027 * probably should) then you should provide the user's cancellable to
31028 * g_simple_async_result_set_check_cancellable() immediately after
31029 * this function returns.
31031 * Returns: a #GSimpleAsyncResult.
31036 * g_simple_async_result_new_error:
31037 * @source_object: (allow-none): a #GObject, or %NULL.
31038 * @callback: (scope async): a #GAsyncReadyCallback.
31039 * @user_data: (closure): user data passed to @callback.
31040 * @domain: a #GQuark.
31041 * @code: an error code.
31042 * @format: a string with format characters.
31043 * @...: a list of values to insert into @format.
31045 * Creates a new #GSimpleAsyncResult with a set error.
31047 * Returns: a #GSimpleAsyncResult.
31052 * g_simple_async_result_new_from_error:
31053 * @source_object: (allow-none): a #GObject, or %NULL.
31054 * @callback: (scope async): a #GAsyncReadyCallback.
31055 * @user_data: (closure): user data passed to @callback.
31056 * @error: a #GError
31058 * Creates a #GSimpleAsyncResult from an error condition.
31060 * Returns: a #GSimpleAsyncResult.
31065 * g_simple_async_result_new_take_error: (skip)
31066 * @source_object: (allow-none): a #GObject, or %NULL
31067 * @callback: (scope async): a #GAsyncReadyCallback
31068 * @user_data: (closure): user data passed to @callback
31069 * @error: a #GError
31071 * Creates a #GSimpleAsyncResult from an error condition, and takes over the
31072 * caller's ownership of @error, so the caller does not need to free it anymore.
31074 * Returns: a #GSimpleAsyncResult
31080 * g_simple_async_result_propagate_error:
31081 * @simple: a #GSimpleAsyncResult.
31082 * @dest: (out): a location to propagate the error to.
31084 * Propagates an error from within the simple asynchronous result to
31085 * a given destination.
31087 * If the #GCancellable given to a prior call to
31088 * g_simple_async_result_set_check_cancellable() is cancelled then this
31089 * function will return %TRUE with @dest set appropriately.
31091 * Returns: %TRUE if the error was propagated to @dest. %FALSE otherwise.
31096 * g_simple_async_result_run_in_thread: (skip)
31097 * @simple: a #GSimpleAsyncResult.
31098 * @func: a #GSimpleAsyncThreadFunc.
31099 * @io_priority: the io priority of the request.
31100 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
31102 * Runs the asynchronous job in a separate thread and then calls
31103 * g_simple_async_result_complete_in_idle() on @simple to return
31104 * the result to the appropriate main loop.
31106 * Calling this function takes a reference to @simple for as long as
31107 * is needed to run the job and report its completion.
31112 * g_simple_async_result_set_check_cancellable:
31113 * @simple: a #GSimpleAsyncResult
31114 * @check_cancellable: (allow-none): a #GCancellable to check, or %NULL to unset
31116 * Sets a #GCancellable to check before dispatching results.
31118 * This function has one very specific purpose: the provided cancellable
31119 * is checked at the time of g_simple_async_result_propagate_error() If
31120 * it is cancelled, these functions will return an "Operation was
31121 * cancelled" error (%G_IO_ERROR_CANCELLED).
31123 * Implementors of cancellable asynchronous functions should use this in
31124 * order to provide a guarantee to their callers that cancelling an
31125 * async operation will reliably result in an error being returned for
31126 * that operation (even if a positive result for the operation has
31127 * already been sent as an idle to the main context to be dispatched).
31129 * The checking described above is done regardless of any call to the
31130 * unrelated g_simple_async_result_set_handle_cancellation() function.
31137 * g_simple_async_result_set_error: (skip)
31138 * @simple: a #GSimpleAsyncResult.
31139 * @domain: a #GQuark (usually #G_IO_ERROR).
31140 * @code: an error code.
31141 * @format: a formatted error reporting string.
31142 * @...: a list of variables to fill in @format.
31144 * Sets an error within the asynchronous result without a #GError.
31149 * g_simple_async_result_set_error_va: (skip)
31150 * @simple: a #GSimpleAsyncResult.
31151 * @domain: a #GQuark (usually #G_IO_ERROR).
31152 * @code: an error code.
31153 * @format: a formatted error reporting string.
31154 * @args: va_list of arguments.
31156 * Sets an error within the asynchronous result without a #GError.
31157 * Unless writing a binding, see g_simple_async_result_set_error().
31162 * g_simple_async_result_set_from_error:
31163 * @simple: a #GSimpleAsyncResult.
31166 * Sets the result from a #GError.
31171 * g_simple_async_result_set_handle_cancellation:
31172 * @simple: a #GSimpleAsyncResult.
31173 * @handle_cancellation: a #gboolean.
31175 * Sets whether to handle cancellation within the asynchronous operation.
31177 * This function has nothing to do with
31178 * g_simple_async_result_set_check_cancellable(). It only refers to the
31179 * #GCancellable passed to g_simple_async_result_run_in_thread().
31184 * g_simple_async_result_set_op_res_gboolean:
31185 * @simple: a #GSimpleAsyncResult.
31186 * @op_res: a #gboolean.
31188 * Sets the operation result to a boolean within the asynchronous result.
31193 * g_simple_async_result_set_op_res_gpointer: (skip)
31194 * @simple: a #GSimpleAsyncResult.
31195 * @op_res: a pointer result from an asynchronous function.
31196 * @destroy_op_res: a #GDestroyNotify function.
31198 * Sets the operation result within the asynchronous result to a pointer.
31203 * g_simple_async_result_set_op_res_gssize:
31204 * @simple: a #GSimpleAsyncResult.
31205 * @op_res: a #gssize.
31207 * Sets the operation result within the asynchronous result to
31208 * the given @op_res.
31213 * g_simple_async_result_take_error: (skip)
31214 * @simple: a #GSimpleAsyncResult
31215 * @error: a #GError
31217 * Sets the result from @error, and takes over the caller's ownership
31218 * of @error, so the caller does not need to free it any more.
31225 * g_simple_permission_new:
31226 * @allowed: %TRUE if the action is allowed
31228 * Creates a new #GPermission instance that represents an action that is
31229 * either always or never allowed.
31231 * Returns: the #GSimplePermission, as a #GPermission
31237 * g_simple_proxy_resolver_new:
31238 * @default_proxy: (allow-none): the default proxy to use, eg
31239 * "socks://192.168.1.1"
31240 * @ignore_hosts: (allow-none): an optional list of hosts/IP addresses
31241 * to not use a proxy for.
31243 * Creates a new #GSimpleProxyResolver. See
31244 * #GSimpleProxyResolver:default-proxy and
31245 * #GSimpleProxyResolver:ignore-hosts for more details on how the
31246 * arguments are interpreted.
31248 * Returns: (transfer full): a new #GSimpleProxyResolver
31254 * g_simple_proxy_resolver_set_default_proxy:
31255 * @resolver: a #GSimpleProxyResolver
31256 * @default_proxy: the default proxy to use
31258 * Sets the default proxy on @resolver, to be used for any URIs that
31259 * don't match #GSimpleProxyResolver:ignore-hosts or a proxy set
31260 * via g_simple_proxy_resolver_set_uri_proxy().
31262 * If @default_proxy starts with "socks://",
31263 * #GSimpleProxyResolver will treat it as referring to all three of
31264 * the socks5, socks4a, and socks4 proxy types.
31271 * g_simple_proxy_resolver_set_ignore_hosts:
31272 * @resolver: a #GSimpleProxyResolver
31273 * @ignore_hosts: %NULL-terminated list of hosts/IP addresses
31274 * to not use a proxy for
31276 * Sets the list of ignored hosts.
31278 * See #GSimpleProxyResolver:ignore-hosts for more details on how the
31279 * @ignore_hosts argument is interpreted.
31286 * g_simple_proxy_resolver_set_uri_proxy:
31287 * @resolver: a #GSimpleProxyResolver
31288 * @uri_scheme: the URI scheme to add a proxy for
31289 * @proxy: the proxy to use for @uri_scheme
31291 * Adds a URI-scheme-specific proxy to @resolver; URIs whose scheme
31292 * matches @uri_scheme (and which don't match
31293 * #GSimpleProxyResolver:ignore-hosts) will be proxied via @proxy.
31295 * As with #GSimpleProxyResolver:default-proxy, if @proxy starts with
31296 * "socks://", #GSimpleProxyResolver will treat it
31297 * as referring to all three of the socks5, socks4a, and socks4 proxy
31306 * @socket: a #GSocket.
31307 * @cancellable: (allow-none): a %GCancellable or %NULL
31308 * @error: #GError for error reporting, or %NULL to ignore.
31310 * Accept incoming connections on a connection-based socket. This removes
31311 * the first outstanding connection request from the listening socket and
31312 * creates a #GSocket object for it.
31314 * The @socket must be bound to a local address with g_socket_bind() and
31315 * must be listening for incoming connections (g_socket_listen()).
31317 * If there are no outstanding connections then the operation will block
31318 * or return %G_IO_ERROR_WOULD_BLOCK if non-blocking I/O is enabled.
31319 * To be notified of an incoming connection, wait for the %G_IO_IN condition.
31321 * Returns: (transfer full): a new #GSocket, or %NULL on error.
31322 * Free the returned object with g_object_unref().
31328 * g_socket_address_enumerator_next:
31329 * @enumerator: a #GSocketAddressEnumerator
31330 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
31331 * @error: a #GError.
31333 * Retrieves the next #GSocketAddress from @enumerator. Note that this
31334 * may block for some amount of time. (Eg, a #GNetworkAddress may need
31335 * to do a DNS lookup before it can return an address.) Use
31336 * g_socket_address_enumerator_next_async() if you need to avoid
31339 * If @enumerator is expected to yield addresses, but for some reason
31340 * is unable to (eg, because of a DNS error), then the first call to
31341 * g_socket_address_enumerator_next() will return an appropriate error
31342 * in *@error. However, if the first call to
31343 * g_socket_address_enumerator_next() succeeds, then any further
31344 * internal errors (other than @cancellable being triggered) will be
31347 * Returns: (transfer full): a #GSocketAddress (owned by the caller), or %NULL on
31348 * error (in which case *@error will be set) or if there are no
31354 * g_socket_address_enumerator_next_async:
31355 * @enumerator: a #GSocketAddressEnumerator
31356 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
31357 * @callback: (scope async): a #GAsyncReadyCallback to call when the request
31359 * @user_data: (closure): the data to pass to callback function
31361 * Asynchronously retrieves the next #GSocketAddress from @enumerator
31362 * and then calls @callback, which must call
31363 * g_socket_address_enumerator_next_finish() to get the result.
31368 * g_socket_address_enumerator_next_finish:
31369 * @enumerator: a #GSocketAddressEnumerator
31370 * @result: a #GAsyncResult
31371 * @error: a #GError
31373 * Retrieves the result of a completed call to
31374 * g_socket_address_enumerator_next_async(). See
31375 * g_socket_address_enumerator_next() for more information about
31378 * Returns: (transfer full): a #GSocketAddress (owned by the caller), or %NULL on
31379 * error (in which case *@error will be set) or if there are no
31385 * g_socket_address_get_family:
31386 * @address: a #GSocketAddress
31388 * Gets the socket family type of @address.
31390 * Returns: the socket family type of @address
31396 * g_socket_address_get_native_size:
31397 * @address: a #GSocketAddress
31399 * Gets the size of @address's native struct sockaddr.
31400 * You can use this to allocate memory to pass to
31401 * g_socket_address_to_native().
31403 * Returns: the size of the native struct sockaddr that
31404 * @address represents
31410 * g_socket_address_new_from_native:
31411 * @native: a pointer to a struct sockaddr
31412 * @len: the size of the memory location pointed to by @native
31414 * Creates a #GSocketAddress subclass corresponding to the native
31415 * struct sockaddr @native.
31417 * Returns: a new #GSocketAddress if @native could successfully
31418 * be converted, otherwise %NULL
31424 * g_socket_address_to_native:
31425 * @address: a #GSocketAddress
31426 * @dest: a pointer to a memory location that will contain the native
31428 * @destlen: the size of @dest. Must be at least as large as
31429 * g_socket_address_get_native_size()
31430 * @error: #GError for error reporting, or %NULL to ignore
31432 * Converts a #GSocketAddress to a native struct sockaddr, which can
31433 * be passed to low-level functions like connect() or bind().
31435 * If not enough space is available, a %G_IO_ERROR_NO_SPACE error
31436 * is returned. If the address type is not known on the system
31437 * then a %G_IO_ERROR_NOT_SUPPORTED error is returned.
31439 * Returns: %TRUE if @dest was filled in, %FALSE on error
31446 * @socket: a #GSocket.
31447 * @address: a #GSocketAddress specifying the local address.
31448 * @allow_reuse: whether to allow reusing this address
31449 * @error: #GError for error reporting, or %NULL to ignore.
31451 * When a socket is created it is attached to an address family, but it
31452 * doesn't have an address in this family. g_socket_bind() assigns the
31453 * address (sometimes called name) of the socket.
31455 * It is generally required to bind to a local address before you can
31456 * receive connections. (See g_socket_listen() and g_socket_accept() ).
31457 * In certain situations, you may also want to bind a socket that will be
31458 * used to initiate connections, though this is not normally required.
31460 * If @socket is a TCP socket, then @allow_reuse controls the setting
31461 * of the `SO_REUSEADDR` socket option; normally it should be %TRUE for
31462 * server sockets (sockets that you will eventually call
31463 * g_socket_accept() on), and %FALSE for client sockets. (Failing to
31464 * set this flag on a server socket may cause g_socket_bind() to return
31465 * %G_IO_ERROR_ADDRESS_IN_USE if the server program is stopped and then
31466 * immediately restarted.)
31468 * If @socket is a UDP socket, then @allow_reuse determines whether or
31469 * not other UDP sockets can be bound to the same address at the same
31470 * time. In particular, you can have several UDP sockets bound to the
31471 * same address, and they will all receive all of the multicast and
31472 * broadcast packets sent to that address. (The behavior of unicast
31473 * UDP packets to an address with multiple listeners is not defined.)
31475 * Returns: %TRUE on success, %FALSE on error.
31481 * g_socket_check_connect_result:
31482 * @socket: a #GSocket
31483 * @error: #GError for error reporting, or %NULL to ignore.
31485 * Checks and resets the pending connect error for the socket.
31486 * This is used to check for errors when g_socket_connect() is
31487 * used in non-blocking mode.
31489 * Returns: %TRUE if no error, %FALSE otherwise, setting @error to the error
31495 * g_socket_client_add_application_proxy:
31496 * @client: a #GSocketClient
31497 * @protocol: The proxy protocol
31499 * Enable proxy protocols to be handled by the application. When the
31500 * indicated proxy protocol is returned by the #GProxyResolver,
31501 * #GSocketClient will consider this protocol as supported but will
31502 * not try to find a #GProxy instance to handle handshaking. The
31503 * application must check for this case by calling
31504 * g_socket_connection_get_remote_address() on the returned
31505 * #GSocketConnection, and seeing if it's a #GProxyAddress of the
31506 * appropriate type, to determine whether or not it needs to handle
31507 * the proxy handshaking itself.
31509 * This should be used for proxy protocols that are dialects of
31510 * another protocol such as HTTP proxy. It also allows cohabitation of
31511 * proxy protocols that are reused between protocols. A good example
31512 * is HTTP. It can be used to proxy HTTP, FTP and Gopher and can also
31513 * be use as generic socket proxy through the HTTP CONNECT method.
31515 * When the proxy is detected as being an application proxy, TLS handshake
31516 * will be skipped. This is required to let the application do the proxy
31517 * specific handshake.
31522 * g_socket_client_connect:
31523 * @client: a #GSocketClient.
31524 * @connectable: a #GSocketConnectable specifying the remote address.
31525 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
31526 * @error: #GError for error reporting, or %NULL to ignore.
31528 * Tries to resolve the @connectable and make a network connection to it.
31530 * Upon a successful connection, a new #GSocketConnection is constructed
31531 * and returned. The caller owns this new object and must drop their
31532 * reference to it when finished with it.
31534 * The type of the #GSocketConnection object returned depends on the type of
31535 * the underlying socket that is used. For instance, for a TCP/IP connection
31536 * it will be a #GTcpConnection.
31538 * The socket created will be the same family as the address that the
31539 * @connectable resolves to, unless family is set with g_socket_client_set_family()
31540 * or indirectly via g_socket_client_set_local_address(). The socket type
31541 * defaults to %G_SOCKET_TYPE_STREAM but can be set with
31542 * g_socket_client_set_socket_type().
31544 * If a local address is specified with g_socket_client_set_local_address() the
31545 * socket will be bound to this address before connecting.
31547 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
31553 * g_socket_client_connect_async:
31554 * @client: a #GSocketClient
31555 * @connectable: a #GSocketConnectable specifying the remote address.
31556 * @cancellable: (allow-none): a #GCancellable, or %NULL
31557 * @callback: (scope async): a #GAsyncReadyCallback
31558 * @user_data: (closure): user data for the callback
31560 * This is the asynchronous version of g_socket_client_connect().
31562 * When the operation is finished @callback will be
31563 * called. You can then call g_socket_client_connect_finish() to get
31564 * the result of the operation.
31571 * g_socket_client_connect_finish:
31572 * @client: a #GSocketClient.
31573 * @result: a #GAsyncResult.
31574 * @error: a #GError location to store the error occurring, or %NULL to
31577 * Finishes an async connect operation. See g_socket_client_connect_async()
31579 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
31585 * g_socket_client_connect_to_host:
31586 * @client: a #GSocketClient
31587 * @host_and_port: the name and optionally port of the host to connect to
31588 * @default_port: the default port to connect to
31589 * @cancellable: (allow-none): a #GCancellable, or %NULL
31590 * @error: a pointer to a #GError, or %NULL
31592 * This is a helper function for g_socket_client_connect().
31594 * Attempts to create a TCP connection to the named host.
31596 * @host_and_port may be in any of a number of recognized formats; an IPv6
31597 * address, an IPv4 address, or a domain name (in which case a DNS
31598 * lookup is performed). Quoting with [] is supported for all address
31599 * types. A port override may be specified in the usual way with a
31600 * colon. Ports may be given as decimal numbers or symbolic names (in
31601 * which case an /etc/services lookup is performed).
31603 * If no port override is given in @host_and_port then @default_port will be
31604 * used as the port number to connect to.
31606 * In general, @host_and_port is expected to be provided by the user (allowing
31607 * them to give the hostname, and a port override if necessary) and
31608 * @default_port is expected to be provided by the application.
31610 * In the case that an IP address is given, a single connection
31611 * attempt is made. In the case that a name is given, multiple
31612 * connection attempts may be made, in turn and according to the
31613 * number of address records in DNS, until a connection succeeds.
31615 * Upon a successful connection, a new #GSocketConnection is constructed
31616 * and returned. The caller owns this new object and must drop their
31617 * reference to it when finished with it.
31619 * In the event of any failure (DNS error, service not found, no hosts
31620 * connectable) %NULL is returned and @error (if non-%NULL) is set
31623 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
31629 * g_socket_client_connect_to_host_async:
31630 * @client: a #GSocketClient
31631 * @host_and_port: the name and optionally the port of the host to connect to
31632 * @default_port: the default port to connect to
31633 * @cancellable: (allow-none): a #GCancellable, or %NULL
31634 * @callback: (scope async): a #GAsyncReadyCallback
31635 * @user_data: (closure): user data for the callback
31637 * This is the asynchronous version of g_socket_client_connect_to_host().
31639 * When the operation is finished @callback will be
31640 * called. You can then call g_socket_client_connect_to_host_finish() to get
31641 * the result of the operation.
31648 * g_socket_client_connect_to_host_finish:
31649 * @client: a #GSocketClient.
31650 * @result: a #GAsyncResult.
31651 * @error: a #GError location to store the error occurring, or %NULL to
31654 * Finishes an async connect operation. See g_socket_client_connect_to_host_async()
31656 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
31662 * g_socket_client_connect_to_service:
31663 * @client: a #GSocketConnection
31664 * @domain: a domain name
31665 * @service: the name of the service to connect to
31666 * @cancellable: (allow-none): a #GCancellable, or %NULL
31667 * @error: a pointer to a #GError, or %NULL
31669 * Attempts to create a TCP connection to a service.
31671 * This call looks up the SRV record for @service at @domain for the
31672 * "tcp" protocol. It then attempts to connect, in turn, to each of
31673 * the hosts providing the service until either a connection succeeds
31674 * or there are no hosts remaining.
31676 * Upon a successful connection, a new #GSocketConnection is constructed
31677 * and returned. The caller owns this new object and must drop their
31678 * reference to it when finished with it.
31680 * In the event of any failure (DNS error, service not found, no hosts
31681 * connectable) %NULL is returned and @error (if non-%NULL) is set
31684 * Returns: (transfer full): a #GSocketConnection if successful, or %NULL on error
31689 * g_socket_client_connect_to_service_async:
31690 * @client: a #GSocketClient
31691 * @domain: a domain name
31692 * @service: the name of the service to connect to
31693 * @cancellable: (allow-none): a #GCancellable, or %NULL
31694 * @callback: (scope async): a #GAsyncReadyCallback
31695 * @user_data: (closure): user data for the callback
31697 * This is the asynchronous version of
31698 * g_socket_client_connect_to_service().
31705 * g_socket_client_connect_to_service_finish:
31706 * @client: a #GSocketClient.
31707 * @result: a #GAsyncResult.
31708 * @error: a #GError location to store the error occurring, or %NULL to
31711 * Finishes an async connect operation. See g_socket_client_connect_to_service_async()
31713 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
31719 * g_socket_client_connect_to_uri:
31720 * @client: a #GSocketClient
31721 * @uri: A network URI
31722 * @default_port: the default port to connect to
31723 * @cancellable: (allow-none): a #GCancellable, or %NULL
31724 * @error: a pointer to a #GError, or %NULL
31726 * This is a helper function for g_socket_client_connect().
31728 * Attempts to create a TCP connection with a network URI.
31730 * @uri may be any valid URI containing an "authority" (hostname/port)
31731 * component. If a port is not specified in the URI, @default_port
31732 * will be used. TLS will be negotiated if #GSocketClient:tls is %TRUE.
31733 * (#GSocketClient does not know to automatically assume TLS for
31734 * certain URI schemes.)
31736 * Using this rather than g_socket_client_connect() or
31737 * g_socket_client_connect_to_host() allows #GSocketClient to
31738 * determine when to use application-specific proxy protocols.
31740 * Upon a successful connection, a new #GSocketConnection is constructed
31741 * and returned. The caller owns this new object and must drop their
31742 * reference to it when finished with it.
31744 * In the event of any failure (DNS error, service not found, no hosts
31745 * connectable) %NULL is returned and @error (if non-%NULL) is set
31748 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
31754 * g_socket_client_connect_to_uri_async:
31755 * @client: a #GSocketClient
31756 * @uri: a network uri
31757 * @default_port: the default port to connect to
31758 * @cancellable: (allow-none): a #GCancellable, or %NULL
31759 * @callback: (scope async): a #GAsyncReadyCallback
31760 * @user_data: (closure): user data for the callback
31762 * This is the asynchronous version of g_socket_client_connect_to_uri().
31764 * When the operation is finished @callback will be
31765 * called. You can then call g_socket_client_connect_to_uri_finish() to get
31766 * the result of the operation.
31773 * g_socket_client_connect_to_uri_finish:
31774 * @client: a #GSocketClient.
31775 * @result: a #GAsyncResult.
31776 * @error: a #GError location to store the error occurring, or %NULL to
31779 * Finishes an async connect operation. See g_socket_client_connect_to_uri_async()
31781 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
31787 * g_socket_client_get_enable_proxy:
31788 * @client: a #GSocketClient.
31790 * Gets the proxy enable state; see g_socket_client_set_enable_proxy()
31792 * Returns: whether proxying is enabled
31798 * g_socket_client_get_family:
31799 * @client: a #GSocketClient.
31801 * Gets the socket family of the socket client.
31803 * See g_socket_client_set_family() for details.
31805 * Returns: a #GSocketFamily
31811 * g_socket_client_get_local_address:
31812 * @client: a #GSocketClient.
31814 * Gets the local address of the socket client.
31816 * See g_socket_client_set_local_address() for details.
31818 * Returns: (transfer none): a #GSocketAddress or %NULL. Do not free.
31824 * g_socket_client_get_protocol:
31825 * @client: a #GSocketClient
31827 * Gets the protocol name type of the socket client.
31829 * See g_socket_client_set_protocol() for details.
31831 * Returns: a #GSocketProtocol
31837 * g_socket_client_get_proxy_resolver:
31838 * @client: a #GSocketClient.
31840 * Gets the #GProxyResolver being used by @client. Normally, this will
31841 * be the resolver returned by g_proxy_resolver_get_default(), but you
31842 * can override it with g_socket_client_set_proxy_resolver().
31844 * Returns: (transfer none): The #GProxyResolver being used by
31851 * g_socket_client_get_socket_type:
31852 * @client: a #GSocketClient.
31854 * Gets the socket type of the socket client.
31856 * See g_socket_client_set_socket_type() for details.
31858 * Returns: a #GSocketFamily
31864 * g_socket_client_get_timeout:
31865 * @client: a #GSocketClient
31867 * Gets the I/O timeout time for sockets created by @client.
31869 * See g_socket_client_set_timeout() for details.
31871 * Returns: the timeout in seconds
31877 * g_socket_client_get_tls:
31878 * @client: a #GSocketClient.
31880 * Gets whether @client creates TLS connections. See
31881 * g_socket_client_set_tls() for details.
31883 * Returns: whether @client uses TLS
31889 * g_socket_client_get_tls_validation_flags:
31890 * @client: a #GSocketClient.
31892 * Gets the TLS validation flags used creating TLS connections via
31895 * Returns: the TLS validation flags
31901 * g_socket_client_new:
31903 * Creates a new #GSocketClient with the default options.
31905 * Returns: a #GSocketClient.
31906 * Free the returned object with g_object_unref().
31912 * g_socket_client_set_enable_proxy:
31913 * @client: a #GSocketClient.
31914 * @enable: whether to enable proxies
31916 * Sets whether or not @client attempts to make connections via a
31917 * proxy server. When enabled (the default), #GSocketClient will use a
31918 * #GProxyResolver to determine if a proxy protocol such as SOCKS is
31919 * needed, and automatically do the necessary proxy negotiation.
31921 * See also g_socket_client_set_proxy_resolver().
31928 * g_socket_client_set_family:
31929 * @client: a #GSocketClient.
31930 * @family: a #GSocketFamily
31932 * Sets the socket family of the socket client.
31933 * If this is set to something other than %G_SOCKET_FAMILY_INVALID
31934 * then the sockets created by this object will be of the specified
31937 * This might be useful for instance if you want to force the local
31938 * connection to be an ipv4 socket, even though the address might
31939 * be an ipv6 mapped to ipv4 address.
31946 * g_socket_client_set_local_address:
31947 * @client: a #GSocketClient.
31948 * @address: (allow-none): a #GSocketAddress, or %NULL
31950 * Sets the local address of the socket client.
31951 * The sockets created by this object will bound to the
31952 * specified address (if not %NULL) before connecting.
31954 * This is useful if you want to ensure that the local
31955 * side of the connection is on a specific port, or on
31956 * a specific interface.
31963 * g_socket_client_set_protocol:
31964 * @client: a #GSocketClient.
31965 * @protocol: a #GSocketProtocol
31967 * Sets the protocol of the socket client.
31968 * The sockets created by this object will use of the specified
31971 * If @protocol is %0 that means to use the default
31972 * protocol for the socket family and type.
31979 * g_socket_client_set_proxy_resolver:
31980 * @client: a #GSocketClient.
31981 * @proxy_resolver: (allow-none): a #GProxyResolver, or %NULL for the
31984 * Overrides the #GProxyResolver used by @client. You can call this if
31985 * you want to use specific proxies, rather than using the system
31986 * default proxy settings.
31988 * Note that whether or not the proxy resolver is actually used
31989 * depends on the setting of #GSocketClient:enable-proxy, which is not
31990 * changed by this function (but which is %TRUE by default)
31997 * g_socket_client_set_socket_type:
31998 * @client: a #GSocketClient.
31999 * @type: a #GSocketType
32001 * Sets the socket type of the socket client.
32002 * The sockets created by this object will be of the specified
32005 * It doesn't make sense to specify a type of %G_SOCKET_TYPE_DATAGRAM,
32006 * as GSocketClient is used for connection oriented services.
32013 * g_socket_client_set_timeout:
32014 * @client: a #GSocketClient.
32015 * @timeout: the timeout
32017 * Sets the I/O timeout for sockets created by @client. @timeout is a
32018 * time in seconds, or 0 for no timeout (the default).
32020 * The timeout value affects the initial connection attempt as well,
32021 * so setting this may cause calls to g_socket_client_connect(), etc,
32022 * to fail with %G_IO_ERROR_TIMED_OUT.
32029 * g_socket_client_set_tls:
32030 * @client: a #GSocketClient.
32031 * @tls: whether to use TLS
32033 * Sets whether @client creates TLS (aka SSL) connections. If @tls is
32034 * %TRUE, @client will wrap its connections in a #GTlsClientConnection
32035 * and perform a TLS handshake when connecting.
32037 * Note that since #GSocketClient must return a #GSocketConnection,
32038 * but #GTlsClientConnection is not a #GSocketConnection, this
32039 * actually wraps the resulting #GTlsClientConnection in a
32040 * #GTcpWrapperConnection when returning it. You can use
32041 * g_tcp_wrapper_connection_get_base_io_stream() on the return value
32042 * to extract the #GTlsClientConnection.
32044 * If you need to modify the behavior of the TLS handshake (eg, by
32045 * setting a client-side certificate to use, or connecting to the
32046 * #GTlsConnection::accept-certificate signal), you can connect to
32047 * @client's #GSocketClient::event signal and wait for it to be
32048 * emitted with %G_SOCKET_CLIENT_TLS_HANDSHAKING, which will give you
32049 * a chance to see the #GTlsClientConnection before the handshake
32057 * g_socket_client_set_tls_validation_flags:
32058 * @client: a #GSocketClient.
32059 * @flags: the validation flags
32061 * Sets the TLS validation flags used when creating TLS connections
32062 * via @client. The default value is %G_TLS_CERTIFICATE_VALIDATE_ALL.
32070 * @socket: a #GSocket
32071 * @error: #GError for error reporting, or %NULL to ignore.
32073 * Closes the socket, shutting down any active connection.
32075 * Closing a socket does not wait for all outstanding I/O operations
32076 * to finish, so the caller should not rely on them to be guaranteed
32077 * to complete even if the close returns with no error.
32079 * Once the socket is closed, all other operations will return
32080 * %G_IO_ERROR_CLOSED. Closing a socket multiple times will not
32083 * Sockets will be automatically closed when the last reference
32084 * is dropped, but you might want to call this function to make sure
32085 * resources are released as early as possible.
32087 * Beware that due to the way that TCP works, it is possible for
32088 * recently-sent data to be lost if either you close a socket while the
32089 * %G_IO_IN condition is set, or else if the remote connection tries to
32090 * send something to you after you close the socket but before it has
32091 * finished reading all of the data you sent. There is no easy generic
32092 * way to avoid this problem; the easiest fix is to design the network
32093 * protocol such that the client will never send data "out of turn".
32094 * Another solution is for the server to half-close the connection by
32095 * calling g_socket_shutdown() with only the @shutdown_write flag set,
32096 * and then wait for the client to notice this and close its side of the
32097 * connection, after which the server can safely call g_socket_close().
32098 * (This is what #GTcpConnection does if you call
32099 * g_tcp_connection_set_graceful_disconnect(). But of course, this
32100 * only works if the client will close its connection after the server
32103 * Returns: %TRUE on success, %FALSE on error
32109 * g_socket_condition_check:
32110 * @socket: a #GSocket
32111 * @condition: a #GIOCondition mask to check
32113 * Checks on the readiness of @socket to perform operations.
32114 * The operations specified in @condition are checked for and masked
32115 * against the currently-satisfied conditions on @socket. The result
32118 * Note that on Windows, it is possible for an operation to return
32119 * %G_IO_ERROR_WOULD_BLOCK even immediately after
32120 * g_socket_condition_check() has claimed that the socket is ready for
32121 * writing. Rather than calling g_socket_condition_check() and then
32122 * writing to the socket if it succeeds, it is generally better to
32123 * simply try writing to the socket right away, and try again later if
32124 * the initial attempt returns %G_IO_ERROR_WOULD_BLOCK.
32126 * It is meaningless to specify %G_IO_ERR or %G_IO_HUP in condition;
32127 * these conditions will always be set in the output if they are true.
32129 * This call never blocks.
32131 * Returns: the @GIOCondition mask of the current state
32137 * g_socket_condition_timed_wait:
32138 * @socket: a #GSocket
32139 * @condition: a #GIOCondition mask to wait for
32140 * @timeout: the maximum time (in microseconds) to wait, or -1
32141 * @cancellable: (allow-none): a #GCancellable, or %NULL
32142 * @error: a #GError pointer, or %NULL
32144 * Waits for up to @timeout microseconds for @condition to become true
32145 * on @socket. If the condition is met, %TRUE is returned.
32147 * If @cancellable is cancelled before the condition is met, or if
32148 * @timeout (or the socket's #GSocket:timeout) is reached before the
32149 * condition is met, then %FALSE is returned and @error, if non-%NULL,
32150 * is set to the appropriate value (%G_IO_ERROR_CANCELLED or
32151 * %G_IO_ERROR_TIMED_OUT).
32153 * If you don't want a timeout, use g_socket_condition_wait().
32154 * (Alternatively, you can pass -1 for @timeout.)
32156 * Note that although @timeout is in microseconds for consistency with
32157 * other GLib APIs, this function actually only has millisecond
32158 * resolution, and the behavior is undefined if @timeout is not an
32159 * exact number of milliseconds.
32161 * Returns: %TRUE if the condition was met, %FALSE otherwise
32167 * g_socket_condition_wait:
32168 * @socket: a #GSocket
32169 * @condition: a #GIOCondition mask to wait for
32170 * @cancellable: (allow-none): a #GCancellable, or %NULL
32171 * @error: a #GError pointer, or %NULL
32173 * Waits for @condition to become true on @socket. When the condition
32174 * is met, %TRUE is returned.
32176 * If @cancellable is cancelled before the condition is met, or if the
32177 * socket has a timeout set and it is reached before the condition is
32178 * met, then %FALSE is returned and @error, if non-%NULL, is set to
32179 * the appropriate value (%G_IO_ERROR_CANCELLED or
32180 * %G_IO_ERROR_TIMED_OUT).
32182 * See also g_socket_condition_timed_wait().
32184 * Returns: %TRUE if the condition was met, %FALSE otherwise
32190 * g_socket_connect:
32191 * @socket: a #GSocket.
32192 * @address: a #GSocketAddress specifying the remote address.
32193 * @cancellable: (allow-none): a %GCancellable or %NULL
32194 * @error: #GError for error reporting, or %NULL to ignore.
32196 * Connect the socket to the specified remote address.
32198 * For connection oriented socket this generally means we attempt to make
32199 * a connection to the @address. For a connection-less socket it sets
32200 * the default address for g_socket_send() and discards all incoming datagrams
32201 * from other sources.
32203 * Generally connection oriented sockets can only connect once, but
32204 * connection-less sockets can connect multiple times to change the
32207 * If the connect call needs to do network I/O it will block, unless
32208 * non-blocking I/O is enabled. Then %G_IO_ERROR_PENDING is returned
32209 * and the user can be notified of the connection finishing by waiting
32210 * for the G_IO_OUT condition. The result of the connection must then be
32211 * checked with g_socket_check_connect_result().
32213 * Returns: %TRUE if connected, %FALSE on error.
32219 * g_socket_connectable_enumerate:
32220 * @connectable: a #GSocketConnectable
32222 * Creates a #GSocketAddressEnumerator for @connectable.
32224 * Returns: (transfer full): a new #GSocketAddressEnumerator.
32230 * g_socket_connectable_proxy_enumerate:
32231 * @connectable: a #GSocketConnectable
32233 * Creates a #GSocketAddressEnumerator for @connectable that will
32234 * return #GProxyAddresses for addresses that you must connect
32237 * If @connectable does not implement
32238 * g_socket_connectable_proxy_enumerate(), this will fall back to
32239 * calling g_socket_connectable_enumerate().
32241 * Returns: (transfer full): a new #GSocketAddressEnumerator.
32247 * g_socket_connection_connect:
32248 * @connection: a #GSocketConnection
32249 * @address: a #GSocketAddress specifying the remote address.
32250 * @cancellable: (allow-none): a %GCancellable or %NULL
32251 * @error: #GError for error reporting, or %NULL to ignore.
32253 * Connect @connection to the specified remote address.
32255 * Returns: %TRUE if the connection succeeded, %FALSE on error
32261 * g_socket_connection_connect_async:
32262 * @connection: a #GSocketConnection
32263 * @address: a #GSocketAddress specifying the remote address.
32264 * @cancellable: (allow-none): a %GCancellable or %NULL
32265 * @callback: (scope async): a #GAsyncReadyCallback
32266 * @user_data: (closure): user data for the callback
32268 * Asynchronously connect @connection to the specified remote address.
32270 * This clears the #GSocket:blocking flag on @connection's underlying
32271 * socket if it is currently set.
32273 * Use g_socket_connection_connect_finish() to retrieve the result.
32280 * g_socket_connection_connect_finish:
32281 * @connection: a #GSocketConnection
32282 * @result: the #GAsyncResult
32283 * @error: #GError for error reporting, or %NULL to ignore.
32285 * Gets the result of a g_socket_connection_connect_async() call.
32287 * Returns: %TRUE if the connection succeeded, %FALSE on error
32293 * g_socket_connection_factory_create_connection:
32294 * @socket: a #GSocket
32296 * Creates a #GSocketConnection subclass of the right type for
32299 * Returns: (transfer full): a #GSocketConnection
32305 * g_socket_connection_factory_lookup_type:
32306 * @family: a #GSocketFamily
32307 * @type: a #GSocketType
32308 * @protocol_id: a protocol id
32310 * Looks up the #GType to be used when creating socket connections on
32311 * sockets with the specified @family, @type and @protocol_id.
32313 * If no type is registered, the #GSocketConnection base type is returned.
32315 * Returns: a #GType
32321 * g_socket_connection_factory_register_type:
32322 * @g_type: a #GType, inheriting from %G_TYPE_SOCKET_CONNECTION
32323 * @family: a #GSocketFamily
32324 * @type: a #GSocketType
32325 * @protocol: a protocol id
32327 * Looks up the #GType to be used when creating socket connections on
32328 * sockets with the specified @family, @type and @protocol.
32330 * If no type is registered, the #GSocketConnection base type is returned.
32337 * g_socket_connection_get_local_address:
32338 * @connection: a #GSocketConnection
32339 * @error: #GError for error reporting, or %NULL to ignore.
32341 * Try to get the local address of a socket connection.
32343 * Returns: (transfer full): a #GSocketAddress or %NULL on error.
32344 * Free the returned object with g_object_unref().
32350 * g_socket_connection_get_remote_address:
32351 * @connection: a #GSocketConnection
32352 * @error: #GError for error reporting, or %NULL to ignore.
32354 * Try to get the remote address of a socket connection.
32356 * Since GLib 2.40, when used with g_socket_client_connect() or
32357 * g_socket_client_connect_async(), during emission of
32358 * %G_SOCKET_CLIENT_CONNECTING, this function will return the remote
32359 * address that will be used for the connection. This allows
32360 * applications to print e.g. "Connecting to example.com
32361 * (10.42.77.3)...".
32363 * Returns: (transfer full): a #GSocketAddress or %NULL on error.
32364 * Free the returned object with g_object_unref().
32370 * g_socket_connection_get_socket:
32371 * @connection: a #GSocketConnection
32373 * Gets the underlying #GSocket object of the connection.
32374 * This can be useful if you want to do something unusual on it
32375 * not supported by the #GSocketConnection APIs.
32377 * Returns: (transfer none): a #GSocketAddress or %NULL on error.
32383 * g_socket_connection_is_connected:
32384 * @connection: a #GSocketConnection
32386 * Checks if @connection is connected. This is equivalent to calling
32387 * g_socket_is_connected() on @connection's underlying #GSocket.
32389 * Returns: whether @connection is connected
32395 * g_socket_control_message_deserialize:
32396 * @level: a socket level
32397 * @type: a socket control message type for the given @level
32398 * @size: the size of the data in bytes
32399 * @data: (array length=size) (element-type guint8): pointer to the message data
32401 * Tries to deserialize a socket control message of a given
32402 * @level and @type. This will ask all known (to GType) subclasses
32403 * of #GSocketControlMessage if they can understand this kind
32404 * of message and if so deserialize it into a #GSocketControlMessage.
32406 * If there is no implementation for this kind of control message, %NULL
32407 * will be returned.
32409 * Returns: (transfer full): the deserialized message or %NULL
32415 * g_socket_control_message_get_level:
32416 * @message: a #GSocketControlMessage
32418 * Returns the "level" (i.e. the originating protocol) of the control message.
32419 * This is often SOL_SOCKET.
32421 * Returns: an integer describing the level
32427 * g_socket_control_message_get_msg_type:
32428 * @message: a #GSocketControlMessage
32430 * Returns the protocol specific type of the control message.
32431 * For instance, for UNIX fd passing this would be SCM_RIGHTS.
32433 * Returns: an integer describing the type of control message
32439 * g_socket_control_message_get_size:
32440 * @message: a #GSocketControlMessage
32442 * Returns the space required for the control message, not including
32443 * headers or alignment.
32445 * Returns: The number of bytes required.
32451 * g_socket_control_message_serialize:
32452 * @message: a #GSocketControlMessage
32453 * @data: A buffer to write data to
32455 * Converts the data in the message to bytes placed in the
32458 * @data is guaranteed to have enough space to fit the size
32459 * returned by g_socket_control_message_get_size() on this
32467 * g_socket_create_source: (skip)
32468 * @socket: a #GSocket
32469 * @condition: a #GIOCondition mask to monitor
32470 * @cancellable: (allow-none): a %GCancellable or %NULL
32472 * Creates a #GSource that can be attached to a %GMainContext to monitor
32473 * for the availability of the specified @condition on the socket. The #GSource
32474 * keeps a reference to the @socket.
32476 * The callback on the source is of the #GSocketSourceFunc type.
32478 * It is meaningless to specify %G_IO_ERR or %G_IO_HUP in @condition;
32479 * these conditions will always be reported output if they are true.
32481 * @cancellable if not %NULL can be used to cancel the source, which will
32482 * cause the source to trigger, reporting the current condition (which
32483 * is likely 0 unless cancellation happened at the same time as a
32484 * condition change). You can check for this in the callback using
32485 * g_cancellable_is_cancelled().
32487 * If @socket has a timeout set, and it is reached before @condition
32488 * occurs, the source will then trigger anyway, reporting %G_IO_IN or
32489 * %G_IO_OUT depending on @condition. However, @socket will have been
32490 * marked as having had a timeout, and so the next #GSocket I/O method
32491 * you call will then fail with a %G_IO_ERROR_TIMED_OUT.
32493 * Returns: (transfer full): a newly allocated %GSource, free with g_source_unref().
32499 * g_socket_get_available_bytes:
32500 * @socket: a #GSocket
32502 * Get the amount of data pending in the OS input buffer.
32504 * If @socket is a UDP or SCTP socket, this will return the size of
32505 * just the next packet, even if additional packets are buffered after
32508 * Note that on Windows, this function is rather inefficient in the
32509 * UDP case, and so if you know any plausible upper bound on the size
32510 * of the incoming packet, it is better to just do a
32511 * g_socket_receive() with a buffer of that size, rather than calling
32512 * g_socket_get_available_bytes() first and then doing a receive of
32513 * exactly the right size.
32515 * Returns: the number of bytes that can be read from the socket
32516 * without blocking or truncating, or -1 on error.
32522 * g_socket_get_blocking:
32523 * @socket: a #GSocket.
32525 * Gets the blocking mode of the socket. For details on blocking I/O,
32526 * see g_socket_set_blocking().
32528 * Returns: %TRUE if blocking I/O is used, %FALSE otherwise.
32534 * g_socket_get_broadcast:
32535 * @socket: a #GSocket.
32537 * Gets the broadcast setting on @socket; if %TRUE,
32538 * it is possible to send packets to broadcast
32541 * Returns: the broadcast setting on @socket
32547 * g_socket_get_credentials:
32548 * @socket: a #GSocket.
32549 * @error: #GError for error reporting, or %NULL to ignore.
32551 * Returns the credentials of the foreign process connected to this
32552 * socket, if any (e.g. it is only supported for %G_SOCKET_FAMILY_UNIX
32555 * If this operation isn't supported on the OS, the method fails with
32556 * the %G_IO_ERROR_NOT_SUPPORTED error. On Linux this is implemented
32557 * by reading the %SO_PEERCRED option on the underlying socket.
32559 * Other ways to obtain credentials from a foreign peer includes the
32560 * #GUnixCredentialsMessage type and
32561 * g_unix_connection_send_credentials() /
32562 * g_unix_connection_receive_credentials() functions.
32564 * Returns: (transfer full): %NULL if @error is set, otherwise a #GCredentials object
32565 * that must be freed with g_object_unref().
32571 * g_socket_get_family:
32572 * @socket: a #GSocket.
32574 * Gets the socket family of the socket.
32576 * Returns: a #GSocketFamily
32583 * @socket: a #GSocket.
32585 * Returns the underlying OS socket object. On unix this
32586 * is a socket file descriptor, and on Windows this is
32587 * a Winsock2 SOCKET handle. This may be useful for
32588 * doing platform specific or otherwise unusual operations
32591 * Returns: the file descriptor of the socket.
32597 * g_socket_get_keepalive:
32598 * @socket: a #GSocket.
32600 * Gets the keepalive mode of the socket. For details on this,
32601 * see g_socket_set_keepalive().
32603 * Returns: %TRUE if keepalive is active, %FALSE otherwise.
32609 * g_socket_get_listen_backlog:
32610 * @socket: a #GSocket.
32612 * Gets the listen backlog setting of the socket. For details on this,
32613 * see g_socket_set_listen_backlog().
32615 * Returns: the maximum number of pending connections.
32621 * g_socket_get_local_address:
32622 * @socket: a #GSocket.
32623 * @error: #GError for error reporting, or %NULL to ignore.
32625 * Try to get the local address of a bound socket. This is only
32626 * useful if the socket has been bound to a local address,
32627 * either explicitly or implicitly when connecting.
32629 * Returns: (transfer full): a #GSocketAddress or %NULL on error.
32630 * Free the returned object with g_object_unref().
32636 * g_socket_get_multicast_loopback:
32637 * @socket: a #GSocket.
32639 * Gets the multicast loopback setting on @socket; if %TRUE (the
32640 * default), outgoing multicast packets will be looped back to
32641 * multicast listeners on the same host.
32643 * Returns: the multicast loopback setting on @socket
32649 * g_socket_get_multicast_ttl:
32650 * @socket: a #GSocket.
32652 * Gets the multicast time-to-live setting on @socket; see
32653 * g_socket_set_multicast_ttl() for more details.
32655 * Returns: the multicast time-to-live setting on @socket
32661 * g_socket_get_option:
32662 * @socket: a #GSocket
32663 * @level: the "API level" of the option (eg, `SOL_SOCKET`)
32664 * @optname: the "name" of the option (eg, `SO_BROADCAST`)
32665 * @value: (out): return location for the option value
32666 * @error: #GError for error reporting, or %NULL to ignore.
32668 * Gets the value of an integer-valued option on @socket, as with
32669 * getsockopt(). (If you need to fetch a non-integer-valued option,
32670 * you will need to call getsockopt() directly.)
32672 * The [<gio/gnetworking.h>][gio-gnetworking.h]
32673 * header pulls in system headers that will define most of the
32674 * standard/portable socket options. For unusual socket protocols or
32675 * platform-dependent options, you may need to include additional
32678 * Note that even for socket options that are a single byte in size,
32679 * @value is still a pointer to a #gint variable, not a #guchar;
32680 * g_socket_get_option() will handle the conversion internally.
32682 * Returns: success or failure. On failure, @error will be set, and
32683 * the system error value (`errno` or WSAGetLastError()) will still
32684 * be set to the result of the getsockopt() call.
32690 * g_socket_get_protocol:
32691 * @socket: a #GSocket.
32693 * Gets the socket protocol id the socket was created with.
32694 * In case the protocol is unknown, -1 is returned.
32696 * Returns: a protocol id, or -1 if unknown
32702 * g_socket_get_remote_address:
32703 * @socket: a #GSocket.
32704 * @error: #GError for error reporting, or %NULL to ignore.
32706 * Try to get the remove address of a connected socket. This is only
32707 * useful for connection oriented sockets that have been connected.
32709 * Returns: (transfer full): a #GSocketAddress or %NULL on error.
32710 * Free the returned object with g_object_unref().
32716 * g_socket_get_socket_type:
32717 * @socket: a #GSocket.
32719 * Gets the socket type of the socket.
32721 * Returns: a #GSocketType
32727 * g_socket_get_timeout:
32728 * @socket: a #GSocket.
32730 * Gets the timeout setting of the socket. For details on this, see
32731 * g_socket_set_timeout().
32733 * Returns: the timeout in seconds
32739 * g_socket_get_ttl:
32740 * @socket: a #GSocket.
32742 * Gets the unicast time-to-live setting on @socket; see
32743 * g_socket_set_ttl() for more details.
32745 * Returns: the time-to-live setting on @socket
32751 * g_socket_is_closed:
32752 * @socket: a #GSocket
32754 * Checks whether a socket is closed.
32756 * Returns: %TRUE if socket is closed, %FALSE otherwise
32762 * g_socket_is_connected:
32763 * @socket: a #GSocket.
32765 * Check whether the socket is connected. This is only useful for
32766 * connection-oriented sockets.
32768 * Returns: %TRUE if socket is connected, %FALSE otherwise.
32774 * g_socket_join_multicast_group:
32775 * @socket: a #GSocket.
32776 * @group: a #GInetAddress specifying the group address to join.
32777 * @iface: (allow-none): Name of the interface to use, or %NULL
32778 * @source_specific: %TRUE if source-specific multicast should be used
32779 * @error: #GError for error reporting, or %NULL to ignore.
32781 * Registers @socket to receive multicast messages sent to @group.
32782 * @socket must be a %G_SOCKET_TYPE_DATAGRAM socket, and must have
32783 * been bound to an appropriate interface and port with
32786 * If @iface is %NULL, the system will automatically pick an interface
32787 * to bind to based on @group.
32789 * If @source_specific is %TRUE, source-specific multicast as defined
32790 * in RFC 4604 is used. Note that on older platforms this may fail
32791 * with a %G_IO_ERROR_NOT_SUPPORTED error.
32793 * Returns: %TRUE on success, %FALSE on error.
32799 * g_socket_leave_multicast_group:
32800 * @socket: a #GSocket.
32801 * @group: a #GInetAddress specifying the group address to leave.
32802 * @iface: (allow-none): Interface used
32803 * @source_specific: %TRUE if source-specific multicast was used
32804 * @error: #GError for error reporting, or %NULL to ignore.
32806 * Removes @socket from the multicast group defined by @group, @iface,
32807 * and @source_specific (which must all have the same values they had
32808 * when you joined the group).
32810 * @socket remains bound to its address and port, and can still receive
32811 * unicast messages after calling this.
32813 * Returns: %TRUE on success, %FALSE on error.
32820 * @socket: a #GSocket.
32821 * @error: #GError for error reporting, or %NULL to ignore.
32823 * Marks the socket as a server socket, i.e. a socket that is used
32824 * to accept incoming requests using g_socket_accept().
32826 * Before calling this the socket must be bound to a local address using
32829 * To set the maximum amount of outstanding clients, use
32830 * g_socket_set_listen_backlog().
32832 * Returns: %TRUE on success, %FALSE on error.
32838 * g_socket_listener_accept:
32839 * @listener: a #GSocketListener
32840 * @source_object: (out) (transfer none) (allow-none): location where #GObject pointer will be stored, or %NULL
32841 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
32842 * @error: #GError for error reporting, or %NULL to ignore.
32844 * Blocks waiting for a client to connect to any of the sockets added
32845 * to the listener. Returns a #GSocketConnection for the socket that was
32848 * If @source_object is not %NULL it will be filled out with the source
32849 * object specified when the corresponding socket or address was added
32852 * If @cancellable is not %NULL, then the operation can be cancelled by
32853 * triggering the cancellable object from another thread. If the operation
32854 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
32856 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
32862 * g_socket_listener_accept_async:
32863 * @listener: a #GSocketListener
32864 * @cancellable: (allow-none): a #GCancellable, or %NULL
32865 * @callback: (scope async): a #GAsyncReadyCallback
32866 * @user_data: (closure): user data for the callback
32868 * This is the asynchronous version of g_socket_listener_accept().
32870 * When the operation is finished @callback will be
32871 * called. You can then call g_socket_listener_accept_socket()
32872 * to get the result of the operation.
32879 * g_socket_listener_accept_finish:
32880 * @listener: a #GSocketListener
32881 * @result: a #GAsyncResult.
32882 * @source_object: (out) (transfer none) (allow-none): Optional #GObject identifying this source
32883 * @error: a #GError location to store the error occurring, or %NULL to
32886 * Finishes an async accept operation. See g_socket_listener_accept_async()
32888 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
32894 * g_socket_listener_accept_socket:
32895 * @listener: a #GSocketListener
32896 * @source_object: (out) (transfer none) (allow-none): location where #GObject pointer will be stored, or %NULL.
32897 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
32898 * @error: #GError for error reporting, or %NULL to ignore.
32900 * Blocks waiting for a client to connect to any of the sockets added
32901 * to the listener. Returns the #GSocket that was accepted.
32903 * If you want to accept the high-level #GSocketConnection, not a #GSocket,
32904 * which is often the case, then you should use g_socket_listener_accept()
32907 * If @source_object is not %NULL it will be filled out with the source
32908 * object specified when the corresponding socket or address was added
32911 * If @cancellable is not %NULL, then the operation can be cancelled by
32912 * triggering the cancellable object from another thread. If the operation
32913 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
32915 * Returns: (transfer full): a #GSocket on success, %NULL on error.
32921 * g_socket_listener_accept_socket_async:
32922 * @listener: a #GSocketListener
32923 * @cancellable: (allow-none): a #GCancellable, or %NULL
32924 * @callback: (scope async): a #GAsyncReadyCallback
32925 * @user_data: (closure): user data for the callback
32927 * This is the asynchronous version of g_socket_listener_accept_socket().
32929 * When the operation is finished @callback will be
32930 * called. You can then call g_socket_listener_accept_socket_finish()
32931 * to get the result of the operation.
32938 * g_socket_listener_accept_socket_finish:
32939 * @listener: a #GSocketListener
32940 * @result: a #GAsyncResult.
32941 * @source_object: (out) (transfer none) (allow-none): Optional #GObject identifying this source
32942 * @error: a #GError location to store the error occurring, or %NULL to
32945 * Finishes an async accept operation. See g_socket_listener_accept_socket_async()
32947 * Returns: (transfer full): a #GSocket on success, %NULL on error.
32953 * g_socket_listener_add_address:
32954 * @listener: a #GSocketListener
32955 * @address: a #GSocketAddress
32956 * @type: a #GSocketType
32957 * @protocol: a #GSocketProtocol
32958 * @source_object: (allow-none): Optional #GObject identifying this source
32959 * @effective_address: (out) (allow-none): location to store the address that was bound to, or %NULL.
32960 * @error: #GError for error reporting, or %NULL to ignore.
32962 * Creates a socket of type @type and protocol @protocol, binds
32963 * it to @address and adds it to the set of sockets we're accepting
32966 * Note that adding an IPv6 address, depending on the platform,
32967 * may or may not result in a listener that also accepts IPv4
32968 * connections. For more deterministic behavior, see
32969 * g_socket_listener_add_inet_port().
32971 * @source_object will be passed out in the various calls
32972 * to accept to identify this particular source, which is
32973 * useful if you're listening on multiple addresses and do
32974 * different things depending on what address is connected to.
32976 * If successful and @effective_address is non-%NULL then it will
32977 * be set to the address that the binding actually occurred at. This
32978 * is helpful for determining the port number that was used for when
32979 * requesting a binding to port 0 (ie: "any port"). This address, if
32980 * requested, belongs to the caller and must be freed.
32982 * Returns: %TRUE on success, %FALSE on error.
32988 * g_socket_listener_add_any_inet_port:
32989 * @listener: a #GSocketListener
32990 * @source_object: (allow-none): Optional #GObject identifying this source
32991 * @error: a #GError location to store the error occurring, or %NULL to
32994 * Listens for TCP connections on any available port number for both
32995 * IPv6 and IPv4 (if each is available).
32997 * This is useful if you need to have a socket for incoming connections
32998 * but don't care about the specific port number.
33000 * @source_object will be passed out in the various calls
33001 * to accept to identify this particular source, which is
33002 * useful if you're listening on multiple addresses and do
33003 * different things depending on what address is connected to.
33005 * Returns: the port number, or 0 in case of failure.
33011 * g_socket_listener_add_inet_port:
33012 * @listener: a #GSocketListener
33013 * @port: an IP port number (non-zero)
33014 * @source_object: (allow-none): Optional #GObject identifying this source
33015 * @error: #GError for error reporting, or %NULL to ignore.
33017 * Helper function for g_socket_listener_add_address() that
33018 * creates a TCP/IP socket listening on IPv4 and IPv6 (if
33019 * supported) on the specified port on all interfaces.
33021 * @source_object will be passed out in the various calls
33022 * to accept to identify this particular source, which is
33023 * useful if you're listening on multiple addresses and do
33024 * different things depending on what address is connected to.
33026 * Returns: %TRUE on success, %FALSE on error.
33032 * g_socket_listener_add_socket:
33033 * @listener: a #GSocketListener
33034 * @socket: a listening #GSocket
33035 * @source_object: (allow-none): Optional #GObject identifying this source
33036 * @error: #GError for error reporting, or %NULL to ignore.
33038 * Adds @socket to the set of sockets that we try to accept
33039 * new clients from. The socket must be bound to a local
33040 * address and listened to.
33042 * @source_object will be passed out in the various calls
33043 * to accept to identify this particular source, which is
33044 * useful if you're listening on multiple addresses and do
33045 * different things depending on what address is connected to.
33047 * The @socket will not be automatically closed when the @listener is finalized
33048 * unless the listener held the final reference to the socket. Before GLib 2.42,
33049 * the @socket was automatically closed on finalization of the @listener, even
33050 * if references to it were held elsewhere.
33052 * Returns: %TRUE on success, %FALSE on error.
33058 * g_socket_listener_close:
33059 * @listener: a #GSocketListener
33061 * Closes all the sockets in the listener.
33068 * g_socket_listener_new:
33070 * Creates a new #GSocketListener with no sockets to listen for.
33071 * New listeners can be added with e.g. g_socket_listener_add_address()
33072 * or g_socket_listener_add_inet_port().
33074 * Returns: a new #GSocketListener.
33080 * g_socket_listener_set_backlog:
33081 * @listener: a #GSocketListener
33082 * @listen_backlog: an integer
33084 * Sets the listen backlog on the sockets in the listener.
33086 * See g_socket_set_listen_backlog() for details
33094 * @family: the socket family to use, e.g. %G_SOCKET_FAMILY_IPV4.
33095 * @type: the socket type to use.
33096 * @protocol: the id of the protocol to use, or 0 for default.
33097 * @error: #GError for error reporting, or %NULL to ignore.
33099 * Creates a new #GSocket with the defined family, type and protocol.
33100 * If @protocol is 0 (%G_SOCKET_PROTOCOL_DEFAULT) the default protocol type
33101 * for the family and type is used.
33103 * The @protocol is a family and type specific int that specifies what
33104 * kind of protocol to use. #GSocketProtocol lists several common ones.
33105 * Many families only support one protocol, and use 0 for this, others
33106 * support several and using 0 means to use the default protocol for
33107 * the family and type.
33109 * The protocol id is passed directly to the operating
33110 * system, so you can use protocols not listed in #GSocketProtocol if you
33111 * know the protocol number used for it.
33113 * Returns: a #GSocket or %NULL on error.
33114 * Free the returned object with g_object_unref().
33120 * g_socket_new_from_fd:
33121 * @fd: a native socket file descriptor.
33122 * @error: #GError for error reporting, or %NULL to ignore.
33124 * Creates a new #GSocket from a native file descriptor
33125 * or winsock SOCKET handle.
33127 * This reads all the settings from the file descriptor so that
33128 * all properties should work. Note that the file descriptor
33129 * will be set to non-blocking mode, independent on the blocking
33130 * mode of the #GSocket.
33132 * Returns: a #GSocket or %NULL on error.
33133 * Free the returned object with g_object_unref().
33139 * g_socket_receive:
33140 * @socket: a #GSocket
33141 * @buffer: (array length=size) (element-type guint8): a buffer to
33142 * read data into (which should be at least @size bytes long).
33143 * @size: the number of bytes you want to read from the socket
33144 * @cancellable: (allow-none): a %GCancellable or %NULL
33145 * @error: #GError for error reporting, or %NULL to ignore.
33147 * Receive data (up to @size bytes) from a socket. This is mainly used by
33148 * connection-oriented sockets; it is identical to g_socket_receive_from()
33149 * with @address set to %NULL.
33151 * For %G_SOCKET_TYPE_DATAGRAM and %G_SOCKET_TYPE_SEQPACKET sockets,
33152 * g_socket_receive() will always read either 0 or 1 complete messages from
33153 * the socket. If the received message is too large to fit in @buffer, then
33154 * the data beyond @size bytes will be discarded, without any explicit
33155 * indication that this has occurred.
33157 * For %G_SOCKET_TYPE_STREAM sockets, g_socket_receive() can return any
33158 * number of bytes, up to @size. If more than @size bytes have been
33159 * received, the additional data will be returned in future calls to
33160 * g_socket_receive().
33162 * If the socket is in blocking mode the call will block until there
33163 * is some data to receive, the connection is closed, or there is an
33164 * error. If there is no data available and the socket is in
33165 * non-blocking mode, a %G_IO_ERROR_WOULD_BLOCK error will be
33166 * returned. To be notified when data is available, wait for the
33167 * %G_IO_IN condition.
33169 * On error -1 is returned and @error is set accordingly.
33171 * Returns: Number of bytes read, or 0 if the connection was closed by
33172 * the peer, or -1 on error
33178 * g_socket_receive_from:
33179 * @socket: a #GSocket
33180 * @address: (out) (allow-none): a pointer to a #GSocketAddress
33181 * pointer, or %NULL
33182 * @buffer: (array length=size) (element-type guint8): a buffer to
33183 * read data into (which should be at least @size bytes long).
33184 * @size: the number of bytes you want to read from the socket
33185 * @cancellable: (allow-none): a %GCancellable or %NULL
33186 * @error: #GError for error reporting, or %NULL to ignore.
33188 * Receive data (up to @size bytes) from a socket.
33190 * If @address is non-%NULL then @address will be set equal to the
33191 * source address of the received packet.
33192 * @address is owned by the caller.
33194 * See g_socket_receive() for additional information.
33196 * Returns: Number of bytes read, or 0 if the connection was closed by
33197 * the peer, or -1 on error
33203 * g_socket_receive_message:
33204 * @socket: a #GSocket
33205 * @address: (out) (allow-none): a pointer to a #GSocketAddress
33206 * pointer, or %NULL
33207 * @vectors: (array length=num_vectors): an array of #GInputVector structs
33208 * @num_vectors: the number of elements in @vectors, or -1
33209 * @messages: (array length=num_messages) (allow-none): a pointer which
33210 * may be filled with an array of #GSocketControlMessages, or %NULL
33211 * @num_messages: a pointer which will be filled with the number of
33212 * elements in @messages, or %NULL
33213 * @flags: a pointer to an int containing #GSocketMsgFlags flags
33214 * @cancellable: (allow-none): a %GCancellable or %NULL
33215 * @error: a #GError pointer, or %NULL
33217 * Receive data from a socket. This is the most complicated and
33218 * fully-featured version of this call. For easier use, see
33219 * g_socket_receive() and g_socket_receive_from().
33221 * If @address is non-%NULL then @address will be set equal to the
33222 * source address of the received packet.
33223 * @address is owned by the caller.
33225 * @vector must point to an array of #GInputVector structs and
33226 * @num_vectors must be the length of this array. These structs
33227 * describe the buffers that received data will be scattered into.
33228 * If @num_vectors is -1, then @vectors is assumed to be terminated
33229 * by a #GInputVector with a %NULL buffer pointer.
33231 * As a special case, if @num_vectors is 0 (in which case, @vectors
33232 * may of course be %NULL), then a single byte is received and
33233 * discarded. This is to facilitate the common practice of sending a
33234 * single '\0' byte for the purposes of transferring ancillary data.
33236 * @messages, if non-%NULL, will be set to point to a newly-allocated
33237 * array of #GSocketControlMessage instances or %NULL if no such
33238 * messages was received. These correspond to the control messages
33239 * received from the kernel, one #GSocketControlMessage per message
33240 * from the kernel. This array is %NULL-terminated and must be freed
33241 * by the caller using g_free() after calling g_object_unref() on each
33242 * element. If @messages is %NULL, any control messages received will
33245 * @num_messages, if non-%NULL, will be set to the number of control
33246 * messages received.
33248 * If both @messages and @num_messages are non-%NULL, then
33249 * @num_messages gives the number of #GSocketControlMessage instances
33250 * in @messages (ie: not including the %NULL terminator).
33252 * @flags is an in/out parameter. The commonly available arguments
33253 * for this are available in the #GSocketMsgFlags enum, but the
33254 * values there are the same as the system values, and the flags
33255 * are passed in as-is, so you can pass in system-specific flags too
33256 * (and g_socket_receive_message() may pass system-specific flags out).
33258 * As with g_socket_receive(), data may be discarded if @socket is
33259 * %G_SOCKET_TYPE_DATAGRAM or %G_SOCKET_TYPE_SEQPACKET and you do not
33260 * provide enough buffer space to read a complete message. You can pass
33261 * %G_SOCKET_MSG_PEEK in @flags to peek at the current message without
33262 * removing it from the receive queue, but there is no portable way to find
33263 * out the length of the message other than by reading it into a
33264 * sufficiently-large buffer.
33266 * If the socket is in blocking mode the call will block until there
33267 * is some data to receive, the connection is closed, or there is an
33268 * error. If there is no data available and the socket is in
33269 * non-blocking mode, a %G_IO_ERROR_WOULD_BLOCK error will be
33270 * returned. To be notified when data is available, wait for the
33271 * %G_IO_IN condition.
33273 * On error -1 is returned and @error is set accordingly.
33275 * Returns: Number of bytes read, or 0 if the connection was closed by
33276 * the peer, or -1 on error
33282 * g_socket_receive_with_blocking:
33283 * @socket: a #GSocket
33284 * @buffer: (array length=size) (element-type guint8): a buffer to
33285 * read data into (which should be at least @size bytes long).
33286 * @size: the number of bytes you want to read from the socket
33287 * @blocking: whether to do blocking or non-blocking I/O
33288 * @cancellable: (allow-none): a %GCancellable or %NULL
33289 * @error: #GError for error reporting, or %NULL to ignore.
33291 * This behaves exactly the same as g_socket_receive(), except that
33292 * the choice of blocking or non-blocking behavior is determined by
33293 * the @blocking argument rather than by @socket's properties.
33295 * Returns: Number of bytes read, or 0 if the connection was closed by
33296 * the peer, or -1 on error
33303 * @socket: a #GSocket
33304 * @buffer: (array length=size) (element-type guint8): the buffer
33305 * containing the data to send.
33306 * @size: the number of bytes to send
33307 * @cancellable: (allow-none): a %GCancellable or %NULL
33308 * @error: #GError for error reporting, or %NULL to ignore.
33310 * Tries to send @size bytes from @buffer on the socket. This is
33311 * mainly used by connection-oriented sockets; it is identical to
33312 * g_socket_send_to() with @address set to %NULL.
33314 * If the socket is in blocking mode the call will block until there is
33315 * space for the data in the socket queue. If there is no space available
33316 * and the socket is in non-blocking mode a %G_IO_ERROR_WOULD_BLOCK error
33317 * will be returned. To be notified when space is available, wait for the
33318 * %G_IO_OUT condition. Note though that you may still receive
33319 * %G_IO_ERROR_WOULD_BLOCK from g_socket_send() even if you were previously
33320 * notified of a %G_IO_OUT condition. (On Windows in particular, this is
33321 * very common due to the way the underlying APIs work.)
33323 * On error -1 is returned and @error is set accordingly.
33325 * Returns: Number of bytes written (which may be less than @size), or -1
33332 * g_socket_send_message:
33333 * @socket: a #GSocket
33334 * @address: (allow-none): a #GSocketAddress, or %NULL
33335 * @vectors: (array length=num_vectors): an array of #GOutputVector structs
33336 * @num_vectors: the number of elements in @vectors, or -1
33337 * @messages: (array length=num_messages) (allow-none): a pointer to an
33338 * array of #GSocketControlMessages, or %NULL.
33339 * @num_messages: number of elements in @messages, or -1.
33340 * @flags: an int containing #GSocketMsgFlags flags
33341 * @cancellable: (allow-none): a %GCancellable or %NULL
33342 * @error: #GError for error reporting, or %NULL to ignore.
33344 * Send data to @address on @socket. This is the most complicated and
33345 * fully-featured version of this call. For easier use, see
33346 * g_socket_send() and g_socket_send_to().
33348 * If @address is %NULL then the message is sent to the default receiver
33349 * (set by g_socket_connect()).
33351 * @vectors must point to an array of #GOutputVector structs and
33352 * @num_vectors must be the length of this array. (If @num_vectors is -1,
33353 * then @vectors is assumed to be terminated by a #GOutputVector with a
33354 * %NULL buffer pointer.) The #GOutputVector structs describe the buffers
33355 * that the sent data will be gathered from. Using multiple
33356 * #GOutputVectors is more memory-efficient than manually copying
33357 * data from multiple sources into a single buffer, and more
33358 * network-efficient than making multiple calls to g_socket_send().
33360 * @messages, if non-%NULL, is taken to point to an array of @num_messages
33361 * #GSocketControlMessage instances. These correspond to the control
33362 * messages to be sent on the socket.
33363 * If @num_messages is -1 then @messages is treated as a %NULL-terminated
33366 * @flags modify how the message is sent. The commonly available arguments
33367 * for this are available in the #GSocketMsgFlags enum, but the
33368 * values there are the same as the system values, and the flags
33369 * are passed in as-is, so you can pass in system-specific flags too.
33371 * If the socket is in blocking mode the call will block until there is
33372 * space for the data in the socket queue. If there is no space available
33373 * and the socket is in non-blocking mode a %G_IO_ERROR_WOULD_BLOCK error
33374 * will be returned. To be notified when space is available, wait for the
33375 * %G_IO_OUT condition. Note though that you may still receive
33376 * %G_IO_ERROR_WOULD_BLOCK from g_socket_send() even if you were previously
33377 * notified of a %G_IO_OUT condition. (On Windows in particular, this is
33378 * very common due to the way the underlying APIs work.)
33380 * On error -1 is returned and @error is set accordingly.
33382 * Returns: Number of bytes written (which may be less than @size), or -1
33389 * g_socket_send_to:
33390 * @socket: a #GSocket
33391 * @address: (allow-none): a #GSocketAddress, or %NULL
33392 * @buffer: (array length=size) (element-type guint8): the buffer
33393 * containing the data to send.
33394 * @size: the number of bytes to send
33395 * @cancellable: (allow-none): a %GCancellable or %NULL
33396 * @error: #GError for error reporting, or %NULL to ignore.
33398 * Tries to send @size bytes from @buffer to @address. If @address is
33399 * %NULL then the message is sent to the default receiver (set by
33400 * g_socket_connect()).
33402 * See g_socket_send() for additional information.
33404 * Returns: Number of bytes written (which may be less than @size), or -1
33411 * g_socket_send_with_blocking:
33412 * @socket: a #GSocket
33413 * @buffer: (array length=size) (element-type guint8): the buffer
33414 * containing the data to send.
33415 * @size: the number of bytes to send
33416 * @blocking: whether to do blocking or non-blocking I/O
33417 * @cancellable: (allow-none): a %GCancellable or %NULL
33418 * @error: #GError for error reporting, or %NULL to ignore.
33420 * This behaves exactly the same as g_socket_send(), except that
33421 * the choice of blocking or non-blocking behavior is determined by
33422 * the @blocking argument rather than by @socket's properties.
33424 * Returns: Number of bytes written (which may be less than @size), or -1
33431 * g_socket_service_is_active:
33432 * @service: a #GSocketService
33434 * Check whether the service is active or not. An active
33435 * service will accept new clients that connect, while
33436 * a non-active service will let connecting clients queue
33437 * up until the service is started.
33439 * Returns: %TRUE if the service is active, %FALSE otherwise
33445 * g_socket_service_new:
33447 * Creates a new #GSocketService with no sockets to listen for.
33448 * New listeners can be added with e.g. g_socket_listener_add_address()
33449 * or g_socket_listener_add_inet_port().
33451 * Returns: a new #GSocketService.
33457 * g_socket_service_start:
33458 * @service: a #GSocketService
33460 * Starts the service, i.e. start accepting connections
33461 * from the added sockets when the mainloop runs.
33463 * This call is thread-safe, so it may be called from a thread
33464 * handling an incoming client request.
33471 * g_socket_service_stop:
33472 * @service: a #GSocketService
33474 * Stops the service, i.e. stops accepting connections
33475 * from the added sockets when the mainloop runs.
33477 * This call is thread-safe, so it may be called from a thread
33478 * handling an incoming client request.
33480 * Note that this only stops accepting new connections; it does not
33481 * close the listening sockets, and you can call
33482 * g_socket_service_start() again later to begin listening again. To
33483 * close the listening sockets, call g_socket_listener_close(). (This
33484 * will happen automatically when the #GSocketService is finalized.)
33491 * g_socket_set_blocking:
33492 * @socket: a #GSocket.
33493 * @blocking: Whether to use blocking I/O or not.
33495 * Sets the blocking mode of the socket. In blocking mode
33496 * all operations block until they succeed or there is an error. In
33497 * non-blocking mode all functions return results immediately or
33498 * with a %G_IO_ERROR_WOULD_BLOCK error.
33500 * All sockets are created in blocking mode. However, note that the
33501 * platform level socket is always non-blocking, and blocking mode
33502 * is a GSocket level feature.
33509 * g_socket_set_broadcast:
33510 * @socket: a #GSocket.
33511 * @broadcast: whether @socket should allow sending to broadcast
33514 * Sets whether @socket should allow sending to broadcast addresses.
33515 * This is %FALSE by default.
33522 * g_socket_set_keepalive:
33523 * @socket: a #GSocket.
33524 * @keepalive: Value for the keepalive flag
33526 * Sets or unsets the %SO_KEEPALIVE flag on the underlying socket. When
33527 * this flag is set on a socket, the system will attempt to verify that the
33528 * remote socket endpoint is still present if a sufficiently long period of
33529 * time passes with no data being exchanged. If the system is unable to
33530 * verify the presence of the remote endpoint, it will automatically close
33533 * This option is only functional on certain kinds of sockets. (Notably,
33534 * %G_SOCKET_PROTOCOL_TCP sockets.)
33536 * The exact time between pings is system- and protocol-dependent, but will
33537 * normally be at least two hours. Most commonly, you would set this flag
33538 * on a server socket if you want to allow clients to remain idle for long
33539 * periods of time, but also want to ensure that connections are eventually
33540 * garbage-collected if clients crash or become unreachable.
33547 * g_socket_set_listen_backlog:
33548 * @socket: a #GSocket.
33549 * @backlog: the maximum number of pending connections.
33551 * Sets the maximum number of outstanding connections allowed
33552 * when listening on this socket. If more clients than this are
33553 * connecting to the socket and the application is not handling them
33554 * on time then the new connections will be refused.
33556 * Note that this must be called before g_socket_listen() and has no
33557 * effect if called after that.
33564 * g_socket_set_multicast_loopback:
33565 * @socket: a #GSocket.
33566 * @loopback: whether @socket should receive messages sent to its
33567 * multicast groups from the local host
33569 * Sets whether outgoing multicast packets will be received by sockets
33570 * listening on that multicast address on the same host. This is %TRUE
33578 * g_socket_set_multicast_ttl:
33579 * @socket: a #GSocket.
33580 * @ttl: the time-to-live value for all multicast datagrams on @socket
33582 * Sets the time-to-live for outgoing multicast datagrams on @socket.
33583 * By default, this is 1, meaning that multicast packets will not leave
33584 * the local network.
33591 * g_socket_set_option:
33592 * @socket: a #GSocket
33593 * @level: the "API level" of the option (eg, `SOL_SOCKET`)
33594 * @optname: the "name" of the option (eg, `SO_BROADCAST`)
33595 * @value: the value to set the option to
33596 * @error: #GError for error reporting, or %NULL to ignore.
33598 * Sets the value of an integer-valued option on @socket, as with
33599 * setsockopt(). (If you need to set a non-integer-valued option,
33600 * you will need to call setsockopt() directly.)
33602 * The [<gio/gnetworking.h>][gio-gnetworking.h]
33603 * header pulls in system headers that will define most of the
33604 * standard/portable socket options. For unusual socket protocols or
33605 * platform-dependent options, you may need to include additional
33608 * Returns: success or failure. On failure, @error will be set, and
33609 * the system error value (`errno` or WSAGetLastError()) will still
33610 * be set to the result of the setsockopt() call.
33616 * g_socket_set_timeout:
33617 * @socket: a #GSocket.
33618 * @timeout: the timeout for @socket, in seconds, or 0 for none
33620 * Sets the time in seconds after which I/O operations on @socket will
33621 * time out if they have not yet completed.
33623 * On a blocking socket, this means that any blocking #GSocket
33624 * operation will time out after @timeout seconds of inactivity,
33625 * returning %G_IO_ERROR_TIMED_OUT.
33627 * On a non-blocking socket, calls to g_socket_condition_wait() will
33628 * also fail with %G_IO_ERROR_TIMED_OUT after the given time. Sources
33629 * created with g_socket_create_source() will trigger after
33630 * @timeout seconds of inactivity, with the requested condition
33631 * set, at which point calling g_socket_receive(), g_socket_send(),
33632 * g_socket_check_connect_result(), etc, will fail with
33633 * %G_IO_ERROR_TIMED_OUT.
33635 * If @timeout is 0 (the default), operations will never time out
33638 * Note that if an I/O operation is interrupted by a signal, this may
33639 * cause the timeout to be reset.
33646 * g_socket_set_ttl:
33647 * @socket: a #GSocket.
33648 * @ttl: the time-to-live value for all unicast packets on @socket
33650 * Sets the time-to-live for outgoing unicast packets on @socket.
33651 * By default the platform-specific default value is used.
33658 * g_socket_shutdown:
33659 * @socket: a #GSocket
33660 * @shutdown_read: whether to shut down the read side
33661 * @shutdown_write: whether to shut down the write side
33662 * @error: #GError for error reporting, or %NULL to ignore.
33664 * Shut down part of a full-duplex connection.
33666 * If @shutdown_read is %TRUE then the receiving side of the connection
33667 * is shut down, and further reading is disallowed.
33669 * If @shutdown_write is %TRUE then the sending side of the connection
33670 * is shut down, and further writing is disallowed.
33672 * It is allowed for both @shutdown_read and @shutdown_write to be %TRUE.
33674 * One example where this is used is graceful disconnect for TCP connections
33675 * where you close the sending side, then wait for the other side to close
33676 * the connection, thus ensuring that the other side saw all sent data.
33678 * Returns: %TRUE on success, %FALSE on error
33684 * g_socket_speaks_ipv4:
33685 * @socket: a #GSocket
33687 * Checks if a socket is capable of speaking IPv4.
33689 * IPv4 sockets are capable of speaking IPv4. On some operating systems
33690 * and under some combinations of circumstances IPv6 sockets are also
33691 * capable of speaking IPv4. See RFC 3493 section 3.7 for more
33694 * No other types of sockets are currently considered as being capable
33695 * of speaking IPv4.
33697 * Returns: %TRUE if this socket can be used with IPv4.
33703 * g_srv_target_copy:
33704 * @target: a #GSrvTarget
33708 * Returns: a copy of @target
33714 * g_srv_target_free:
33715 * @target: a #GSrvTarget
33724 * g_srv_target_get_hostname:
33725 * @target: a #GSrvTarget
33727 * Gets @target's hostname (in ASCII form; if you are going to present
33728 * this to the user, you should use g_hostname_is_ascii_encoded() to
33729 * check if it contains encoded Unicode segments, and use
33730 * g_hostname_to_unicode() to convert it if it does.)
33732 * Returns: @target's hostname
33738 * g_srv_target_get_port:
33739 * @target: a #GSrvTarget
33741 * Gets @target's port
33743 * Returns: @target's port
33749 * g_srv_target_get_priority:
33750 * @target: a #GSrvTarget
33752 * Gets @target's priority. You should not need to look at this;
33753 * #GResolver already sorts the targets according to the algorithm in
33756 * Returns: @target's priority
33762 * g_srv_target_get_weight:
33763 * @target: a #GSrvTarget
33765 * Gets @target's weight. You should not need to look at this;
33766 * #GResolver already sorts the targets according to the algorithm in
33769 * Returns: @target's weight
33775 * g_srv_target_list_sort: (skip)
33776 * @targets: a #GList of #GSrvTarget
33778 * Sorts @targets in place according to the algorithm in RFC 2782.
33780 * Returns: (transfer full): the head of the sorted list.
33786 * g_srv_target_new:
33787 * @hostname: the host that the service is running on
33788 * @port: the port that the service is running on
33789 * @priority: the target's priority
33790 * @weight: the target's weight
33792 * Creates a new #GSrvTarget with the given parameters.
33794 * You should not need to use this; normally #GSrvTargets are
33795 * created by #GResolver.
33797 * Returns: a new #GSrvTarget.
33803 * g_static_resource_fini:
33804 * @static_resource: pointer to a static #GStaticResource
33806 * Finalized a GResource initialized by g_static_resource_init().
33808 * This is normally used by code generated by
33809 * [glib-compile-resources][glib-compile-resources]
33810 * and is not typically used by other code.
33817 * g_static_resource_get_resource:
33818 * @static_resource: pointer to a static #GStaticResource
33820 * Gets the GResource that was registered by a call to g_static_resource_init().
33822 * This is normally used by code generated by
33823 * [glib-compile-resources][glib-compile-resources]
33824 * and is not typically used by other code.
33826 * Returns: (transfer none): a #GResource
33832 * g_static_resource_init:
33833 * @static_resource: pointer to a static #GStaticResource
33835 * Initializes a GResource from static data using a
33838 * This is normally used by code generated by
33839 * [glib-compile-resources][glib-compile-resources]
33840 * and is not typically used by other code.
33847 * g_subprocess_communicate:
33848 * @subprocess: a #GSubprocess
33849 * @stdin_buf: (allow-none): data to send to the stdin of the subprocess, or %NULL
33850 * @cancellable: a #GCancellable
33851 * @stdout_buf: (out): data read from the subprocess stdout
33852 * @stderr_buf: (out): data read from the subprocess stderr
33853 * @error: a pointer to a %NULL #GError pointer, or %NULL
33855 * Communicate with the subprocess until it terminates, and all input
33856 * and output has been completed.
33858 * If @stdin_buf is given, the subprocess must have been created with
33859 * %G_SUBPROCESS_FLAGS_STDIN_PIPE. The given data is fed to the
33860 * stdin of the subprocess and the pipe is closed (ie: EOF).
33862 * At the same time (as not to cause blocking when dealing with large
33863 * amounts of data), if %G_SUBPROCESS_FLAGS_STDOUT_PIPE or
33864 * %G_SUBPROCESS_FLAGS_STDERR_PIPE were used, reads from those
33865 * streams. The data that was read is returned in @stdout and/or
33868 * If the subprocess was created with %G_SUBPROCESS_FLAGS_STDOUT_PIPE,
33869 * @stdout_buf will contain the data read from stdout. Otherwise, for
33870 * subprocesses not created with %G_SUBPROCESS_FLAGS_STDOUT_PIPE,
33871 * @stdout_buf will be set to %NULL. Similar provisions apply to
33872 * @stderr_buf and %G_SUBPROCESS_FLAGS_STDERR_PIPE.
33874 * As usual, any output variable may be given as %NULL to ignore it.
33876 * If you desire the stdout and stderr data to be interleaved, create
33877 * the subprocess with %G_SUBPROCESS_FLAGS_STDOUT_PIPE and
33878 * %G_SUBPROCESS_FLAGS_STDERR_MERGE. The merged result will be returned
33879 * in @stdout_buf and @stderr_buf will be set to %NULL.
33881 * In case of any error (including cancellation), %FALSE will be
33882 * returned with @error set. Some or all of the stdin data may have
33883 * been written. Any stdout or stderr data that has been read will be
33884 * discarded. None of the out variables (aside from @error) will have
33885 * been set to anything in particular and should not be inspected.
33887 * In the case that %TRUE is returned, the subprocess has exited and the
33888 * exit status inspection APIs (eg: g_subprocess_get_if_exited(),
33889 * g_subprocess_get_exit_status()) may be used.
33891 * You should not attempt to use any of the subprocess pipes after
33892 * starting this function, since they may be left in strange states,
33893 * even if the operation was cancelled. You should especially not
33894 * attempt to interact with the pipes while the operation is in progress
33895 * (either from another thread or if using the asynchronous version).
33897 * Returns: %TRUE if successful
33903 * g_subprocess_communicate_async:
33904 * @subprocess: Self
33905 * @stdin_buf: (allow-none): Input data, or %NULL
33906 * @cancellable: (allow-none): Cancellable
33907 * @callback: Callback
33908 * @user_data: User data
33910 * Asynchronous version of g_subprocess_communicate(). Complete
33911 * invocation with g_subprocess_communicate_finish().
33916 * g_subprocess_communicate_finish:
33917 * @subprocess: Self
33919 * @stdout_buf: (out): Return location for stdout data
33920 * @stderr_buf: (out): Return location for stderr data
33923 * Complete an invocation of g_subprocess_communicate_async().
33928 * g_subprocess_communicate_utf8:
33929 * @subprocess: a #GSubprocess
33930 * @stdin_buf: (allow-none): data to send to the stdin of the subprocess, or %NULL
33931 * @cancellable: a #GCancellable
33932 * @stdout_buf: (out): data read from the subprocess stdout
33933 * @stderr_buf: (out): data read from the subprocess stderr
33934 * @error: a pointer to a %NULL #GError pointer, or %NULL
33936 * Like g_subprocess_communicate(), but validates the output of the
33937 * process as UTF-8, and returns it as a regular NUL terminated string.
33942 * g_subprocess_communicate_utf8_async:
33943 * @subprocess: Self
33944 * @stdin_buf: (allow-none): Input data, or %NULL
33945 * @cancellable: Cancellable
33946 * @callback: Callback
33947 * @user_data: User data
33949 * Asynchronous version of g_subprocess_communicate_utf8(). Complete
33950 * invocation with g_subprocess_communicate_utf8_finish().
33955 * g_subprocess_communicate_utf8_finish:
33956 * @subprocess: Self
33958 * @stdout_buf: (out): Return location for stdout data
33959 * @stderr_buf: (out): Return location for stderr data
33962 * Complete an invocation of g_subprocess_communicate_utf8_async().
33967 * g_subprocess_force_exit:
33968 * @subprocess: a #GSubprocess
33970 * Use an operating-system specific method to attempt an immediate,
33971 * forceful termination of the process. There is no mechanism to
33972 * determine whether or not the request itself was successful;
33973 * however, you can use g_subprocess_wait() to monitor the status of
33974 * the process after calling this function.
33976 * On Unix, this function sends %SIGKILL.
33983 * g_subprocess_get_exit_status:
33984 * @subprocess: a #GSubprocess
33986 * Check the exit status of the subprocess, given that it exited
33987 * normally. This is the value passed to the exit() system call or the
33988 * return value from main.
33990 * This is equivalent to the system WEXITSTATUS macro.
33992 * It is an error to call this function before g_subprocess_wait() and
33993 * unless g_subprocess_get_if_exited() returned %TRUE.
33995 * Returns: the exit status
34001 * g_subprocess_get_identifier:
34002 * @subprocess: a #GSubprocess
34004 * On UNIX, returns the process ID as a decimal string.
34005 * On Windows, returns the result of GetProcessId() also as a string.
34010 * g_subprocess_get_if_exited:
34011 * @subprocess: a #GSubprocess
34013 * Check if the given subprocess exited normally (ie: by way of exit()
34014 * or return from main()).
34016 * This is equivalent to the system WIFEXITED macro.
34018 * It is an error to call this function before g_subprocess_wait() has
34021 * Returns: %TRUE if the case of a normal exit
34027 * g_subprocess_get_if_signaled:
34028 * @subprocess: a #GSubprocess
34030 * Check if the given subprocess terminated in response to a signal.
34032 * This is equivalent to the system WIFSIGNALED macro.
34034 * It is an error to call this function before g_subprocess_wait() has
34037 * Returns: %TRUE if the case of termination due to a signal
34043 * g_subprocess_get_status:
34044 * @subprocess: a #GSubprocess
34046 * Gets the raw status code of the process, as from waitpid().
34048 * This value has no particular meaning, but it can be used with the
34049 * macros defined by the system headers such as WIFEXITED. It can also
34050 * be used with g_spawn_check_exit_status().
34052 * It is more likely that you want to use g_subprocess_get_if_exited()
34053 * followed by g_subprocess_get_exit_status().
34055 * It is an error to call this function before g_subprocess_wait() has
34058 * Returns: the (meaningless) waitpid() exit status from the kernel
34064 * g_subprocess_get_stderr_pipe:
34065 * @subprocess: a #GSubprocess
34067 * Gets the #GInputStream from which to read the stderr output of
34070 * The process must have been created with
34071 * %G_SUBPROCESS_FLAGS_STDERR_PIPE.
34073 * Returns: (transfer none): the stderr pipe
34079 * g_subprocess_get_stdin_pipe:
34080 * @subprocess: a #GSubprocess
34082 * Gets the #GOutputStream that you can write to in order to give data
34083 * to the stdin of @subprocess.
34085 * The process must have been created with
34086 * %G_SUBPROCESS_FLAGS_STDIN_PIPE.
34088 * Returns: (transfer none): the stdout pipe
34094 * g_subprocess_get_stdout_pipe:
34095 * @subprocess: a #GSubprocess
34097 * Gets the #GInputStream from which to read the stdout output of
34100 * The process must have been created with
34101 * %G_SUBPROCESS_FLAGS_STDOUT_PIPE.
34103 * Returns: (transfer none): the stdout pipe
34109 * g_subprocess_get_successful:
34110 * @subprocess: a #GSubprocess
34112 * Checks if the process was "successful". A process is considered
34113 * successful if it exited cleanly with an exit status of 0, either by
34114 * way of the exit() system call or return from main().
34116 * It is an error to call this function before g_subprocess_wait() has
34119 * Returns: %TRUE if the process exited cleanly with a exit status of 0
34125 * g_subprocess_get_term_sig:
34126 * @subprocess: a #GSubprocess
34128 * Get the signal number that caused the subprocess to terminate, given
34129 * that it terminated due to a signal.
34131 * This is equivalent to the system WTERMSIG macro.
34133 * It is an error to call this function before g_subprocess_wait() and
34134 * unless g_subprocess_get_if_signaled() returned %TRUE.
34136 * Returns: the signal causing termination
34142 * g_subprocess_launcher_getenv:
34143 * @self: a #GSubprocess
34144 * @variable: the environment variable to get
34146 * Returns the value of the environment variable @variable in the
34147 * environment of processes launched from this launcher.
34149 * The returned string is in the GLib file name encoding. On UNIX, this
34150 * means that it can be an arbitrary byte string. On Windows, it will
34153 * Returns: the value of the environment variable, %NULL if unset
34159 * g_subprocess_launcher_new:
34160 * @flags: #GSubprocessFlags
34162 * Creates a new #GSubprocessLauncher.
34164 * The launcher is created with the default options. A copy of the
34165 * environment of the calling process is made at the time of this call
34166 * and will be used as the environment that the process is launched in.
34173 * g_subprocess_launcher_set_child_setup:
34174 * @self: a #GSubprocessLauncher
34175 * @child_setup: a #GSpawnChildSetupFunc to use as the child setup function
34176 * @user_data: user data for @child_setup
34177 * @destroy_notify: a #GDestroyNotify for @user_data
34179 * Sets up a child setup function.
34181 * The child setup function will be called after fork() but before
34182 * exec() on the child's side.
34184 * @destroy_notify will not be automatically called on the child's side
34185 * of the fork(). It will only be called when the last reference on the
34186 * #GSubprocessLauncher is dropped or when a new child setup function is
34189 * %NULL can be given as @child_setup to disable the functionality.
34191 * Child setup functions are only available on UNIX.
34198 * g_subprocess_launcher_set_cwd:
34199 * @self: a #GSubprocess
34200 * @cwd: the cwd for launched processes
34202 * Sets the current working directory that processes will be launched
34205 * By default processes are launched with the current working directory
34206 * of the launching process at the time of launch.
34213 * g_subprocess_launcher_set_environ:
34214 * @self: a #GSubprocess
34215 * @env: the replacement environment
34217 * Replace the entire environment of processes launched from this
34218 * launcher with the given 'environ' variable.
34220 * Typically you will build this variable by using g_listenv() to copy
34221 * the process 'environ' and using the functions g_environ_setenv(),
34222 * g_environ_unsetenv(), etc.
34224 * As an alternative, you can use g_subprocess_launcher_setenv(),
34225 * g_subprocess_launcher_unsetenv(), etc.
34227 * All strings in this array are expected to be in the GLib file name
34228 * encoding. On UNIX, this means that they can be arbitrary byte
34229 * strings. On Windows, they should be in UTF-8.
34236 * g_subprocess_launcher_set_flags:
34237 * @self: a #GSubprocessLauncher
34238 * @flags: #GSubprocessFlags
34240 * Sets the flags on the launcher.
34242 * The default flags are %G_SUBPROCESS_FLAGS_NONE.
34244 * You may not set flags that specify conflicting options for how to
34245 * handle a particular stdio stream (eg: specifying both
34246 * %G_SUBPROCESS_FLAGS_STDIN_PIPE and
34247 * %G_SUBPROCESS_FLAGS_STDIN_INHERIT).
34249 * You may also not set a flag that conflicts with a previous call to a
34250 * function like g_subprocess_launcher_set_stdin_file_path() or
34251 * g_subprocess_launcher_take_stdout_fd().
34258 * g_subprocess_launcher_set_stderr_file_path:
34259 * @self: a #GSubprocessLauncher
34260 * @path: a filename or %NULL
34262 * Sets the file path to use as the stderr for spawned processes.
34264 * If @path is %NULL then any previously given path is unset.
34266 * The file will be created or truncated when the process is spawned, as
34267 * would be the case if using '2>' at the shell.
34269 * If you want to send both stdout and stderr to the same file then use
34270 * %G_SUBPROCESS_FLAGS_STDERR_MERGE.
34272 * You may not set a stderr file path if a stderr fd is already set or
34273 * if the launcher flags contain any flags directing stderr elsewhere.
34275 * This feature is only available on UNIX.
34282 * g_subprocess_launcher_set_stdin_file_path:
34283 * @self: a #GSubprocessLauncher
34284 * @path: a filename or %NULL
34286 * Sets the file path to use as the stdin for spawned processes.
34288 * If @path is %NULL then any previously given path is unset.
34290 * The file must exist or spawning the process will fail.
34292 * You may not set a stdin file path if a stdin fd is already set or if
34293 * the launcher flags contain any flags directing stdin elsewhere.
34295 * This feature is only available on UNIX.
34302 * g_subprocess_launcher_set_stdout_file_path:
34303 * @self: a #GSubprocessLauncher
34304 * @path: a filename or %NULL
34306 * Sets the file path to use as the stdout for spawned processes.
34308 * If @path is %NULL then any previously given path is unset.
34310 * The file will be created or truncated when the process is spawned, as
34311 * would be the case if using '>' at the shell.
34313 * You may not set a stdout file path if a stdout fd is already set or
34314 * if the launcher flags contain any flags directing stdout elsewhere.
34316 * This feature is only available on UNIX.
34323 * g_subprocess_launcher_setenv:
34324 * @self: a #GSubprocess
34325 * @variable: the environment variable to set, must not contain '='
34326 * @value: the new value for the variable
34327 * @overwrite: whether to change the variable if it already exists
34329 * Sets the environment variable @variable in the environment of
34330 * processes launched from this launcher.
34332 * Both the variable's name and value should be in the GLib file name
34333 * encoding. On UNIX, this means that they can be arbitrary byte
34334 * strings. On Windows, they should be in UTF-8.
34341 * g_subprocess_launcher_spawn:
34342 * @self: a #GSubprocessLauncher
34344 * @argv0: Command line arguments
34345 * @...: Continued arguments, %NULL terminated
34347 * Creates a #GSubprocess given a provided varargs list of arguments.
34350 * Returns: (transfer full): A new #GSubprocess, or %NULL on error (and @error will be set)
34355 * g_subprocess_launcher_spawnv:
34356 * @self: a #GSubprocessLauncher
34357 * @argv: (array zero-terminated=1) (element-type utf8): Command line arguments
34360 * Creates a #GSubprocess given a provided array of arguments.
34363 * Returns: (transfer full): A new #GSubprocess, or %NULL on error (and @error will be set)
34368 * g_subprocess_launcher_take_fd:
34369 * @self: a #GSubprocessLauncher
34370 * @source_fd: File descriptor in parent process
34371 * @target_fd: Target descriptor for child process
34373 * Transfer an arbitrary file descriptor from parent process to the
34374 * child. This function takes "ownership" of the fd; it will be closed
34375 * in the parent when @self is freed.
34377 * By default, all file descriptors from the parent will be closed.
34378 * This function allows you to create (for example) a custom pipe() or
34379 * socketpair() before launching the process, and choose the target
34380 * descriptor in the child.
34382 * An example use case is GNUPG, which has a command line argument
34383 * --passphrase-fd providing a file descriptor number where it expects
34384 * the passphrase to be written.
34389 * g_subprocess_launcher_take_stderr_fd:
34390 * @self: a #GSubprocessLauncher
34391 * @fd: a file descriptor, or -1
34393 * Sets the file descriptor to use as the stderr for spawned processes.
34395 * If @fd is -1 then any previously given fd is unset.
34397 * Note that the default behaviour is to pass stderr through to the
34398 * stderr of the parent process.
34400 * The passed @fd belongs to the #GSubprocessLauncher. It will be
34401 * automatically closed when the launcher is finalized. The file
34402 * descriptor will also be closed on the child side when executing the
34405 * You may not set a stderr fd if a stderr file path is already set or
34406 * if the launcher flags contain any flags directing stderr elsewhere.
34408 * This feature is only available on UNIX.
34415 * g_subprocess_launcher_take_stdin_fd:
34416 * @self: a #GSubprocessLauncher
34417 * @fd: a file descriptor, or -1
34419 * Sets the file descriptor to use as the stdin for spawned processes.
34421 * If @fd is -1 then any previously given fd is unset.
34423 * Note that if your intention is to have the stdin of the calling
34424 * process inherited by the child then %G_SUBPROCESS_FLAGS_STDIN_INHERIT
34425 * is a better way to go about doing that.
34427 * The passed @fd is noted but will not be touched in the current
34428 * process. It is therefore necessary that it be kept open by the
34429 * caller until the subprocess is spawned. The file descriptor will
34430 * also not be explicitly closed on the child side, so it must be marked
34431 * O_CLOEXEC if that's what you want.
34433 * You may not set a stdin fd if a stdin file path is already set or if
34434 * the launcher flags contain any flags directing stdin elsewhere.
34436 * This feature is only available on UNIX.
34443 * g_subprocess_launcher_take_stdout_fd:
34444 * @self: a #GSubprocessLauncher
34445 * @fd: a file descriptor, or -1
34447 * Sets the file descriptor to use as the stdout for spawned processes.
34449 * If @fd is -1 then any previously given fd is unset.
34451 * Note that the default behaviour is to pass stdout through to the
34452 * stdout of the parent process.
34454 * The passed @fd is noted but will not be touched in the current
34455 * process. It is therefore necessary that it be kept open by the
34456 * caller until the subprocess is spawned. The file descriptor will
34457 * also not be explicitly closed on the child side, so it must be marked
34458 * O_CLOEXEC if that's what you want.
34460 * You may not set a stdout fd if a stdout file path is already set or
34461 * if the launcher flags contain any flags directing stdout elsewhere.
34463 * This feature is only available on UNIX.
34470 * g_subprocess_launcher_unsetenv:
34471 * @self: a #GSubprocess
34472 * @variable: the environment variable to unset, must not contain '='
34474 * Removes the environment variable @variable from the environment of
34475 * processes launched from this launcher.
34477 * The variable name should be in the GLib file name encoding. On UNIX,
34478 * this means that they can be arbitrary byte strings. On Windows, they
34479 * should be in UTF-8.
34486 * g_subprocess_new: (skip)
34487 * @flags: flags that define the behaviour of the subprocess
34488 * @error: (allow-none): return location for an error, or %NULL
34489 * @argv0: first commandline argument to pass to the subprocess
34490 * @...: more commandline arguments, followed by %NULL
34492 * Create a new process with the given flags and varargs argument
34493 * list. By default, matching the g_spawn_async() defaults, the
34494 * child's stdin will be set to the system null device, and
34495 * stdout/stderr will be inherited from the parent. You can use
34496 * @flags to control this behavior.
34498 * The argument list must be terminated with %NULL.
34500 * Returns: A newly created #GSubprocess, or %NULL on error (and @error
34507 * g_subprocess_newv: (rename-to g_subprocess_new)
34508 * @argv: (array zero-terminated=1) (element-type utf8): commandline arguments for the subprocess
34509 * @flags: flags that define the behaviour of the subprocess
34510 * @error: (allow-none): return location for an error, or %NULL
34512 * Create a new process with the given flags and argument list.
34514 * The argument list is expected to be %NULL-terminated.
34516 * Returns: A newly created #GSubprocess, or %NULL on error (and @error
34523 * g_subprocess_send_signal:
34524 * @subprocess: a #GSubprocess
34525 * @signal_num: the signal number to send
34527 * Sends the UNIX signal @signal_num to the subprocess, if it is still
34530 * This API is race-free. If the subprocess has terminated, it will not
34533 * This API is not available on Windows.
34540 * g_subprocess_wait:
34541 * @subprocess: a #GSubprocess
34542 * @cancellable: a #GCancellable
34543 * @error: a #GError
34545 * Synchronously wait for the subprocess to terminate.
34547 * After the process terminates you can query its exit status with
34548 * functions such as g_subprocess_get_if_exited() and
34549 * g_subprocess_get_exit_status().
34551 * This function does not fail in the case of the subprocess having
34552 * abnormal termination. See g_subprocess_wait_check() for that.
34554 * Cancelling @cancellable doesn't kill the subprocess. Call
34555 * g_subprocess_force_exit() if it is desirable.
34557 * Returns: %TRUE on success, %FALSE if @cancellable was cancelled
34563 * g_subprocess_wait_async:
34564 * @subprocess: a #GSubprocess
34565 * @cancellable: a #GCancellable, or %NULL
34566 * @callback: a #GAsyncReadyCallback to call when the operation is complete
34567 * @user_data: user_data for @callback
34569 * Wait for the subprocess to terminate.
34571 * This is the asynchronous version of g_subprocess_wait().
34578 * g_subprocess_wait_check:
34579 * @subprocess: a #GSubprocess
34580 * @cancellable: a #GCancellable
34581 * @error: a #GError
34583 * Combines g_subprocess_wait() with g_spawn_check_exit_status().
34585 * Returns: %TRUE on success, %FALSE if process exited abnormally, or
34586 * @cancellable was cancelled
34592 * g_subprocess_wait_check_async:
34593 * @subprocess: a #GSubprocess
34594 * @cancellable: a #GCancellable, or %NULL
34595 * @callback: a #GAsyncReadyCallback to call when the operation is complete
34596 * @user_data: user_data for @callback
34598 * Combines g_subprocess_wait_async() with g_spawn_check_exit_status().
34600 * This is the asynchronous version of g_subprocess_wait_check().
34607 * g_subprocess_wait_check_finish:
34608 * @subprocess: a #GSubprocess
34609 * @result: the #GAsyncResult passed to your #GAsyncReadyCallback
34610 * @error: a pointer to a %NULL #GError, or %NULL
34612 * Collects the result of a previous call to
34613 * g_subprocess_wait_check_async().
34615 * Returns: %TRUE if successful, or %FALSE with @error set
34621 * g_subprocess_wait_finish:
34622 * @subprocess: a #GSubprocess
34623 * @result: the #GAsyncResult passed to your #GAsyncReadyCallback
34624 * @error: a pointer to a %NULL #GError, or %NULL
34626 * Collects the result of a previous call to
34627 * g_subprocess_wait_async().
34629 * Returns: %TRUE if successful, or %FALSE with @error set
34635 * g_task_attach_source:
34637 * @source: the source to attach
34638 * @callback: the callback to invoke when @source triggers
34640 * A utility function for dealing with async operations where you need
34641 * to wait for a #GSource to trigger. Attaches @source to @task's
34642 * #GMainContext with @task's [priority][io-priority], and sets @source's
34643 * callback to @callback, with @task as the callback's `user_data`.
34645 * This takes a reference on @task until @source is destroyed.
34652 * g_task_get_cancellable:
34655 * Gets @task's #GCancellable
34657 * Returns: (transfer none): @task's #GCancellable
34663 * g_task_get_check_cancellable:
34664 * @task: the #GTask
34666 * Gets @task's check-cancellable flag. See
34667 * g_task_set_check_cancellable() for more details.
34674 * g_task_get_context:
34677 * Gets the #GMainContext that @task will return its result in (that
34678 * is, the context that was the
34679 * [thread-default main context][g-main-context-push-thread-default]
34680 * at the point when @task was created).
34682 * This will always return a non-%NULL value, even if the task's
34683 * context is the default #GMainContext.
34685 * Returns: (transfer none): @task's #GMainContext
34691 * g_task_get_priority:
34694 * Gets @task's priority
34696 * Returns: @task's priority
34702 * g_task_get_return_on_cancel:
34703 * @task: the #GTask
34705 * Gets @task's return-on-cancel flag. See
34706 * g_task_set_return_on_cancel() for more details.
34713 * g_task_get_source_object:
34716 * Gets the source object from @task. Like
34717 * g_async_result_get_source_object(), but does not ref the object.
34719 * Returns: (transfer none) (type GObject): @task's source object, or %NULL
34725 * g_task_get_source_tag:
34728 * Gets @task's source tag. See g_task_set_source_tag().
34730 * Returns: (transfer none): @task's source tag
34736 * g_task_get_task_data:
34739 * Gets @task's `task_data`.
34741 * Returns: (transfer none): @task's `task_data`.
34747 * g_task_had_error:
34750 * Tests if @task resulted in an error.
34752 * Returns: %TRUE if the task resulted in an error, %FALSE otherwise.
34759 * @result: (type Gio.AsyncResult): A #GAsyncResult
34760 * @source_object: (allow-none) (type GObject): the source object
34761 * expected to be associated with the task
34763 * Checks that @result is a #GTask, and that @source_object is its
34764 * source object (or that @source_object is %NULL and @result has no
34765 * source object). This can be used in g_return_if_fail() checks.
34767 * Returns: %TRUE if @result and @source_object are valid, %FALSE
34775 * @source_object: (allow-none) (type GObject): the #GObject that owns
34776 * this task, or %NULL.
34777 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
34778 * @callback: (scope async): a #GAsyncReadyCallback.
34779 * @callback_data: (closure): user data passed to @callback.
34781 * Creates a #GTask acting on @source_object, which will eventually be
34782 * used to invoke @callback in the current
34783 * [thread-default main context][g-main-context-push-thread-default].
34785 * Call this in the "start" method of your asynchronous method, and
34786 * pass the #GTask around throughout the asynchronous operation. You
34787 * can use g_task_set_task_data() to attach task-specific data to the
34788 * object, which you can retrieve later via g_task_get_task_data().
34790 * By default, if @cancellable is cancelled, then the return value of
34791 * the task will always be %G_IO_ERROR_CANCELLED, even if the task had
34792 * already completed before the cancellation. This allows for
34793 * simplified handling in cases where cancellation may imply that
34794 * other objects that the task depends on have been destroyed. If you
34795 * do not want this behavior, you can use
34796 * g_task_set_check_cancellable() to change it.
34798 * Returns: a #GTask.
34804 * g_task_propagate_boolean:
34806 * @error: return location for a #GError
34808 * Gets the result of @task as a #gboolean.
34810 * If the task resulted in an error, or was cancelled, then this will
34811 * instead return %FALSE and set @error.
34813 * Since this method transfers ownership of the return value (or
34814 * error) to the caller, you may only call it once.
34816 * Returns: the task result, or %FALSE on error
34822 * g_task_propagate_int:
34824 * @error: return location for a #GError
34826 * Gets the result of @task as an integer (#gssize).
34828 * If the task resulted in an error, or was cancelled, then this will
34829 * instead return -1 and set @error.
34831 * Since this method transfers ownership of the return value (or
34832 * error) to the caller, you may only call it once.
34834 * Returns: the task result, or -1 on error
34840 * g_task_propagate_pointer:
34842 * @error: return location for a #GError
34844 * Gets the result of @task as a pointer, and transfers ownership
34845 * of that value to the caller.
34847 * If the task resulted in an error, or was cancelled, then this will
34848 * instead return %NULL and set @error.
34850 * Since this method transfers ownership of the return value (or
34851 * error) to the caller, you may only call it once.
34853 * Returns: (transfer full): the task result, or %NULL on error
34859 * g_task_report_error:
34860 * @source_object: (allow-none) (type GObject): the #GObject that owns
34861 * this task, or %NULL.
34862 * @callback: (scope async): a #GAsyncReadyCallback.
34863 * @callback_data: (closure): user data passed to @callback.
34864 * @source_tag: an opaque pointer indicating the source of this task
34865 * @error: (transfer full): error to report
34867 * Creates a #GTask and then immediately calls g_task_return_error()
34868 * on it. Use this in the wrapper function of an asynchronous method
34869 * when you want to avoid even calling the virtual method. You can
34870 * then use g_async_result_is_tagged() in the finish method wrapper to
34871 * check if the result there is tagged as having been created by the
34872 * wrapper method, and deal with it appropriately if so.
34874 * See also g_task_report_new_error().
34881 * g_task_report_new_error:
34882 * @source_object: (allow-none) (type GObject): the #GObject that owns
34883 * this task, or %NULL.
34884 * @callback: (scope async): a #GAsyncReadyCallback.
34885 * @callback_data: (closure): user data passed to @callback.
34886 * @source_tag: an opaque pointer indicating the source of this task
34887 * @domain: a #GQuark.
34888 * @code: an error code.
34889 * @format: a string with format characters.
34890 * @...: a list of values to insert into @format.
34892 * Creates a #GTask and then immediately calls
34893 * g_task_return_new_error() on it. Use this in the wrapper function
34894 * of an asynchronous method when you want to avoid even calling the
34895 * virtual method. You can then use g_async_result_is_tagged() in the
34896 * finish method wrapper to check if the result there is tagged as
34897 * having been created by the wrapper method, and deal with it
34898 * appropriately if so.
34900 * See also g_task_report_error().
34907 * g_task_return_boolean:
34909 * @result: the #gboolean result of a task function.
34911 * Sets @task's result to @result and completes the task (see
34912 * g_task_return_pointer() for more discussion of exactly what this
34920 * g_task_return_error:
34922 * @error: (transfer full): the #GError result of a task function.
34924 * Sets @task's result to @error (which @task assumes ownership of)
34925 * and completes the task (see g_task_return_pointer() for more
34926 * discussion of exactly what this means).
34928 * Note that since the task takes ownership of @error, and since the
34929 * task may be completed before returning from g_task_return_error(),
34930 * you cannot assume that @error is still valid after calling this.
34931 * Call g_error_copy() on the error if you need to keep a local copy
34934 * See also g_task_return_new_error().
34941 * g_task_return_error_if_cancelled:
34944 * Checks if @task's #GCancellable has been cancelled, and if so, sets
34945 * @task's error accordingly and completes the task (see
34946 * g_task_return_pointer() for more discussion of exactly what this
34949 * Returns: %TRUE if @task has been cancelled, %FALSE if not
34955 * g_task_return_int:
34957 * @result: the integer (#gssize) result of a task function.
34959 * Sets @task's result to @result and completes the task (see
34960 * g_task_return_pointer() for more discussion of exactly what this
34968 * g_task_return_new_error:
34970 * @domain: a #GQuark.
34971 * @code: an error code.
34972 * @format: a string with format characters.
34973 * @...: a list of values to insert into @format.
34975 * Sets @task's result to a new #GError created from @domain, @code,
34976 * @format, and the remaining arguments, and completes the task (see
34977 * g_task_return_pointer() for more discussion of exactly what this
34980 * See also g_task_return_error().
34987 * g_task_return_pointer:
34989 * @result: (allow-none) (transfer full): the pointer result of a task
34991 * @result_destroy: (allow-none): a #GDestroyNotify function.
34993 * Sets @task's result to @result and completes the task. If @result
34994 * is not %NULL, then @result_destroy will be used to free @result if
34995 * the caller does not take ownership of it with
34996 * g_task_propagate_pointer().
34998 * "Completes the task" means that for an ordinary asynchronous task
34999 * it will either invoke the task's callback, or else queue that
35000 * callback to be invoked in the proper #GMainContext, or in the next
35001 * iteration of the current #GMainContext. For a task run via
35002 * g_task_run_in_thread() or g_task_run_in_thread_sync(), calling this
35003 * method will save @result to be returned to the caller later, but
35004 * the task will not actually be completed until the #GTaskThreadFunc
35007 * Note that since the task may be completed before returning from
35008 * g_task_return_pointer(), you cannot assume that @result is still
35009 * valid after calling this, unless you are still holding another
35017 * g_task_run_in_thread:
35019 * @task_func: a #GTaskThreadFunc
35021 * Runs @task_func in another thread. When @task_func returns, @task's
35022 * #GAsyncReadyCallback will be invoked in @task's #GMainContext.
35024 * This takes a ref on @task until the task completes.
35026 * See #GTaskThreadFunc for more details about how @task_func is handled.
35033 * g_task_run_in_thread_sync:
35035 * @task_func: a #GTaskThreadFunc
35037 * Runs @task_func in another thread, and waits for it to return or be
35038 * cancelled. You can use g_task_propagate_pointer(), etc, afterward
35039 * to get the result of @task_func.
35041 * See #GTaskThreadFunc for more details about how @task_func is handled.
35043 * Normally this is used with tasks created with a %NULL
35044 * `callback`, but note that even if the task does
35045 * have a callback, it will not be invoked when @task_func returns.
35052 * g_task_set_check_cancellable:
35053 * @task: the #GTask
35054 * @check_cancellable: whether #GTask will check the state of
35055 * its #GCancellable for you.
35057 * Sets or clears @task's check-cancellable flag. If this is %TRUE
35058 * (the default), then g_task_propagate_pointer(), etc, and
35059 * g_task_had_error() will check the task's #GCancellable first, and
35060 * if it has been cancelled, then they will consider the task to have
35061 * returned an "Operation was cancelled" error
35062 * (%G_IO_ERROR_CANCELLED), regardless of any other error or return
35063 * value the task may have had.
35065 * If @check_cancellable is %FALSE, then the #GTask will not check the
35066 * cancellable itself, and it is up to @task's owner to do this (eg,
35067 * via g_task_return_error_if_cancelled()).
35069 * If you are using g_task_set_return_on_cancel() as well, then
35070 * you must leave check-cancellable set %TRUE.
35077 * g_task_set_priority:
35078 * @task: the #GTask
35079 * @priority: the [priority][io-priority] of the request
35081 * Sets @task's priority. If you do not call this, it will default to
35082 * %G_PRIORITY_DEFAULT.
35084 * This will affect the priority of #GSources created with
35085 * g_task_attach_source() and the scheduling of tasks run in threads,
35086 * and can also be explicitly retrieved later via
35087 * g_task_get_priority().
35094 * g_task_set_return_on_cancel:
35095 * @task: the #GTask
35096 * @return_on_cancel: whether the task returns automatically when
35099 * Sets or clears @task's return-on-cancel flag. This is only
35100 * meaningful for tasks run via g_task_run_in_thread() or
35101 * g_task_run_in_thread_sync().
35103 * If @return_on_cancel is %TRUE, then cancelling @task's
35104 * #GCancellable will immediately cause it to return, as though the
35105 * task's #GTaskThreadFunc had called
35106 * g_task_return_error_if_cancelled() and then returned.
35108 * This allows you to create a cancellable wrapper around an
35109 * uninterruptable function. The #GTaskThreadFunc just needs to be
35110 * careful that it does not modify any externally-visible state after
35111 * it has been cancelled. To do that, the thread should call
35112 * g_task_set_return_on_cancel() again to (atomically) set
35113 * return-on-cancel %FALSE before making externally-visible changes;
35114 * if the task gets cancelled before the return-on-cancel flag could
35115 * be changed, g_task_set_return_on_cancel() will indicate this by
35116 * returning %FALSE.
35118 * You can disable and re-enable this flag multiple times if you wish.
35119 * If the task's #GCancellable is cancelled while return-on-cancel is
35120 * %FALSE, then calling g_task_set_return_on_cancel() to set it %TRUE
35121 * again will cause the task to be cancelled at that point.
35123 * If the task's #GCancellable is already cancelled before you call
35124 * g_task_run_in_thread()/g_task_run_in_thread_sync(), then the
35125 * #GTaskThreadFunc will still be run (for consistency), but the task
35126 * will also be completed right away.
35128 * Returns: %TRUE if @task's return-on-cancel flag was changed to
35129 * match @return_on_cancel. %FALSE if @task has already been
35136 * g_task_set_source_tag:
35137 * @task: the #GTask
35138 * @source_tag: an opaque pointer indicating the source of this task
35140 * Sets @task's source tag. You can use this to tag a task return
35141 * value with a particular pointer (usually a pointer to the function
35142 * doing the tagging) and then later check it using
35143 * g_task_get_source_tag() (or g_async_result_is_tagged()) in the
35144 * task's "finish" function, to figure out if the response came from a
35145 * particular place.
35152 * g_task_set_task_data:
35153 * @task: the #GTask
35154 * @task_data: (allow-none): task-specific data
35155 * @task_data_destroy: (allow-none): #GDestroyNotify for @task_data
35157 * Sets @task's task data (freeing the existing task data, if any).
35164 * g_tcp_connection_get_graceful_disconnect:
35165 * @connection: a #GTcpConnection
35167 * Checks if graceful disconnects are used. See
35168 * g_tcp_connection_set_graceful_disconnect().
35170 * Returns: %TRUE if graceful disconnect is used on close, %FALSE otherwise
35176 * g_tcp_connection_set_graceful_disconnect:
35177 * @connection: a #GTcpConnection
35178 * @graceful_disconnect: Whether to do graceful disconnects or not
35180 * This enabled graceful disconnects on close. A graceful disconnect
35181 * means that we signal the receiving end that the connection is terminated
35182 * and wait for it to close the connection before closing the connection.
35184 * A graceful disconnect means that we can be sure that we successfully sent
35185 * all the outstanding data to the other end, or get an error reported.
35186 * However, it also means we have to wait for all the data to reach the
35187 * other side and for it to acknowledge this by closing the socket, which may
35188 * take a while. For this reason it is disabled by default.
35195 * g_tcp_wrapper_connection_get_base_io_stream:
35196 * @conn: a #GTcpWrapperConnection
35198 * Get's @conn's base #GIOStream
35200 * Returns: (transfer none): @conn's base #GIOStream
35205 * g_tcp_wrapper_connection_new:
35206 * @base_io_stream: the #GIOStream to wrap
35207 * @socket: the #GSocket associated with @base_io_stream
35209 * Wraps @base_io_stream and @socket together as a #GSocketConnection.
35211 * Returns: the new #GSocketConnection.
35217 * g_test_dbus_add_service_dir:
35218 * @self: a #GTestDBus
35219 * @path: path to a directory containing .service files
35221 * Add a path where dbus-daemon will look up .service files. This can't be
35222 * called after g_test_dbus_up().
35227 * g_test_dbus_down:
35228 * @self: a #GTestDBus
35230 * Stop the session bus started by g_test_dbus_up().
35232 * This will wait for the singleton returned by g_bus_get() or g_bus_get_sync()
35233 * is destroyed. This is done to ensure that the next unit test won't get a
35234 * leaked singleton from this test.
35239 * g_test_dbus_get_bus_address:
35240 * @self: a #GTestDBus
35242 * Get the address on which dbus-daemon is running. If g_test_dbus_up() has not
35243 * been called yet, %NULL is returned. This can be used with
35244 * g_dbus_connection_new_for_address().
35246 * Returns: (allow-none): the address of the bus, or %NULL.
35251 * g_test_dbus_get_flags:
35252 * @self: a #GTestDBus
35254 * Get the flags of the #GTestDBus object.
35256 * Returns: the value of #GTestDBus:flags property
35262 * @flags: a #GTestDBusFlags
35264 * Create a new #GTestDBus object.
35266 * Returns: (transfer full): a new #GTestDBus.
35271 * g_test_dbus_stop:
35272 * @self: a #GTestDBus
35274 * Stop the session bus started by g_test_dbus_up().
35276 * Unlike g_test_dbus_down(), this won't verify the #GDBusConnection
35277 * singleton returned by g_bus_get() or g_bus_get_sync() is destroyed. Unit
35278 * tests wanting to verify behaviour after the session bus has been stopped
35279 * can use this function but should still call g_test_dbus_down() when done.
35284 * g_test_dbus_unset:
35286 * Unset DISPLAY and DBUS_SESSION_BUS_ADDRESS env variables to ensure the test
35287 * won't use user's session bus.
35289 * This is useful for unit tests that want to verify behaviour when no session
35290 * bus is running. It is not necessary to call this if unit test already calls
35291 * g_test_dbus_up() before acquiring the session bus.
35297 * @self: a #GTestDBus
35299 * Start a dbus-daemon instance and set DBUS_SESSION_BUS_ADDRESS. After this
35300 * call, it is safe for unit tests to start sending messages on the session bus.
35302 * If this function is called from setup callback of g_test_add(),
35303 * g_test_dbus_down() must be called in its teardown callback.
35305 * If this function is called from unit test's main(), then g_test_dbus_down()
35306 * must be called after g_test_run().
35311 * g_themed_icon_append_name:
35312 * @icon: a #GThemedIcon
35313 * @iconname: name of icon to append to list of icons from within @icon.
35315 * Append a name to the list of icons from within @icon.
35317 * Note that doing so invalidates the hash computed by prior calls
35318 * to g_icon_hash().
35323 * g_themed_icon_get_names:
35324 * @icon: a #GThemedIcon.
35326 * Gets the names of icons from within @icon.
35328 * Returns: (transfer none): a list of icon names.
35333 * g_themed_icon_new:
35334 * @iconname: a string containing an icon name.
35336 * Creates a new themed icon for @iconname.
35338 * Returns: (transfer full) (type GThemedIcon): a new #GThemedIcon.
35343 * g_themed_icon_new_from_names:
35344 * @iconnames: (array length=len): an array of strings containing icon names.
35345 * @len: the length of the @iconnames array, or -1 if @iconnames is
35348 * Creates a new themed icon for @iconnames.
35350 * Returns: (transfer full) (type GThemedIcon): a new #GThemedIcon
35355 * g_themed_icon_new_with_default_fallbacks:
35356 * @iconname: a string containing an icon name
35358 * Creates a new themed icon for @iconname, and all the names
35359 * that can be created by shortening @iconname at '-' characters.
35361 * In the following example, @icon1 and @icon2 are equivalent:
35362 * |[<!-- language="C" -->
35363 * const char *names[] = {
35364 * "gnome-dev-cdrom-audio",
35365 * "gnome-dev-cdrom",
35370 * icon1 = g_themed_icon_new_from_names (names, 4);
35371 * icon2 = g_themed_icon_new_with_default_fallbacks ("gnome-dev-cdrom-audio");
35374 * Returns: (transfer full) (type GThemedIcon): a new #GThemedIcon.
35379 * g_themed_icon_prepend_name:
35380 * @icon: a #GThemedIcon
35381 * @iconname: name of icon to prepend to list of icons from within @icon.
35383 * Prepend a name to the list of icons from within @icon.
35385 * Note that doing so invalidates the hash computed by prior calls
35386 * to g_icon_hash().
35393 * g_threaded_socket_service_new:
35394 * @max_threads: the maximal number of threads to execute concurrently
35395 * handling incoming clients, -1 means no limit
35397 * Creates a new #GThreadedSocketService with no listeners. Listeners
35398 * must be added with one of the #GSocketListener "add" methods.
35400 * Returns: a new #GSocketService.
35406 * g_tls_backend_get_certificate_type:
35407 * @backend: the #GTlsBackend
35409 * Gets the #GType of @backend's #GTlsCertificate implementation.
35411 * Returns: the #GType of @backend's #GTlsCertificate
35418 * g_tls_backend_get_client_connection_type:
35419 * @backend: the #GTlsBackend
35421 * Gets the #GType of @backend's #GTlsClientConnection implementation.
35423 * Returns: the #GType of @backend's #GTlsClientConnection
35430 * g_tls_backend_get_default:
35432 * Gets the default #GTlsBackend for the system.
35434 * Returns: (transfer none): a #GTlsBackend
35440 * g_tls_backend_get_default_database:
35441 * @backend: the #GTlsBackend
35443 * Gets the default #GTlsDatabase used to verify TLS connections.
35445 * Returns: (transfer full): the default database, which should be
35446 * unreffed when done.
35452 * g_tls_backend_get_file_database_type:
35453 * @backend: the #GTlsBackend
35455 * Gets the #GType of @backend's #GTlsFileDatabase implementation.
35457 * Returns: the #GType of backend's #GTlsFileDatabase implementation.
35463 * g_tls_backend_get_server_connection_type:
35464 * @backend: the #GTlsBackend
35466 * Gets the #GType of @backend's #GTlsServerConnection implementation.
35468 * Returns: the #GType of @backend's #GTlsServerConnection
35475 * g_tls_backend_supports_tls:
35476 * @backend: the #GTlsBackend
35478 * Checks if TLS is supported; if this returns %FALSE for the default
35479 * #GTlsBackend, it means no "real" TLS backend is available.
35481 * Returns: whether or not TLS is supported
35487 * g_tls_certificate_get_issuer:
35488 * @cert: a #GTlsCertificate
35490 * Gets the #GTlsCertificate representing @cert's issuer, if known
35492 * Returns: (transfer none): The certificate of @cert's issuer,
35493 * or %NULL if @cert is self-signed or signed with an unknown
35500 * g_tls_certificate_is_same:
35501 * @cert_one: first certificate to compare
35502 * @cert_two: second certificate to compare
35504 * Check if two #GTlsCertificate objects represent the same certificate.
35505 * The raw DER byte data of the two certificates are checked for equality.
35506 * This has the effect that two certificates may compare equal even if
35507 * their #GTlsCertificate:issuer, #GTlsCertificate:private-key, or
35508 * #GTlsCertificate:private-key-pem properties differ.
35510 * Returns: whether the same or not
35516 * g_tls_certificate_list_new_from_file:
35517 * @file: file containing PEM-encoded certificates to import
35518 * @error: #GError for error reporting, or %NULL to ignore.
35520 * Creates one or more #GTlsCertificates from the PEM-encoded
35521 * data in @file. If @file cannot be read or parsed, the function will
35522 * return %NULL and set @error. If @file does not contain any
35523 * PEM-encoded certificates, this will return an empty list and not
35526 * Returns: (element-type Gio.TlsCertificate) (transfer full): a
35527 * #GList containing #GTlsCertificate objects. You must free the list
35528 * and its contents when you are done with it.
35534 * g_tls_certificate_new_from_file:
35535 * @file: file containing a PEM-encoded certificate to import
35536 * @error: #GError for error reporting, or %NULL to ignore.
35538 * Creates a #GTlsCertificate from the PEM-encoded data in @file. If
35539 * @file cannot be read or parsed, the function will return %NULL and
35540 * set @error. Otherwise, this behaves like
35541 * g_tls_certificate_new_from_pem().
35543 * Returns: the new certificate, or %NULL on error
35549 * g_tls_certificate_new_from_files:
35550 * @cert_file: file containing a PEM-encoded certificate to import
35551 * @key_file: file containing a PEM-encoded private key to import
35552 * @error: #GError for error reporting, or %NULL to ignore.
35554 * Creates a #GTlsCertificate from the PEM-encoded data in @cert_file
35555 * and @key_file. If either file cannot be read or parsed, the
35556 * function will return %NULL and set @error. Otherwise, this behaves
35557 * like g_tls_certificate_new_from_pem().
35559 * Returns: the new certificate, or %NULL on error
35565 * g_tls_certificate_new_from_pem:
35566 * @data: PEM-encoded certificate data
35567 * @length: the length of @data, or -1 if it's 0-terminated.
35568 * @error: #GError for error reporting, or %NULL to ignore.
35570 * Creates a new #GTlsCertificate from the PEM-encoded data in @data.
35571 * If @data includes both a certificate and a private key, then the
35572 * returned certificate will include the private key data as well. (See
35573 * the #GTlsCertificate:private-key-pem property for information about
35574 * supported formats.)
35576 * If @data includes multiple certificates, only the first one will be
35579 * Returns: the new certificate, or %NULL if @data is invalid
35585 * g_tls_certificate_verify:
35586 * @cert: a #GTlsCertificate
35587 * @identity: (allow-none): the expected peer identity
35588 * @trusted_ca: (allow-none): the certificate of a trusted authority
35590 * This verifies @cert and returns a set of #GTlsCertificateFlags
35591 * indicating any problems found with it. This can be used to verify a
35592 * certificate outside the context of making a connection, or to
35593 * check a certificate against a CA that is not part of the system
35596 * If @identity is not %NULL, @cert's name(s) will be compared against
35597 * it, and %G_TLS_CERTIFICATE_BAD_IDENTITY will be set in the return
35598 * value if it does not match. If @identity is %NULL, that bit will
35599 * never be set in the return value.
35601 * If @trusted_ca is not %NULL, then @cert (or one of the certificates
35602 * in its chain) must be signed by it, or else
35603 * %G_TLS_CERTIFICATE_UNKNOWN_CA will be set in the return value. If
35604 * @trusted_ca is %NULL, that bit will never be set in the return
35607 * (All other #GTlsCertificateFlags values will always be set or unset
35610 * Returns: the appropriate #GTlsCertificateFlags
35616 * g_tls_client_connection_get_accepted_cas:
35617 * @conn: the #GTlsClientConnection
35619 * Gets the list of distinguished names of the Certificate Authorities
35620 * that the server will accept certificates from. This will be set
35621 * during the TLS handshake if the server requests a certificate.
35622 * Otherwise, it will be %NULL.
35624 * Each item in the list is a #GByteArray which contains the complete
35625 * subject DN of the certificate authority.
35627 * Returns: (element-type GByteArray) (transfer full): the list of
35628 * CA DNs. You should unref each element with g_byte_array_unref() and then
35629 * the free the list with g_list_free().
35635 * g_tls_client_connection_get_server_identity:
35636 * @conn: the #GTlsClientConnection
35638 * Gets @conn's expected server identity
35640 * Returns: (transfer none): a #GSocketConnectable describing the
35641 * expected server identity, or %NULL if the expected identity is not
35648 * g_tls_client_connection_get_use_ssl3:
35649 * @conn: the #GTlsClientConnection
35651 * Gets whether @conn will use SSL 3.0 rather than the
35652 * highest-supported version of TLS; see
35653 * g_tls_client_connection_set_use_ssl3().
35655 * Returns: whether @conn will use SSL 3.0
35661 * g_tls_client_connection_get_validation_flags:
35662 * @conn: the #GTlsClientConnection
35664 * Gets @conn's validation flags
35666 * Returns: the validation flags
35672 * g_tls_client_connection_new:
35673 * @base_io_stream: the #GIOStream to wrap
35674 * @server_identity: (allow-none): the expected identity of the server
35675 * @error: #GError for error reporting, or %NULL to ignore.
35677 * Creates a new #GTlsClientConnection wrapping @base_io_stream (which
35678 * must have pollable input and output streams) which is assumed to
35679 * communicate with the server identified by @server_identity.
35681 * Returns: (transfer full) (type GTlsClientConnection): the new
35682 * #GTlsClientConnection, or %NULL on error
35688 * g_tls_client_connection_set_server_identity:
35689 * @conn: the #GTlsClientConnection
35690 * @identity: a #GSocketConnectable describing the expected server identity
35692 * Sets @conn's expected server identity, which is used both to tell
35693 * servers on virtual hosts which certificate to present, and also
35694 * to let @conn know what name to look for in the certificate when
35695 * performing %G_TLS_CERTIFICATE_BAD_IDENTITY validation, if enabled.
35702 * g_tls_client_connection_set_use_ssl3:
35703 * @conn: the #GTlsClientConnection
35704 * @use_ssl3: whether to use SSL 3.0
35706 * If @use_ssl3 is %TRUE, this forces @conn to use SSL 3.0 rather than
35707 * trying to properly negotiate the right version of TLS or SSL to use.
35708 * This can be used when talking to servers that do not implement the
35709 * fallbacks correctly and which will therefore fail to handshake with
35710 * a "modern" TLS handshake attempt.
35717 * g_tls_client_connection_set_validation_flags:
35718 * @conn: the #GTlsClientConnection
35719 * @flags: the #GTlsCertificateFlags to use
35721 * Sets @conn's validation flags, to override the default set of
35722 * checks performed when validating a server certificate. By default,
35723 * %G_TLS_CERTIFICATE_VALIDATE_ALL is used.
35730 * g_tls_connection_emit_accept_certificate:
35731 * @conn: a #GTlsConnection
35732 * @peer_cert: the peer's #GTlsCertificate
35733 * @errors: the problems with @peer_cert
35735 * Used by #GTlsConnection implementations to emit the
35736 * #GTlsConnection::accept-certificate signal.
35738 * Returns: %TRUE if one of the signal handlers has returned
35739 * %TRUE to accept @peer_cert
35745 * g_tls_connection_get_certificate:
35746 * @conn: a #GTlsConnection
35748 * Gets @conn's certificate, as set by
35749 * g_tls_connection_set_certificate().
35751 * Returns: (transfer none): @conn's certificate, or %NULL
35757 * g_tls_connection_get_database:
35758 * @conn: a #GTlsConnection
35760 * Gets the certificate database that @conn uses to verify
35761 * peer certificates. See g_tls_connection_set_database().
35763 * Returns: (transfer none): the certificate database that @conn uses or %NULL
35769 * g_tls_connection_get_interaction:
35770 * @conn: a connection
35772 * Get the object that will be used to interact with the user. It will be used
35773 * for things like prompting the user for passwords. If %NULL is returned, then
35774 * no user interaction will occur for this connection.
35776 * Returns: (transfer none): The interaction object.
35782 * g_tls_connection_get_peer_certificate:
35783 * @conn: a #GTlsConnection
35785 * Gets @conn's peer's certificate after the handshake has completed.
35786 * (It is not set during the emission of
35787 * #GTlsConnection::accept-certificate.)
35789 * Returns: (transfer none): @conn's peer's certificate, or %NULL
35795 * g_tls_connection_get_peer_certificate_errors:
35796 * @conn: a #GTlsConnection
35798 * Gets the errors associated with validating @conn's peer's
35799 * certificate, after the handshake has completed. (It is not set
35800 * during the emission of #GTlsConnection::accept-certificate.)
35802 * Returns: @conn's peer's certificate errors
35808 * g_tls_connection_get_rehandshake_mode:
35809 * @conn: a #GTlsConnection
35811 * Gets @conn rehandshaking mode. See
35812 * g_tls_connection_set_rehandshake_mode() for details.
35814 * Returns: @conn's rehandshaking mode
35820 * g_tls_connection_get_require_close_notify:
35821 * @conn: a #GTlsConnection
35823 * Tests whether or not @conn expects a proper TLS close notification
35824 * when the connection is closed. See
35825 * g_tls_connection_set_require_close_notify() for details.
35827 * Returns: %TRUE if @conn requires a proper TLS close
35834 * g_tls_connection_get_use_system_certdb:
35835 * @conn: a #GTlsConnection
35837 * Gets whether @conn uses the system certificate database to verify
35838 * peer certificates. See g_tls_connection_set_use_system_certdb().
35840 * Returns: whether @conn uses the system certificate database
35841 * Deprecated: 2.30: Use g_tls_connection_get_database() instead
35846 * g_tls_connection_handshake:
35847 * @conn: a #GTlsConnection
35848 * @cancellable: (allow-none): a #GCancellable, or %NULL
35849 * @error: a #GError, or %NULL
35851 * Attempts a TLS handshake on @conn.
35853 * On the client side, it is never necessary to call this method;
35854 * although the connection needs to perform a handshake after
35855 * connecting (or after sending a "STARTTLS"-type command) and may
35856 * need to rehandshake later if the server requests it,
35857 * #GTlsConnection will handle this for you automatically when you try
35858 * to send or receive data on the connection. However, you can call
35859 * g_tls_connection_handshake() manually if you want to know for sure
35860 * whether the initial handshake succeeded or failed (as opposed to
35861 * just immediately trying to write to @conn's output stream, in which
35862 * case if it fails, it may not be possible to tell if it failed
35863 * before or after completing the handshake).
35865 * Likewise, on the server side, although a handshake is necessary at
35866 * the beginning of the communication, you do not need to call this
35867 * function explicitly unless you want clearer error reporting.
35868 * However, you may call g_tls_connection_handshake() later on to
35869 * renegotiate parameters (encryption methods, etc) with the client.
35871 * #GTlsConnection::accept_certificate may be emitted during the
35874 * Returns: success or failure
35880 * g_tls_connection_handshake_async:
35881 * @conn: a #GTlsConnection
35882 * @io_priority: the [I/O priority][io-priority] of the request
35883 * @cancellable: (allow-none): a #GCancellable, or %NULL
35884 * @callback: callback to call when the handshake is complete
35885 * @user_data: the data to pass to the callback function
35887 * Asynchronously performs a TLS handshake on @conn. See
35888 * g_tls_connection_handshake() for more information.
35895 * g_tls_connection_handshake_finish:
35896 * @conn: a #GTlsConnection
35897 * @result: a #GAsyncResult.
35898 * @error: a #GError pointer, or %NULL
35900 * Finish an asynchronous TLS handshake operation. See
35901 * g_tls_connection_handshake() for more information.
35903 * Returns: %TRUE on success, %FALSE on failure, in which
35904 * case @error will be set.
35910 * g_tls_connection_set_certificate:
35911 * @conn: a #GTlsConnection
35912 * @certificate: the certificate to use for @conn
35914 * This sets the certificate that @conn will present to its peer
35915 * during the TLS handshake. For a #GTlsServerConnection, it is
35916 * mandatory to set this, and that will normally be done at construct
35919 * For a #GTlsClientConnection, this is optional. If a handshake fails
35920 * with %G_TLS_ERROR_CERTIFICATE_REQUIRED, that means that the server
35921 * requires a certificate, and if you try connecting again, you should
35922 * call this method first. You can call
35923 * g_tls_client_connection_get_accepted_cas() on the failed connection
35924 * to get a list of Certificate Authorities that the server will
35925 * accept certificates from.
35927 * (It is also possible that a server will allow the connection with
35928 * or without a certificate; in that case, if you don't provide a
35929 * certificate, you can tell that the server requested one by the fact
35930 * that g_tls_client_connection_get_accepted_cas() will return
35938 * g_tls_connection_set_database:
35939 * @conn: a #GTlsConnection
35940 * @database: a #GTlsDatabase
35942 * Sets the certificate database that is used to verify peer certificates.
35943 * This is set to the default database by default. See
35944 * g_tls_backend_get_default_database(). If set to %NULL, then
35945 * peer certificate validation will always set the
35946 * %G_TLS_CERTIFICATE_UNKNOWN_CA error (meaning
35947 * #GTlsConnection::accept-certificate will always be emitted on
35948 * client-side connections, unless that bit is not set in
35949 * #GTlsClientConnection:validation-flags).
35956 * g_tls_connection_set_interaction:
35957 * @conn: a connection
35958 * @interaction: (allow-none): an interaction object, or %NULL
35960 * Set the object that will be used to interact with the user. It will be used
35961 * for things like prompting the user for passwords.
35963 * The @interaction argument will normally be a derived subclass of
35964 * #GTlsInteraction. %NULL can also be provided if no user interaction
35965 * should occur for this connection.
35972 * g_tls_connection_set_rehandshake_mode:
35973 * @conn: a #GTlsConnection
35974 * @mode: the rehandshaking mode
35976 * Sets how @conn behaves with respect to rehandshaking requests.
35978 * %G_TLS_REHANDSHAKE_NEVER means that it will never agree to
35979 * rehandshake after the initial handshake is complete. (For a client,
35980 * this means it will refuse rehandshake requests from the server, and
35981 * for a server, this means it will close the connection with an error
35982 * if the client attempts to rehandshake.)
35984 * %G_TLS_REHANDSHAKE_SAFELY means that the connection will allow a
35985 * rehandshake only if the other end of the connection supports the
35986 * TLS `renegotiation_info` extension. This is the default behavior,
35987 * but means that rehandshaking will not work against older
35988 * implementations that do not support that extension.
35990 * %G_TLS_REHANDSHAKE_UNSAFELY means that the connection will allow
35991 * rehandshaking even without the `renegotiation_info` extension. On
35992 * the server side in particular, this is not recommended, since it
35993 * leaves the server open to certain attacks. However, this mode is
35994 * necessary if you need to allow renegotiation with older client
36002 * g_tls_connection_set_require_close_notify:
36003 * @conn: a #GTlsConnection
36004 * @require_close_notify: whether or not to require close notification
36006 * Sets whether or not @conn expects a proper TLS close notification
36007 * before the connection is closed. If this is %TRUE (the default),
36008 * then @conn will expect to receive a TLS close notification from its
36009 * peer before the connection is closed, and will return a
36010 * %G_TLS_ERROR_EOF error if the connection is closed without proper
36011 * notification (since this may indicate a network error, or
36012 * man-in-the-middle attack).
36014 * In some protocols, the application will know whether or not the
36015 * connection was closed cleanly based on application-level data
36016 * (because the application-level data includes a length field, or is
36017 * somehow self-delimiting); in this case, the close notify is
36018 * redundant and sometimes omitted. (TLS 1.1 explicitly allows this;
36019 * in TLS 1.0 it is technically an error, but often done anyway.) You
36020 * can use g_tls_connection_set_require_close_notify() to tell @conn
36021 * to allow an "unannounced" connection close, in which case the close
36022 * will show up as a 0-length read, as in a non-TLS
36023 * #GSocketConnection, and it is up to the application to check that
36024 * the data has been fully received.
36026 * Note that this only affects the behavior when the peer closes the
36027 * connection; when the application calls g_io_stream_close() itself
36028 * on @conn, this will send a close notification regardless of the
36029 * setting of this property. If you explicitly want to do an unclean
36030 * close, you can close @conn's #GTlsConnection:base-io-stream rather
36031 * than closing @conn itself.
36038 * g_tls_connection_set_use_system_certdb:
36039 * @conn: a #GTlsConnection
36040 * @use_system_certdb: whether to use the system certificate database
36042 * Sets whether @conn uses the system certificate database to verify
36043 * peer certificates. This is %TRUE by default. If set to %FALSE, then
36044 * peer certificate validation will always set the
36045 * %G_TLS_CERTIFICATE_UNKNOWN_CA error (meaning
36046 * #GTlsConnection::accept-certificate will always be emitted on
36047 * client-side connections, unless that bit is not set in
36048 * #GTlsClientConnection:validation-flags).
36050 * Deprecated: 2.30: Use g_tls_connection_set_database() instead
36055 * g_tls_database_create_certificate_handle:
36056 * @self: a #GTlsDatabase
36057 * @certificate: certificate for which to create a handle.
36059 * Create a handle string for the certificate. The database will only be able
36060 * to create a handle for certificates that originate from the database. In
36061 * cases where the database cannot create a handle for a certificate, %NULL
36062 * will be returned.
36064 * This handle should be stable across various instances of the application,
36065 * and between applications. If a certificate is modified in the database,
36066 * then it is not guaranteed that this handle will continue to point to it.
36068 * Returns: (nullable): a newly allocated string containing the
36075 * g_tls_database_lookup_certificate_for_handle:
36076 * @self: a #GTlsDatabase
36077 * @handle: a certificate handle
36078 * @interaction: (allow-none): used to interact with the user if necessary
36079 * @flags: Flags which affect the lookup.
36080 * @cancellable: (allow-none): a #GCancellable, or %NULL
36081 * @error: (allow-none): a #GError, or %NULL
36083 * Lookup a certificate by its handle.
36085 * The handle should have been created by calling
36086 * g_tls_database_create_certificate_handle() on a #GTlsDatabase object of
36087 * the same TLS backend. The handle is designed to remain valid across
36088 * instantiations of the database.
36090 * If the handle is no longer valid, or does not point to a certificate in
36091 * this database, then %NULL will be returned.
36093 * This function can block, use g_tls_database_lookup_certificate_for_handle_async() to perform
36094 * the lookup operation asynchronously.
36096 * Returns: (transfer full) (allow-none): a newly allocated
36097 * #GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate.
36103 * g_tls_database_lookup_certificate_for_handle_async:
36104 * @self: a #GTlsDatabase
36105 * @handle: a certificate handle
36106 * @interaction: (allow-none): used to interact with the user if necessary
36107 * @flags: Flags which affect the lookup.
36108 * @cancellable: (allow-none): a #GCancellable, or %NULL
36109 * @callback: callback to call when the operation completes
36110 * @user_data: the data to pass to the callback function
36112 * Asynchronously lookup a certificate by its handle in the database. See
36113 * g_tls_database_lookup_certificate_for_handle() for more information.
36120 * g_tls_database_lookup_certificate_for_handle_finish:
36121 * @self: a #GTlsDatabase
36122 * @result: a #GAsyncResult.
36123 * @error: a #GError pointer, or %NULL
36125 * Finish an asynchronous lookup of a certificate by its handle. See
36126 * g_tls_database_lookup_certificate_handle() for more information.
36128 * If the handle is no longer valid, or does not point to a certificate in
36129 * this database, then %NULL will be returned.
36131 * Returns: (transfer full): a newly allocated #GTlsCertificate object.
36132 * Use g_object_unref() to release the certificate.
36138 * g_tls_database_lookup_certificate_issuer:
36139 * @self: a #GTlsDatabase
36140 * @certificate: a #GTlsCertificate
36141 * @interaction: (allow-none): used to interact with the user if necessary
36142 * @flags: flags which affect the lookup operation
36143 * @cancellable: (allow-none): a #GCancellable, or %NULL
36144 * @error: (allow-none): a #GError, or %NULL
36146 * Lookup the issuer of @certificate in the database.
36148 * The %issuer property
36149 * of @certificate is not modified, and the two certificates are not hooked
36152 * This function can block, use g_tls_database_lookup_certificate_issuer_async() to perform
36153 * the lookup operation asynchronously.
36155 * Returns: (transfer full): a newly allocated issuer #GTlsCertificate,
36156 * or %NULL. Use g_object_unref() to release the certificate.
36162 * g_tls_database_lookup_certificate_issuer_async:
36163 * @self: a #GTlsDatabase
36164 * @certificate: a #GTlsCertificate
36165 * @interaction: (allow-none): used to interact with the user if necessary
36166 * @flags: flags which affect the lookup operation
36167 * @cancellable: (allow-none): a #GCancellable, or %NULL
36168 * @callback: callback to call when the operation completes
36169 * @user_data: the data to pass to the callback function
36171 * Asynchronously lookup the issuer of @certificate in the database. See
36172 * g_tls_database_lookup_certificate_issuer() for more information.
36179 * g_tls_database_lookup_certificate_issuer_finish:
36180 * @self: a #GTlsDatabase
36181 * @result: a #GAsyncResult.
36182 * @error: a #GError pointer, or %NULL
36184 * Finish an asynchronous lookup issuer operation. See
36185 * g_tls_database_lookup_certificate_issuer() for more information.
36187 * Returns: (transfer full): a newly allocated issuer #GTlsCertificate,
36188 * or %NULL. Use g_object_unref() to release the certificate.
36194 * g_tls_database_lookup_certificates_issued_by:
36195 * @self: a #GTlsDatabase
36196 * @issuer_raw_dn: a #GByteArray which holds the DER encoded issuer DN.
36197 * @interaction: (allow-none): used to interact with the user if necessary
36198 * @flags: Flags which affect the lookup operation.
36199 * @cancellable: (allow-none): a #GCancellable, or %NULL
36200 * @error: (allow-none): a #GError, or %NULL
36202 * Lookup certificates issued by this issuer in the database.
36204 * This function can block, use g_tls_database_lookup_certificates_issued_by_async() to perform
36205 * the lookup operation asynchronously.
36207 * Returns: (transfer full) (element-type GTlsCertificate): a newly allocated list of #GTlsCertificate
36208 * objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list.
36214 * g_tls_database_lookup_certificates_issued_by_async:
36215 * @self: a #GTlsDatabase
36216 * @issuer_raw_dn: a #GByteArray which holds the DER encoded issuer DN.
36217 * @interaction: (allow-none): used to interact with the user if necessary
36218 * @flags: Flags which affect the lookup operation.
36219 * @cancellable: (allow-none): a #GCancellable, or %NULL
36220 * @callback: callback to call when the operation completes
36221 * @user_data: the data to pass to the callback function
36223 * Asynchronously lookup certificates issued by this issuer in the database. See
36224 * g_tls_database_lookup_certificates_issued_by() for more information.
36226 * The database may choose to hold a reference to the issuer byte array for the duration
36227 * of of this asynchronous operation. The byte array should not be modified during
36235 * g_tls_database_lookup_certificates_issued_by_finish:
36236 * @self: a #GTlsDatabase
36237 * @result: a #GAsyncResult.
36238 * @error: a #GError pointer, or %NULL
36240 * Finish an asynchronous lookup of certificates. See
36241 * g_tls_database_lookup_certificates_issued_by() for more information.
36243 * Returns: (transfer full) (element-type GTlsCertificate): a newly allocated list of #GTlsCertificate
36244 * objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list.
36250 * g_tls_database_verify_chain:
36251 * @self: a #GTlsDatabase
36252 * @chain: a #GTlsCertificate chain
36253 * @purpose: the purpose that this certificate chain will be used for.
36254 * @identity: (allow-none): the expected peer identity
36255 * @interaction: (allow-none): used to interact with the user if necessary
36256 * @flags: additional verify flags
36257 * @cancellable: (allow-none): a #GCancellable, or %NULL
36258 * @error: (allow-none): a #GError, or %NULL
36260 * Verify's a certificate chain after looking up and adding any missing
36261 * certificates to the chain.
36263 * @chain is a chain of #GTlsCertificate objects each pointing to the next
36264 * certificate in the chain by its %issuer property. The chain may initially
36265 * consist of one or more certificates. After the verification process is
36266 * complete, @chain may be modified by adding missing certificates, or removing
36267 * extra certificates. If a certificate anchor was found, then it is added to
36270 * @purpose describes the purpose (or usage) for which the certificate
36271 * is being used. Typically @purpose will be set to #G_TLS_DATABASE_PURPOSE_AUTHENTICATE_SERVER
36272 * which means that the certificate is being used to authenticate a server
36273 * (and we are acting as the client).
36275 * The @identity is used to check for pinned certificates (trust exceptions)
36276 * in the database. These will override the normal verification process on a
36277 * host by host basis.
36279 * Currently there are no @flags, and %G_TLS_DATABASE_VERIFY_NONE should be
36282 * This function can block, use g_tls_database_verify_chain_async() to perform
36283 * the verification operation asynchronously.
36285 * Returns: the appropriate #GTlsCertificateFlags which represents the
36286 * result of verification.
36292 * g_tls_database_verify_chain_async:
36293 * @self: a #GTlsDatabase
36294 * @chain: a #GTlsCertificate chain
36295 * @purpose: the purpose that this certificate chain will be used for.
36296 * @identity: (allow-none): the expected peer identity
36297 * @interaction: (allow-none): used to interact with the user if necessary
36298 * @flags: additional verify flags
36299 * @cancellable: (allow-none): a #GCancellable, or %NULL
36300 * @callback: callback to call when the operation completes
36301 * @user_data: the data to pass to the callback function
36303 * Asynchronously verify's a certificate chain after looking up and adding
36304 * any missing certificates to the chain. See g_tls_database_verify_chain()
36305 * for more information.
36312 * g_tls_database_verify_chain_finish:
36313 * @self: a #GTlsDatabase
36314 * @result: a #GAsyncResult.
36315 * @error: a #GError pointer, or %NULL
36317 * Finish an asynchronous verify chain operation. See
36318 * g_tls_database_verify_chain() for more information. *
36320 * Returns: the appropriate #GTlsCertificateFlags which represents the
36321 * result of verification.
36327 * g_tls_error_quark:
36329 * Gets the TLS error quark.
36331 * Returns: a #GQuark.
36337 * g_tls_file_database_new:
36338 * @anchors: filename of anchor certificate authorities.
36339 * @error: #GError for error reporting, or %NULL to ignore.
36341 * Creates a new #GTlsFileDatabase which uses anchor certificate authorities
36342 * in @anchors to verify certificate chains.
36344 * The certificates in @anchors must be PEM encoded.
36346 * Returns: (transfer full) (type GTlsFileDatabase): the new
36347 * #GTlsFileDatabase, or %NULL on error
36353 * g_tls_interaction_ask_password:
36354 * @interaction: a #GTlsInteraction object
36355 * @password: a #GTlsPassword object
36356 * @cancellable: an optional #GCancellable cancellation object
36357 * @error: an optional location to place an error on failure
36359 * Run synchronous interaction to ask the user for a password. In general,
36360 * g_tls_interaction_invoke_ask_password() should be used instead of this
36363 * Derived subclasses usually implement a password prompt, although they may
36364 * also choose to provide a password from elsewhere. The @password value will
36365 * be filled in and then @callback will be called. Alternatively the user may
36366 * abort this password request, which will usually abort the TLS connection.
36368 * If the interaction is cancelled by the cancellation object, or by the
36369 * user then %G_TLS_INTERACTION_FAILED will be returned with an error that
36370 * contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may
36371 * not support immediate cancellation.
36373 * Returns: The status of the ask password interaction.
36379 * g_tls_interaction_ask_password_async:
36380 * @interaction: a #GTlsInteraction object
36381 * @password: a #GTlsPassword object
36382 * @cancellable: an optional #GCancellable cancellation object
36383 * @callback: (allow-none): will be called when the interaction completes
36384 * @user_data: (allow-none): data to pass to the @callback
36386 * Run asynchronous interaction to ask the user for a password. In general,
36387 * g_tls_interaction_invoke_ask_password() should be used instead of this
36390 * Derived subclasses usually implement a password prompt, although they may
36391 * also choose to provide a password from elsewhere. The @password value will
36392 * be filled in and then @callback will be called. Alternatively the user may
36393 * abort this password request, which will usually abort the TLS connection.
36395 * If the interaction is cancelled by the cancellation object, or by the
36396 * user then %G_TLS_INTERACTION_FAILED will be returned with an error that
36397 * contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may
36398 * not support immediate cancellation.
36400 * Certain implementations may not support immediate cancellation.
36407 * g_tls_interaction_ask_password_finish:
36408 * @interaction: a #GTlsInteraction object
36409 * @result: the result passed to the callback
36410 * @error: an optional location to place an error on failure
36412 * Complete an ask password user interaction request. This should be once
36413 * the g_tls_interaction_ask_password_async() completion callback is called.
36415 * If %G_TLS_INTERACTION_HANDLED is returned, then the #GTlsPassword passed
36416 * to g_tls_interaction_ask_password() will have its password filled in.
36418 * If the interaction is cancelled by the cancellation object, or by the
36419 * user then %G_TLS_INTERACTION_FAILED will be returned with an error that
36420 * contains a %G_IO_ERROR_CANCELLED error code.
36422 * Returns: The status of the ask password interaction.
36428 * g_tls_interaction_invoke_ask_password:
36429 * @interaction: a #GTlsInteraction object
36430 * @password: a #GTlsPassword object
36431 * @cancellable: an optional #GCancellable cancellation object
36432 * @error: an optional location to place an error on failure
36434 * Invoke the interaction to ask the user for a password. It invokes this
36435 * interaction in the main loop, specifically the #GMainContext returned by
36436 * g_main_context_get_thread_default() when the interaction is created. This
36437 * is called by called by #GTlsConnection or #GTlsDatabase to ask the user
36440 * Derived subclasses usually implement a password prompt, although they may
36441 * also choose to provide a password from elsewhere. The @password value will
36442 * be filled in and then @callback will be called. Alternatively the user may
36443 * abort this password request, which will usually abort the TLS connection.
36445 * The implementation can either be a synchronous (eg: modal dialog) or an
36446 * asynchronous one (eg: modeless dialog). This function will take care of
36447 * calling which ever one correctly.
36449 * If the interaction is cancelled by the cancellation object, or by the
36450 * user then %G_TLS_INTERACTION_FAILED will be returned with an error that
36451 * contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may
36452 * not support immediate cancellation.
36454 * Returns: The status of the ask password interaction.
36460 * g_tls_interaction_invoke_request_certificate:
36461 * @interaction: a #GTlsInteraction object
36462 * @connection: a #GTlsConnection object
36463 * @flags: flags providing more information about the request
36464 * @cancellable: an optional #GCancellable cancellation object
36465 * @error: an optional location to place an error on failure
36467 * Invoke the interaction to ask the user to choose a certificate to
36468 * use with the connection. It invokes this interaction in the main
36469 * loop, specifically the #GMainContext returned by
36470 * g_main_context_get_thread_default() when the interaction is
36471 * created. This is called by called by #GTlsConnection when the peer
36472 * requests a certificate during the handshake.
36474 * Derived subclasses usually implement a certificate selector,
36475 * although they may also choose to provide a certificate from
36476 * elsewhere. Alternatively the user may abort this certificate
36477 * request, which may or may not abort the TLS connection.
36479 * The implementation can either be a synchronous (eg: modal dialog) or an
36480 * asynchronous one (eg: modeless dialog). This function will take care of
36481 * calling which ever one correctly.
36483 * If the interaction is cancelled by the cancellation object, or by the
36484 * user then %G_TLS_INTERACTION_FAILED will be returned with an error that
36485 * contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may
36486 * not support immediate cancellation.
36488 * Returns: The status of the certificate request interaction.
36494 * g_tls_interaction_request_certificate:
36495 * @interaction: a #GTlsInteraction object
36496 * @connection: a #GTlsConnection object
36497 * @flags: flags providing more information about the request
36498 * @cancellable: an optional #GCancellable cancellation object
36499 * @error: an optional location to place an error on failure
36501 * Run synchronous interaction to ask the user to choose a certificate to use
36502 * with the connection. In general, g_tls_interaction_invoke_request_certificate()
36503 * should be used instead of this function.
36505 * Derived subclasses usually implement a certificate selector, although they may
36506 * also choose to provide a certificate from elsewhere. Alternatively the user may
36507 * abort this certificate request, which will usually abort the TLS connection.
36509 * If %G_TLS_INTERACTION_HANDLED is returned, then the #GTlsConnection
36510 * passed to g_tls_interaction_request_certificate() will have had its
36511 * #GTlsConnection:certificate filled in.
36513 * If the interaction is cancelled by the cancellation object, or by the
36514 * user then %G_TLS_INTERACTION_FAILED will be returned with an error that
36515 * contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may
36516 * not support immediate cancellation.
36518 * Returns: The status of the request certificate interaction.
36524 * g_tls_interaction_request_certificate_async:
36525 * @interaction: a #GTlsInteraction object
36526 * @connection: a #GTlsConnection object
36527 * @flags: flags providing more information about the request
36528 * @cancellable: an optional #GCancellable cancellation object
36529 * @callback: (allow-none): will be called when the interaction completes
36530 * @user_data: (allow-none): data to pass to the @callback
36532 * Run asynchronous interaction to ask the user for a certificate to use with
36533 * the connection. In general, g_tls_interaction_invoke_request_certificate() should
36534 * be used instead of this function.
36536 * Derived subclasses usually implement a certificate selector, although they may
36537 * also choose to provide a certificate from elsewhere. @callback will be called
36538 * when the operation completes. Alternatively the user may abort this certificate
36539 * request, which will usually abort the TLS connection.
36546 * g_tls_interaction_request_certificate_finish:
36547 * @interaction: a #GTlsInteraction object
36548 * @result: the result passed to the callback
36549 * @error: an optional location to place an error on failure
36551 * Complete an request certificate user interaction request. This should be once
36552 * the g_tls_interaction_request_certificate_async() completion callback is called.
36554 * If %G_TLS_INTERACTION_HANDLED is returned, then the #GTlsConnection
36555 * passed to g_tls_interaction_request_certificate_async() will have had its
36556 * #GTlsConnection:certificate filled in.
36558 * If the interaction is cancelled by the cancellation object, or by the
36559 * user then %G_TLS_INTERACTION_FAILED will be returned with an error that
36560 * contains a %G_IO_ERROR_CANCELLED error code.
36562 * Returns: The status of the request certificate interaction.
36568 * g_tls_password_get_description:
36569 * @password: a #GTlsPassword object
36571 * Get a description string about what the password will be used for.
36573 * Returns: The description of the password.
36579 * g_tls_password_get_flags:
36580 * @password: a #GTlsPassword object
36582 * Get flags about the password.
36584 * Returns: The flags about the password.
36590 * g_tls_password_get_value:
36591 * @password: a #GTlsPassword object
36592 * @length: (allow-none): location to place the length of the password.
36594 * Get the password value. If @length is not %NULL then it will be
36595 * filled in with the length of the password value. (Note that the
36596 * password value is not nul-terminated, so you can only pass %NULL
36597 * for @length in contexts where you know the password will have a
36598 * certain fixed length.)
36600 * Returns: The password value (owned by the password object).
36606 * g_tls_password_get_warning:
36607 * @password: a #GTlsPassword object
36609 * Get a user readable translated warning. Usually this warning is a
36610 * representation of the password flags returned from
36611 * g_tls_password_get_flags().
36613 * Returns: The warning.
36619 * g_tls_password_new:
36620 * @flags: the password flags
36621 * @description: description of what the password is for
36623 * Create a new #GTlsPassword object.
36625 * Returns: (transfer full): The newly allocated password object
36630 * g_tls_password_set_description:
36631 * @password: a #GTlsPassword object
36632 * @description: The description of the password
36634 * Set a description string about what the password will be used for.
36641 * g_tls_password_set_flags:
36642 * @password: a #GTlsPassword object
36643 * @flags: The flags about the password
36645 * Set flags about the password.
36652 * g_tls_password_set_value:
36653 * @password: a #GTlsPassword object
36654 * @value: the new password value
36655 * @length: the length of the password, or -1
36657 * Set the value for this password. The @value will be copied by the password
36660 * Specify the @length, for a non-nul-terminated password. Pass -1 as
36661 * @length if using a nul-terminated password, and @length will be
36662 * calculated automatically. (Note that the terminating nul is not
36663 * considered part of the password in this case.)
36670 * g_tls_password_set_value_full: (virtual set_value)
36671 * @password: a #GTlsPassword object
36672 * @value: the value for the password
36673 * @length: the length of the password, or -1
36674 * @destroy: (allow-none): a function to use to free the password.
36676 * Provide the value for this password.
36678 * The @value will be owned by the password object, and later freed using
36679 * the @destroy function callback.
36681 * Specify the @length, for a non-nul-terminated password. Pass -1 as
36682 * @length if using a nul-terminated password, and @length will be
36683 * calculated automatically. (Note that the terminating nul is not
36684 * considered part of the password in this case.)
36691 * g_tls_password_set_warning:
36692 * @password: a #GTlsPassword object
36693 * @warning: The user readable warning
36695 * Set a user readable translated warning. Usually this warning is a
36696 * representation of the password flags returned from
36697 * g_tls_password_get_flags().
36704 * g_tls_server_connection_new:
36705 * @base_io_stream: the #GIOStream to wrap
36706 * @certificate: (allow-none): the default server certificate, or %NULL
36707 * @error: #GError for error reporting, or %NULL to ignore.
36709 * Creates a new #GTlsServerConnection wrapping @base_io_stream (which
36710 * must have pollable input and output streams).
36712 * Returns: (transfer full) (type GTlsServerConnection): the new
36713 * #GTlsServerConnection, or %NULL on error
36719 * g_unix_connection_receive_credentials:
36720 * @connection: A #GUnixConnection.
36721 * @cancellable: (allow-none): A #GCancellable or %NULL.
36722 * @error: Return location for error or %NULL.
36724 * Receives credentials from the sending end of the connection. The
36725 * sending end has to call g_unix_connection_send_credentials() (or
36726 * similar) for this to work.
36728 * As well as reading the credentials this also reads (and discards) a
36729 * single byte from the stream, as this is required for credentials
36730 * passing to work on some implementations.
36732 * Other ways to exchange credentials with a foreign peer includes the
36733 * #GUnixCredentialsMessage type and g_socket_get_credentials() function.
36735 * Returns: (transfer full): Received credentials on success (free with
36736 * g_object_unref()), %NULL if @error is set.
36742 * g_unix_connection_receive_credentials_async:
36743 * @connection: A #GUnixConnection.
36744 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
36745 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
36746 * @user_data: (closure): the data to pass to callback function
36748 * Asynchronously receive credentials.
36750 * For more details, see g_unix_connection_receive_credentials() which is
36751 * the synchronous version of this call.
36753 * When the operation is finished, @callback will be called. You can then call
36754 * g_unix_connection_receive_credentials_finish() to get the result of the operation.
36761 * g_unix_connection_receive_credentials_finish:
36762 * @connection: A #GUnixConnection.
36763 * @result: a #GAsyncResult.
36764 * @error: a #GError, or %NULL
36766 * Finishes an asynchronous receive credentials operation started with
36767 * g_unix_connection_receive_credentials_async().
36769 * Returns: (transfer full): a #GCredentials, or %NULL on error.
36770 * Free the returned object with g_object_unref().
36776 * g_unix_connection_receive_fd:
36777 * @connection: a #GUnixConnection
36778 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
36779 * @error: (allow-none): #GError for error reporting, or %NULL to ignore
36781 * Receives a file descriptor from the sending end of the connection.
36782 * The sending end has to call g_unix_connection_send_fd() for this
36785 * As well as reading the fd this also reads a single byte from the
36786 * stream, as this is required for fd passing to work on some
36789 * Returns: a file descriptor on success, -1 on error.
36795 * g_unix_connection_send_credentials:
36796 * @connection: A #GUnixConnection.
36797 * @cancellable: (allow-none): A #GCancellable or %NULL.
36798 * @error: Return location for error or %NULL.
36800 * Passes the credentials of the current user the receiving side
36801 * of the connection. The receiving end has to call
36802 * g_unix_connection_receive_credentials() (or similar) to accept the
36805 * As well as sending the credentials this also writes a single NUL
36806 * byte to the stream, as this is required for credentials passing to
36807 * work on some implementations.
36809 * Other ways to exchange credentials with a foreign peer includes the
36810 * #GUnixCredentialsMessage type and g_socket_get_credentials() function.
36812 * Returns: %TRUE on success, %FALSE if @error is set.
36818 * g_unix_connection_send_credentials_async:
36819 * @connection: A #GUnixConnection.
36820 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
36821 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
36822 * @user_data: (closure): the data to pass to callback function
36824 * Asynchronously send credentials.
36826 * For more details, see g_unix_connection_send_credentials() which is
36827 * the synchronous version of this call.
36829 * When the operation is finished, @callback will be called. You can then call
36830 * g_unix_connection_send_credentials_finish() to get the result of the operation.
36837 * g_unix_connection_send_credentials_finish:
36838 * @connection: A #GUnixConnection.
36839 * @result: a #GAsyncResult.
36840 * @error: a #GError, or %NULL
36842 * Finishes an asynchronous send credentials operation started with
36843 * g_unix_connection_send_credentials_async().
36845 * Returns: %TRUE if the operation was successful, otherwise %FALSE.
36851 * g_unix_connection_send_fd:
36852 * @connection: a #GUnixConnection
36853 * @fd: a file descriptor
36854 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
36855 * @error: (allow-none): #GError for error reporting, or %NULL to ignore.
36857 * Passes a file descriptor to the receiving side of the
36858 * connection. The receiving end has to call g_unix_connection_receive_fd()
36859 * to accept the file descriptor.
36861 * As well as sending the fd this also writes a single byte to the
36862 * stream, as this is required for fd passing to work on some
36865 * Returns: a %TRUE on success, %NULL on error.
36871 * g_unix_credentials_message_get_credentials:
36872 * @message: A #GUnixCredentialsMessage.
36874 * Gets the credentials stored in @message.
36876 * Returns: (transfer none): A #GCredentials instance. Do not free, it is owned by @message.
36882 * g_unix_credentials_message_is_supported:
36884 * Checks if passing #GCredentials on a #GSocket is supported on this platform.
36886 * Returns: %TRUE if supported, %FALSE otherwise
36892 * g_unix_credentials_message_new:
36894 * Creates a new #GUnixCredentialsMessage with credentials matching the current processes.
36896 * Returns: a new #GUnixCredentialsMessage
36902 * g_unix_credentials_message_new_with_credentials:
36903 * @credentials: A #GCredentials object.
36905 * Creates a new #GUnixCredentialsMessage holding @credentials.
36907 * Returns: a new #GUnixCredentialsMessage
36913 * g_unix_fd_list_append:
36914 * @list: a #GUnixFDList
36915 * @fd: a valid open file descriptor
36916 * @error: a #GError pointer
36918 * Adds a file descriptor to @list.
36920 * The file descriptor is duplicated using dup(). You keep your copy
36921 * of the descriptor and the copy contained in @list will be closed
36922 * when @list is finalized.
36924 * A possible cause of failure is exceeding the per-process or
36925 * system-wide file descriptor limit.
36927 * The index of the file descriptor in the list is returned. If you use
36928 * this index with g_unix_fd_list_get() then you will receive back a
36929 * duplicated copy of the same file descriptor.
36931 * Returns: the index of the appended fd in case of success, else -1
36932 * (and @error is set)
36938 * g_unix_fd_list_get:
36939 * @list: a #GUnixFDList
36940 * @index_: the index into the list
36941 * @error: a #GError pointer
36943 * Gets a file descriptor out of @list.
36945 * @index_ specifies the index of the file descriptor to get. It is a
36946 * programmer error for @index_ to be out of range; see
36947 * g_unix_fd_list_get_length().
36949 * The file descriptor is duplicated using dup() and set as
36950 * close-on-exec before being returned. You must call close() on it
36951 * when you are done.
36953 * A possible cause of failure is exceeding the per-process or
36954 * system-wide file descriptor limit.
36956 * Returns: the file descriptor, or -1 in case of error
36962 * g_unix_fd_list_get_length:
36963 * @list: a #GUnixFDList
36965 * Gets the length of @list (ie: the number of file descriptors
36966 * contained within).
36968 * Returns: the length of @list
36974 * g_unix_fd_list_new:
36976 * Creates a new #GUnixFDList containing no file descriptors.
36978 * Returns: a new #GUnixFDList
36984 * g_unix_fd_list_new_from_array:
36985 * @fds: (array length=n_fds): the initial list of file descriptors
36986 * @n_fds: the length of #fds, or -1
36988 * Creates a new #GUnixFDList containing the file descriptors given in
36989 * @fds. The file descriptors become the property of the new list and
36990 * may no longer be used by the caller. The array itself is owned by
36993 * Each file descriptor in the array should be set to close-on-exec.
36995 * If @n_fds is -1 then @fds must be terminated with -1.
36997 * Returns: a new #GUnixFDList
37003 * g_unix_fd_list_peek_fds:
37004 * @list: a #GUnixFDList
37005 * @length: (out) (allow-none): pointer to the length of the returned
37008 * Returns the array of file descriptors that is contained in this
37011 * After this call, the descriptors remain the property of @list. The
37012 * caller must not close them and must not free the array. The array is
37013 * valid only until @list is changed in any way.
37015 * If @length is non-%NULL then it is set to the number of file
37016 * descriptors in the returned array. The returned array is also
37017 * terminated with -1.
37019 * This function never returns %NULL. In case there are no file
37020 * descriptors contained in @list, an empty array is returned.
37022 * Returns: (array length=length) (transfer none): an array of file
37029 * g_unix_fd_list_steal_fds:
37030 * @list: a #GUnixFDList
37031 * @length: (out) (allow-none): pointer to the length of the returned
37034 * Returns the array of file descriptors that is contained in this
37037 * After this call, the descriptors are no longer contained in
37038 * @list. Further calls will return an empty list (unless more
37039 * descriptors have been added).
37041 * The return result of this function must be freed with g_free().
37042 * The caller is also responsible for closing all of the file
37043 * descriptors. The file descriptors in the array are set to
37046 * If @length is non-%NULL then it is set to the number of file
37047 * descriptors in the returned array. The returned array is also
37048 * terminated with -1.
37050 * This function never returns %NULL. In case there are no file
37051 * descriptors contained in @list, an empty array is returned.
37053 * Returns: (array length=length) (transfer full): an array of file
37060 * g_unix_fd_message_append_fd:
37061 * @message: a #GUnixFDMessage
37062 * @fd: a valid open file descriptor
37063 * @error: a #GError pointer
37065 * Adds a file descriptor to @message.
37067 * The file descriptor is duplicated using dup(). You keep your copy
37068 * of the descriptor and the copy contained in @message will be closed
37069 * when @message is finalized.
37071 * A possible cause of failure is exceeding the per-process or
37072 * system-wide file descriptor limit.
37074 * Returns: %TRUE in case of success, else %FALSE (and @error is set)
37080 * g_unix_fd_message_get_fd_list:
37081 * @message: a #GUnixFDMessage
37083 * Gets the #GUnixFDList contained in @message. This function does not
37084 * return a reference to the caller, but the returned list is valid for
37085 * the lifetime of @message.
37087 * Returns: (transfer none): the #GUnixFDList from @message
37093 * g_unix_fd_message_new:
37095 * Creates a new #GUnixFDMessage containing an empty file descriptor
37098 * Returns: a new #GUnixFDMessage
37104 * g_unix_fd_message_new_with_fd_list:
37105 * @fd_list: a #GUnixFDList
37107 * Creates a new #GUnixFDMessage containing @list.
37109 * Returns: a new #GUnixFDMessage
37115 * g_unix_fd_message_steal_fds:
37116 * @message: a #GUnixFDMessage
37117 * @length: (out) (allow-none): pointer to the length of the returned
37120 * Returns the array of file descriptors that is contained in this
37123 * After this call, the descriptors are no longer contained in
37124 * @message. Further calls will return an empty list (unless more
37125 * descriptors have been added).
37127 * The return result of this function must be freed with g_free().
37128 * The caller is also responsible for closing all of the file
37131 * If @length is non-%NULL then it is set to the number of file
37132 * descriptors in the returned array. The returned array is also
37133 * terminated with -1.
37135 * This function never returns %NULL. In case there are no file
37136 * descriptors contained in @message, an empty array is returned.
37138 * Returns: (array length=length) (transfer full): an array of file
37145 * g_unix_input_stream_get_close_fd:
37146 * @stream: a #GUnixInputStream
37148 * Returns whether the file descriptor of @stream will be
37149 * closed when the stream is closed.
37151 * Returns: %TRUE if the file descriptor is closed when done
37157 * g_unix_input_stream_get_fd:
37158 * @stream: a #GUnixInputStream
37160 * Return the UNIX file descriptor that the stream reads from.
37162 * Returns: The file descriptor of @stream
37168 * g_unix_input_stream_new:
37169 * @fd: a UNIX file descriptor
37170 * @close_fd: %TRUE to close the file descriptor when done
37172 * Creates a new #GUnixInputStream for the given @fd.
37174 * If @close_fd is %TRUE, the file descriptor will be closed
37175 * when the stream is closed.
37177 * Returns: a new #GUnixInputStream
37182 * g_unix_input_stream_set_close_fd:
37183 * @stream: a #GUnixInputStream
37184 * @close_fd: %TRUE to close the file descriptor when done
37186 * Sets whether the file descriptor of @stream shall be closed
37187 * when the stream is closed.
37194 * g_unix_is_mount_path_system_internal:
37195 * @mount_path: a mount path, e.g. `/media/disk` or `/usr`
37197 * Determines if @mount_path is considered an implementation of the
37198 * OS. This is primarily used for hiding mountable and mounted volumes
37199 * that only are used in the OS and has little to no relevance to the
37202 * Returns: %TRUE if @mount_path is considered an implementation detail
37208 * g_unix_mount_at: (skip)
37209 * @mount_path: path for a possible unix mount.
37210 * @time_read: (out) (allow-none): guint64 to contain a timestamp.
37212 * Gets a #GUnixMountEntry for a given mount path. If @time_read
37213 * is set, it will be filled with a unix timestamp for checking
37214 * if the mounts have changed since with g_unix_mounts_changed_since().
37216 * Returns: (transfer full): a #GUnixMountEntry.
37221 * g_unix_mount_compare:
37222 * @mount1: first #GUnixMountEntry to compare.
37223 * @mount2: second #GUnixMountEntry to compare.
37225 * Compares two unix mounts.
37227 * Returns: 1, 0 or -1 if @mount1 is greater than, equal to,
37228 * or less than @mount2, respectively.
37233 * g_unix_mount_free:
37234 * @mount_entry: a #GUnixMountEntry.
37236 * Frees a unix mount.
37241 * g_unix_mount_get_device_path:
37242 * @mount_entry: a #GUnixMount.
37244 * Gets the device path for a unix mount.
37246 * Returns: a string containing the device path.
37251 * g_unix_mount_get_fs_type:
37252 * @mount_entry: a #GUnixMount.
37254 * Gets the filesystem type for the unix mount.
37256 * Returns: a string containing the file system type.
37261 * g_unix_mount_get_mount_path:
37262 * @mount_entry: input #GUnixMountEntry to get the mount path for.
37264 * Gets the mount path for a unix mount.
37266 * Returns: the mount path for @mount_entry.
37271 * g_unix_mount_guess_can_eject:
37272 * @mount_entry: a #GUnixMountEntry
37274 * Guesses whether a Unix mount can be ejected.
37276 * Returns: %TRUE if @mount_entry is deemed to be ejectable.
37281 * g_unix_mount_guess_icon:
37282 * @mount_entry: a #GUnixMountEntry
37284 * Guesses the icon of a Unix mount.
37286 * Returns: (transfer full): a #GIcon
37291 * g_unix_mount_guess_name:
37292 * @mount_entry: a #GUnixMountEntry
37294 * Guesses the name of a Unix mount.
37295 * The result is a translated string.
37297 * Returns: A newly allocated string that must
37298 * be freed with g_free()
37303 * g_unix_mount_guess_should_display:
37304 * @mount_entry: a #GUnixMountEntry
37306 * Guesses whether a Unix mount should be displayed in the UI.
37308 * Returns: %TRUE if @mount_entry is deemed to be displayable.
37313 * g_unix_mount_guess_symbolic_icon:
37314 * @mount_entry: a #GUnixMountEntry
37316 * Guesses the symbolic icon of a Unix mount.
37318 * Returns: (transfer full): a #GIcon
37324 * g_unix_mount_is_readonly:
37325 * @mount_entry: a #GUnixMount.
37327 * Checks if a unix mount is mounted read only.
37329 * Returns: %TRUE if @mount_entry is read only.
37334 * g_unix_mount_is_system_internal:
37335 * @mount_entry: a #GUnixMount.
37337 * Checks if a unix mount is a system path.
37339 * Returns: %TRUE if the unix mount is for a system path.
37344 * g_unix_mount_monitor_new:
37346 * Gets a new #GUnixMountMonitor. The default rate limit for which the
37347 * monitor will report consecutive changes for the mount and mount
37348 * point entry files is the default for a #GFileMonitor. Use
37349 * g_unix_mount_monitor_set_rate_limit() to change this.
37351 * Returns: a #GUnixMountMonitor.
37356 * g_unix_mount_monitor_set_rate_limit:
37357 * @mount_monitor: a #GUnixMountMonitor
37358 * @limit_msec: a integer with the limit in milliseconds to
37359 * poll for changes.
37361 * Sets the rate limit to which the @mount_monitor will report
37362 * consecutive change events to the mount and mount point entry files.
37369 * g_unix_mount_point_compare:
37370 * @mount1: a #GUnixMount.
37371 * @mount2: a #GUnixMount.
37373 * Compares two unix mount points.
37375 * Returns: 1, 0 or -1 if @mount1 is greater than, equal to,
37376 * or less than @mount2, respectively.
37381 * g_unix_mount_point_free:
37382 * @mount_point: unix mount point to free.
37384 * Frees a unix mount point.
37389 * g_unix_mount_point_get_device_path:
37390 * @mount_point: a #GUnixMountPoint.
37392 * Gets the device path for a unix mount point.
37394 * Returns: a string containing the device path.
37399 * g_unix_mount_point_get_fs_type:
37400 * @mount_point: a #GUnixMountPoint.
37402 * Gets the file system type for the mount point.
37404 * Returns: a string containing the file system type.
37409 * g_unix_mount_point_get_mount_path:
37410 * @mount_point: a #GUnixMountPoint.
37412 * Gets the mount path for a unix mount point.
37414 * Returns: a string containing the mount path.
37419 * g_unix_mount_point_get_options:
37420 * @mount_point: a #GUnixMountPoint.
37422 * Gets the options for the mount point.
37424 * Returns: a string containing the options.
37430 * g_unix_mount_point_guess_can_eject:
37431 * @mount_point: a #GUnixMountPoint
37433 * Guesses whether a Unix mount point can be ejected.
37435 * Returns: %TRUE if @mount_point is deemed to be ejectable.
37440 * g_unix_mount_point_guess_icon:
37441 * @mount_point: a #GUnixMountPoint
37443 * Guesses the icon of a Unix mount point.
37445 * Returns: (transfer full): a #GIcon
37450 * g_unix_mount_point_guess_name:
37451 * @mount_point: a #GUnixMountPoint
37453 * Guesses the name of a Unix mount point.
37454 * The result is a translated string.
37456 * Returns: A newly allocated string that must
37457 * be freed with g_free()
37462 * g_unix_mount_point_guess_symbolic_icon:
37463 * @mount_point: a #GUnixMountPoint
37465 * Guesses the symbolic icon of a Unix mount point.
37467 * Returns: (transfer full): a #GIcon
37473 * g_unix_mount_point_is_loopback:
37474 * @mount_point: a #GUnixMountPoint.
37476 * Checks if a unix mount point is a loopback device.
37478 * Returns: %TRUE if the mount point is a loopback. %FALSE otherwise.
37483 * g_unix_mount_point_is_readonly:
37484 * @mount_point: a #GUnixMountPoint.
37486 * Checks if a unix mount point is read only.
37488 * Returns: %TRUE if a mount point is read only.
37493 * g_unix_mount_point_is_user_mountable:
37494 * @mount_point: a #GUnixMountPoint.
37496 * Checks if a unix mount point is mountable by the user.
37498 * Returns: %TRUE if the mount point is user mountable.
37503 * g_unix_mount_points_changed_since:
37504 * @time: guint64 to contain a timestamp.
37506 * Checks if the unix mount points have changed since a given unix time.
37508 * Returns: %TRUE if the mount points have changed since @time.
37513 * g_unix_mount_points_get: (skip)
37514 * @time_read: (out) (allow-none): guint64 to contain a timestamp.
37516 * Gets a #GList of #GUnixMountPoint containing the unix mount points.
37517 * If @time_read is set, it will be filled with the mount timestamp,
37518 * allowing for checking if the mounts have changed with
37519 * g_unix_mount_points_changed_since().
37521 * Returns: (element-type GUnixMountPoint) (transfer full):
37522 * a #GList of the UNIX mountpoints.
37527 * g_unix_mounts_changed_since:
37528 * @time: guint64 to contain a timestamp.
37530 * Checks if the unix mounts have changed since a given unix time.
37532 * Returns: %TRUE if the mounts have changed since @time.
37537 * g_unix_mounts_get: (skip)
37538 * @time_read: (out) (allow-none): guint64 to contain a timestamp, or %NULL
37540 * Gets a #GList of #GUnixMountEntry containing the unix mounts.
37541 * If @time_read is set, it will be filled with the mount
37542 * timestamp, allowing for checking if the mounts have changed
37543 * with g_unix_mounts_changed_since().
37545 * Returns: (element-type GUnixMountEntry) (transfer full):
37546 * a #GList of the UNIX mounts.
37551 * g_unix_output_stream_get_close_fd:
37552 * @stream: a #GUnixOutputStream
37554 * Returns whether the file descriptor of @stream will be
37555 * closed when the stream is closed.
37557 * Returns: %TRUE if the file descriptor is closed when done
37563 * g_unix_output_stream_get_fd:
37564 * @stream: a #GUnixOutputStream
37566 * Return the UNIX file descriptor that the stream writes to.
37568 * Returns: The file descriptor of @stream
37574 * g_unix_output_stream_new:
37575 * @fd: a UNIX file descriptor
37576 * @close_fd: %TRUE to close the file descriptor when done
37578 * Creates a new #GUnixOutputStream for the given @fd.
37580 * If @close_fd, is %TRUE, the file descriptor will be closed when
37581 * the output stream is destroyed.
37583 * Returns: a new #GOutputStream
37588 * g_unix_output_stream_set_close_fd:
37589 * @stream: a #GUnixOutputStream
37590 * @close_fd: %TRUE to close the file descriptor when done
37592 * Sets whether the file descriptor of @stream shall be closed
37593 * when the stream is closed.
37600 * g_unix_socket_address_abstract_names_supported:
37602 * Checks if abstract UNIX domain socket names are supported.
37604 * Returns: %TRUE if supported, %FALSE otherwise
37610 * g_unix_socket_address_get_address_type:
37611 * @address: a #GInetSocketAddress
37613 * Gets @address's type.
37615 * Returns: a #GUnixSocketAddressType
37621 * g_unix_socket_address_get_is_abstract:
37622 * @address: a #GInetSocketAddress
37624 * Tests if @address is abstract.
37626 * Returns: %TRUE if the address is abstract, %FALSE otherwise
37628 * Deprecated: Use g_unix_socket_address_get_address_type()
37633 * g_unix_socket_address_get_path:
37634 * @address: a #GInetSocketAddress
37636 * Gets @address's path, or for abstract sockets the "name".
37638 * Guaranteed to be zero-terminated, but an abstract socket
37639 * may contain embedded zeros, and thus you should use
37640 * g_unix_socket_address_get_path_len() to get the true length
37643 * Returns: the path for @address
37649 * g_unix_socket_address_get_path_len:
37650 * @address: a #GInetSocketAddress
37652 * Gets the length of @address's path.
37654 * For details, see g_unix_socket_address_get_path().
37656 * Returns: the length of the path
37662 * g_unix_socket_address_new:
37663 * @path: the socket path
37665 * Creates a new #GUnixSocketAddress for @path.
37667 * To create abstract socket addresses, on systems that support that,
37668 * use g_unix_socket_address_new_abstract().
37670 * Returns: a new #GUnixSocketAddress
37676 * g_unix_socket_address_new_abstract:
37677 * @path: (array length=path_len) (element-type gchar): the abstract name
37678 * @path_len: the length of @path, or -1
37680 * Creates a new %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED
37681 * #GUnixSocketAddress for @path.
37683 * Returns: a new #GUnixSocketAddress
37684 * Deprecated: Use g_unix_socket_address_new_with_type().
37689 * g_unix_socket_address_new_with_type:
37690 * @path: (array length=path_len) (element-type gchar): the name
37691 * @path_len: the length of @path, or -1
37692 * @type: a #GUnixSocketAddressType
37694 * Creates a new #GUnixSocketAddress of type @type with name @path.
37696 * If @type is %G_UNIX_SOCKET_ADDRESS_PATH, this is equivalent to
37697 * calling g_unix_socket_address_new().
37699 * If @path_type is %G_UNIX_SOCKET_ADDRESS_ABSTRACT, then @path_len
37700 * bytes of @path will be copied to the socket's path, and only those
37701 * bytes will be considered part of the name. (If @path_len is -1,
37702 * then @path is assumed to be NUL-terminated.) For example, if @path
37703 * was "test", then calling g_socket_address_get_native_size() on the
37704 * returned socket would return 7 (2 bytes of overhead, 1 byte for the
37705 * abstract-socket indicator byte, and 4 bytes for the name "test").
37707 * If @path_type is %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED, then
37708 * @path_len bytes of @path will be copied to the socket's path, the
37709 * rest of the path will be padded with 0 bytes, and the entire
37710 * zero-padded buffer will be considered the name. (As above, if
37711 * @path_len is -1, then @path is assumed to be NUL-terminated.) In
37712 * this case, g_socket_address_get_native_size() will always return
37713 * the full size of a `struct sockaddr_un`, although
37714 * g_unix_socket_address_get_path_len() will still return just the
37717 * %G_UNIX_SOCKET_ADDRESS_ABSTRACT is preferred over
37718 * %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED for new programs. Of course,
37719 * when connecting to a server created by another process, you must
37720 * use the appropriate type corresponding to how that process created
37721 * its listening socket.
37723 * Returns: a new #GUnixSocketAddress
37729 * g_vfs_get_default:
37731 * Gets the default #GVfs for the system.
37733 * Returns: (transfer none): a #GVfs.
37738 * g_vfs_get_file_for_path:
37740 * @path: a string containing a VFS path.
37742 * Gets a #GFile for @path.
37744 * Returns: (transfer full): a #GFile.
37745 * Free the returned object with g_object_unref().
37750 * g_vfs_get_file_for_uri:
37752 * @uri: a string containing a URI
37754 * Gets a #GFile for @uri.
37756 * This operation never fails, but the returned object
37757 * might not support any I/O operation if the URI
37758 * is malformed or if the URI scheme is not supported.
37760 * Returns: (transfer full): a #GFile.
37761 * Free the returned object with g_object_unref().
37768 * Gets the local #GVfs for the system.
37770 * Returns: (transfer none): a #GVfs.
37775 * g_vfs_get_supported_uri_schemes:
37778 * Gets a list of URI schemes supported by @vfs.
37780 * Returns: (transfer none): a %NULL-terminated array of strings.
37781 * The returned array belongs to GIO and must
37782 * not be freed or modified.
37790 * Checks if the VFS is active.
37792 * Returns: %TRUE if construction of the @vfs was successful
37793 * and it is now active.
37798 * g_vfs_parse_name:
37800 * @parse_name: a string to be parsed by the VFS module.
37802 * This operation never fails, but the returned object might
37803 * not support any I/O operations if the @parse_name cannot
37804 * be parsed by the #GVfs module.
37806 * Returns: (transfer full): a #GFile for the given @parse_name.
37807 * Free the returned object with g_object_unref().
37812 * g_volume_can_eject:
37813 * @volume: a #GVolume
37815 * Checks if a volume can be ejected.
37817 * Returns: %TRUE if the @volume can be ejected. %FALSE otherwise
37822 * g_volume_can_mount:
37823 * @volume: a #GVolume
37825 * Checks if a volume can be mounted.
37827 * Returns: %TRUE if the @volume can be mounted. %FALSE otherwise
37833 * @volume: a #GVolume
37834 * @flags: flags affecting the unmount if required for eject
37835 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
37836 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL
37837 * @user_data: user data that gets passed to @callback
37839 * Ejects a volume. This is an asynchronous operation, and is
37840 * finished by calling g_volume_eject_finish() with the @volume
37841 * and #GAsyncResult returned in the @callback.
37843 * Deprecated: 2.22: Use g_volume_eject_with_operation() instead.
37848 * g_volume_eject_finish:
37849 * @volume: pointer to a #GVolume
37850 * @result: a #GAsyncResult
37851 * @error: a #GError location to store an error, or %NULL to ignore
37853 * Finishes ejecting a volume. If any errors occurred during the operation,
37854 * @error will be set to contain the errors and %FALSE will be returned.
37856 * Returns: %TRUE, %FALSE if operation failed
37857 * Deprecated: 2.22: Use g_volume_eject_with_operation_finish() instead.
37862 * g_volume_eject_with_operation:
37863 * @volume: a #GVolume
37864 * @flags: flags affecting the unmount if required for eject
37865 * @mount_operation: (allow-none): a #GMountOperation or %NULL to
37866 * avoid user interaction
37867 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
37868 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL
37869 * @user_data: user data passed to @callback
37871 * Ejects a volume. This is an asynchronous operation, and is
37872 * finished by calling g_volume_eject_with_operation_finish() with the @volume
37873 * and #GAsyncResult data returned in the @callback.
37880 * g_volume_eject_with_operation_finish:
37881 * @volume: a #GVolume
37882 * @result: a #GAsyncResult
37883 * @error: a #GError location to store the error occurring, or %NULL
37885 * Finishes ejecting a volume. If any errors occurred during the operation,
37886 * @error will be set to contain the errors and %FALSE will be returned.
37888 * Returns: %TRUE if the volume was successfully ejected. %FALSE otherwise
37894 * g_volume_enumerate_identifiers:
37895 * @volume: a #GVolume
37897 * Gets the kinds of [identifiers][volume-identifier] that @volume has.
37898 * Use g_volume_get_identifier() to obtain the identifiers themselves.
37900 * Returns: (array zero-terminated=1) (transfer full): a %NULL-terminated array
37901 * of strings containing kinds of identifiers. Use g_strfreev() to free.
37906 * g_volume_get_activation_root:
37907 * @volume: a #GVolume
37909 * Gets the activation root for a #GVolume if it is known ahead of
37910 * mount time. Returns %NULL otherwise. If not %NULL and if @volume
37911 * is mounted, then the result of g_mount_get_root() on the
37912 * #GMount object obtained from g_volume_get_mount() will always
37913 * either be equal or a prefix of what this function returns. In
37914 * other words, in code
37916 * |[<!-- language="C" -->
37918 * GFile *mount_root
37919 * GFile *volume_activation_root;
37921 * mount = g_volume_get_mount (volume); // mounted, so never NULL
37922 * mount_root = g_mount_get_root (mount);
37923 * volume_activation_root = g_volume_get_activation_root (volume); // assume not NULL
37925 * then the expression
37926 * |[<!-- language="C" -->
37927 * (g_file_has_prefix (volume_activation_root, mount_root) ||
37928 * g_file_equal (volume_activation_root, mount_root))
37930 * will always be %TRUE.
37932 * Activation roots are typically used in #GVolumeMonitor
37933 * implementations to find the underlying mount to shadow, see
37934 * g_mount_is_shadowed() for more details.
37936 * Returns: (nullable) (transfer full): the activation root of @volume
37937 * or %NULL. Use g_object_unref() to free.
37943 * g_volume_get_drive:
37944 * @volume: a #GVolume
37946 * Gets the drive for the @volume.
37948 * Returns: (transfer full): a #GDrive or %NULL if @volume is not
37949 * associated with a drive. The returned object should be unreffed
37950 * with g_object_unref() when no longer needed.
37955 * g_volume_get_icon:
37956 * @volume: a #GVolume
37958 * Gets the icon for @volume.
37960 * Returns: (transfer full): a #GIcon.
37961 * The returned object should be unreffed with g_object_unref()
37962 * when no longer needed.
37967 * g_volume_get_identifier:
37968 * @volume: a #GVolume
37969 * @kind: the kind of identifier to return
37971 * Gets the identifier of the given kind for @volume.
37972 * See the [introduction][volume-identifier] for more
37973 * information about volume identifiers.
37975 * Returns: a newly allocated string containing the
37976 * requested identfier, or %NULL if the #GVolume
37977 * doesn't have this kind of identifier
37982 * g_volume_get_mount:
37983 * @volume: a #GVolume
37985 * Gets the mount for the @volume.
37987 * Returns: (transfer full): a #GMount or %NULL if @volume isn't mounted.
37988 * The returned object should be unreffed with g_object_unref()
37989 * when no longer needed.
37994 * g_volume_get_name:
37995 * @volume: a #GVolume
37997 * Gets the name of @volume.
37999 * Returns: the name for the given @volume. The returned string should
38000 * be freed with g_free() when no longer needed.
38005 * g_volume_get_sort_key:
38006 * @volume: a #GVolume
38008 * Gets the sort key for @volume, if any.
38010 * Returns: Sorting key for @volume or %NULL if no such key is available
38016 * g_volume_get_symbolic_icon:
38017 * @volume: a #GVolume
38019 * Gets the symbolic icon for @volume.
38021 * Returns: (transfer full): a #GIcon.
38022 * The returned object should be unreffed with g_object_unref()
38023 * when no longer needed.
38029 * g_volume_get_uuid:
38030 * @volume: a #GVolume
38032 * Gets the UUID for the @volume. The reference is typically based on
38033 * the file system UUID for the volume in question and should be
38034 * considered an opaque string. Returns %NULL if there is no UUID
38037 * Returns: the UUID for @volume or %NULL if no UUID can be computed.
38038 * The returned string should be freed with g_free()
38039 * when no longer needed.
38044 * g_volume_monitor_adopt_orphan_mount:
38045 * @mount: a #GMount object to find a parent for
38047 * This function should be called by any #GVolumeMonitor
38048 * implementation when a new #GMount object is created that is not
38049 * associated with a #GVolume object. It must be called just before
38050 * emitting the @mount_added signal.
38052 * If the return value is not %NULL, the caller must associate the
38053 * returned #GVolume object with the #GMount. This involves returning
38054 * it in its g_mount_get_volume() implementation. The caller must
38055 * also listen for the "removed" signal on the returned object
38056 * and give up its reference when handling that signal
38058 * Similary, if implementing g_volume_monitor_adopt_orphan_mount(),
38059 * the implementor must take a reference to @mount and return it in
38060 * its g_volume_get_mount() implemented. Also, the implementor must
38061 * listen for the "unmounted" signal on @mount and give up its
38062 * reference upon handling that signal.
38064 * There are two main use cases for this function.
38066 * One is when implementing a user space file system driver that reads
38067 * blocks of a block device that is already represented by the native
38068 * volume monitor (for example a CD Audio file system driver). Such
38069 * a driver will generate its own #GMount object that needs to be
38070 * associated with the #GVolume object that represents the volume.
38072 * The other is for implementing a #GVolumeMonitor whose sole purpose
38073 * is to return #GVolume objects representing entries in the users
38074 * "favorite servers" list or similar.
38076 * Returns: (transfer full): the #GVolume object that is the parent for @mount or %NULL
38077 * if no wants to adopt the #GMount.
38078 * Deprecated: 2.20: Instead of using this function, #GVolumeMonitor
38079 * implementations should instead create shadow mounts with the URI of
38080 * the mount they intend to adopt. See the proxy volume monitor in
38081 * gvfs for an example of this. Also see g_mount_is_shadowed(),
38082 * g_mount_shadow() and g_mount_unshadow() functions.
38087 * g_volume_monitor_get:
38089 * Gets the volume monitor used by gio.
38091 * Returns: (transfer full): a reference to the #GVolumeMonitor used by gio. Call
38092 * g_object_unref() when done with it.
38097 * g_volume_monitor_get_connected_drives:
38098 * @volume_monitor: a #GVolumeMonitor.
38100 * Gets a list of drives connected to the system.
38102 * The returned list should be freed with g_list_free(), after
38103 * its elements have been unreffed with g_object_unref().
38105 * Returns: (element-type GDrive) (transfer full): a #GList of connected #GDrive objects.
38110 * g_volume_monitor_get_mount_for_uuid:
38111 * @volume_monitor: a #GVolumeMonitor.
38112 * @uuid: the UUID to look for
38114 * Finds a #GMount object by its UUID (see g_mount_get_uuid())
38116 * Returns: (transfer full): a #GMount or %NULL if no such mount is available.
38117 * Free the returned object with g_object_unref().
38122 * g_volume_monitor_get_mounts:
38123 * @volume_monitor: a #GVolumeMonitor.
38125 * Gets a list of the mounts on the system.
38127 * The returned list should be freed with g_list_free(), after
38128 * its elements have been unreffed with g_object_unref().
38130 * Returns: (element-type GMount) (transfer full): a #GList of #GMount objects.
38135 * g_volume_monitor_get_volume_for_uuid:
38136 * @volume_monitor: a #GVolumeMonitor.
38137 * @uuid: the UUID to look for
38139 * Finds a #GVolume object by its UUID (see g_volume_get_uuid())
38141 * Returns: (transfer full): a #GVolume or %NULL if no such volume is available.
38142 * Free the returned object with g_object_unref().
38147 * g_volume_monitor_get_volumes:
38148 * @volume_monitor: a #GVolumeMonitor.
38150 * Gets a list of the volumes on the system.
38152 * The returned list should be freed with g_list_free(), after
38153 * its elements have been unreffed with g_object_unref().
38155 * Returns: (element-type GVolume) (transfer full): a #GList of #GVolume objects.
38160 * g_volume_mount: (virtual mount_fn)
38161 * @volume: a #GVolume
38162 * @flags: flags affecting the operation
38163 * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction
38164 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
38165 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL
38166 * @user_data: user data that gets passed to @callback
38168 * Mounts a volume. This is an asynchronous operation, and is
38169 * finished by calling g_volume_mount_finish() with the @volume
38170 * and #GAsyncResult returned in the @callback.
38175 * g_volume_mount_finish:
38176 * @volume: a #GVolume
38177 * @result: a #GAsyncResult
38178 * @error: a #GError location to store an error, or %NULL to ignore
38180 * Finishes mounting a volume. If any errors occurred during the operation,
38181 * @error will be set to contain the errors and %FALSE will be returned.
38183 * If the mount operation succeeded, g_volume_get_mount() on @volume
38184 * is guaranteed to return the mount right after calling this
38185 * function; there's no need to listen for the 'mount-added' signal on
38188 * Returns: %TRUE, %FALSE if operation failed
38193 * g_volume_should_automount:
38194 * @volume: a #GVolume
38196 * Returns whether the volume should be automatically mounted.
38198 * Returns: %TRUE if the volume should be automatically mounted
38203 * g_win32_input_stream_get_close_handle:
38204 * @stream: a #GWin32InputStream
38206 * Returns whether the handle of @stream will be
38207 * closed when the stream is closed.
38209 * Returns: %TRUE if the handle is closed when done
38215 * g_win32_input_stream_get_handle:
38216 * @stream: a #GWin32InputStream
38218 * Return the Windows file handle that the stream reads from.
38220 * Returns: The file handle of @stream
38226 * g_win32_input_stream_new:
38227 * @handle: a Win32 file handle
38228 * @close_handle: %TRUE to close the handle when done
38230 * Creates a new #GWin32InputStream for the given @handle.
38232 * If @close_handle is %TRUE, the handle will be closed
38233 * when the stream is closed.
38235 * Note that "handle" here means a Win32 HANDLE, not a "file descriptor"
38236 * as used in the Windows C libraries.
38238 * Returns: a new #GWin32InputStream
38243 * g_win32_input_stream_set_close_handle:
38244 * @stream: a #GWin32InputStream
38245 * @close_handle: %TRUE to close the handle when done
38247 * Sets whether the handle of @stream shall be closed
38248 * when the stream is closed.
38255 * g_win32_output_stream_get_close_handle:
38256 * @stream: a #GWin32OutputStream
38258 * Returns whether the handle of @stream will be closed when the
38259 * stream is closed.
38261 * Returns: %TRUE if the handle is closed when done
38267 * g_win32_output_stream_get_handle:
38268 * @stream: a #GWin32OutputStream
38270 * Return the Windows handle that the stream writes to.
38272 * Returns: The handle descriptor of @stream
38278 * g_win32_output_stream_new:
38279 * @handle: a Win32 file handle
38280 * @close_handle: %TRUE to close the handle when done
38282 * Creates a new #GWin32OutputStream for the given @handle.
38284 * If @close_handle, is %TRUE, the handle will be closed when the
38285 * output stream is destroyed.
38287 * Returns: a new #GOutputStream
38293 * g_win32_output_stream_set_close_handle:
38294 * @stream: a #GWin32OutputStream
38295 * @close_handle: %TRUE to close the handle when done
38297 * Sets whether the handle of @stream shall be closed when the stream
38305 * g_zlib_compressor_get_file_info:
38306 * @compressor: a #GZlibCompressor
38308 * Returns the #GZlibCompressor:file-info property.
38310 * Returns: (transfer none): a #GFileInfo, or %NULL
38316 * g_zlib_compressor_new:
38317 * @format: The format to use for the compressed data
38318 * @level: compression level (0-9), -1 for default
38320 * Creates a new #GZlibCompressor.
38322 * Returns: a new #GZlibCompressor
38328 * g_zlib_compressor_set_file_info:
38329 * @compressor: a #GZlibCompressor
38330 * @file_info: (allow-none): a #GFileInfo
38332 * Sets @file_info in @compressor. If non-%NULL, and @compressor's
38333 * #GZlibCompressor:format property is %G_ZLIB_COMPRESSOR_FORMAT_GZIP,
38334 * it will be used to set the file name and modification time in
38335 * the GZIP header of the compressed data.
38337 * Note: it is an error to call this function while a compression is in
38338 * progress; it may only be called immediately after creation of @compressor,
38339 * or after resetting it with g_converter_reset().
38346 * g_zlib_decompressor_get_file_info:
38347 * @decompressor: a #GZlibDecompressor
38349 * Retrieves the #GFileInfo constructed from the GZIP header data
38350 * of compressed data processed by @compressor, or %NULL if @decompressor's
38351 * #GZlibDecompressor:format property is not %G_ZLIB_COMPRESSOR_FORMAT_GZIP,
38352 * or the header data was not fully processed yet, or it not present in the
38353 * data stream at all.
38355 * Returns: (transfer none): a #GFileInfo, or %NULL
38361 * g_zlib_decompressor_new:
38362 * @format: The format to use for the compressed data
38364 * Creates a new #GZlibDecompressor.
38366 * Returns: a new #GZlibDecompressor
38372 /************************************************************/
38373 /* THIS FILE IS GENERATED DO NOT EDIT */
38374 /************************************************************/