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.
3210 * @G_UNIX_MOUNT_TYPE_UNKNOWN: Unknown UNIX mount type.
3211 * @G_UNIX_MOUNT_TYPE_FLOPPY: Floppy disk UNIX mount type.
3212 * @G_UNIX_MOUNT_TYPE_CDROM: CDROM UNIX mount type.
3213 * @G_UNIX_MOUNT_TYPE_NFS: Network File System (NFS) UNIX mount type.
3214 * @G_UNIX_MOUNT_TYPE_ZIP: ZIP UNIX mount type.
3215 * @G_UNIX_MOUNT_TYPE_JAZ: JAZZ UNIX mount type.
3216 * @G_UNIX_MOUNT_TYPE_MEMSTICK: Memory Stick UNIX mount type.
3217 * @G_UNIX_MOUNT_TYPE_CF: Compact Flash UNIX mount type.
3218 * @G_UNIX_MOUNT_TYPE_SM: Smart Media UNIX mount type.
3219 * @G_UNIX_MOUNT_TYPE_SDMMC: SD/MMC UNIX mount type.
3220 * @G_UNIX_MOUNT_TYPE_IPOD: iPod UNIX mount type.
3221 * @G_UNIX_MOUNT_TYPE_CAMERA: Digital camera UNIX mount type.
3222 * @G_UNIX_MOUNT_TYPE_HD: Hard drive UNIX mount type.
3224 * Types of UNIX mounts.
3229 * GUnixOutputStream:close-fd:
3231 * Whether to close the file descriptor when the stream is closed.
3238 * GUnixOutputStream:fd:
3240 * The file descriptor that the stream writes to.
3247 * GUnixSocketAddress:
3249 * A UNIX-domain (local) socket address, corresponding to a
3250 * struct sockaddr_un.
3255 * GUnixSocketAddress:abstract:
3257 * Whether or not this is an abstract address
3259 * Deprecated: Use #GUnixSocketAddress:address-type, which
3260 * distinguishes between zero-padded and non-zero-padded
3261 * abstract addresses.
3268 * Emitted when the volume has been changed.
3275 * This signal is emitted when the #GVolume have been removed. If
3276 * the recipient is holding references to the object they should
3277 * release them so the object can be finalized.
3282 * GVolumeMonitor::drive-changed:
3283 * @volume_monitor: The volume monitor emitting the signal.
3284 * @drive: the drive that changed
3286 * Emitted when a drive changes.
3291 * GVolumeMonitor::drive-connected:
3292 * @volume_monitor: The volume monitor emitting the signal.
3293 * @drive: a #GDrive that was connected.
3295 * Emitted when a drive is connected to the system.
3300 * GVolumeMonitor::drive-disconnected:
3301 * @volume_monitor: The volume monitor emitting the signal.
3302 * @drive: a #GDrive that was disconnected.
3304 * Emitted when a drive is disconnected from the system.
3309 * GVolumeMonitor::drive-eject-button:
3310 * @volume_monitor: The volume monitor emitting the signal.
3311 * @drive: the drive where the eject button was pressed
3313 * Emitted when the eject button is pressed on @drive.
3320 * GVolumeMonitor::drive-stop-button:
3321 * @volume_monitor: The volume monitor emitting the signal.
3322 * @drive: the drive where the stop button was pressed
3324 * Emitted when the stop button is pressed on @drive.
3331 * GVolumeMonitor::mount-added:
3332 * @volume_monitor: The volume monitor emitting the signal.
3333 * @mount: a #GMount that was added.
3335 * Emitted when a mount is added.
3340 * GVolumeMonitor::mount-changed:
3341 * @volume_monitor: The volume monitor emitting the signal.
3342 * @mount: a #GMount that changed.
3344 * Emitted when a mount changes.
3349 * GVolumeMonitor::mount-pre-unmount:
3350 * @volume_monitor: The volume monitor emitting the signal.
3351 * @mount: a #GMount that is being unmounted.
3353 * Emitted when a mount is about to be removed.
3358 * GVolumeMonitor::mount-removed:
3359 * @volume_monitor: The volume monitor emitting the signal.
3360 * @mount: a #GMount that was removed.
3362 * Emitted when a mount is removed.
3367 * GVolumeMonitor::volume-added:
3368 * @volume_monitor: The volume monitor emitting the signal.
3369 * @volume: a #GVolume that was added.
3371 * Emitted when a mountable volume is added to the system.
3376 * GVolumeMonitor::volume-changed:
3377 * @volume_monitor: The volume monitor emitting the signal.
3378 * @volume: a #GVolume that changed.
3380 * Emitted when mountable volume is changed.
3385 * GVolumeMonitor::volume-removed:
3386 * @volume_monitor: The volume monitor emitting the signal.
3387 * @volume: a #GVolume that was removed.
3389 * Emitted when a mountable volume is removed from the system.
3394 * GWin32InputStream:close-handle:
3396 * Whether to close the file handle when the stream is closed.
3403 * GWin32InputStream:handle:
3405 * The handle that the stream reads from.
3412 * GWin32OutputStream:close-handle:
3414 * Whether to close the file handle when the stream is closed.
3421 * GWin32OutputStream:handle:
3423 * The file handle that the stream writes to.
3432 * Zlib decompression
3437 * GZlibCompressor:file-info:
3439 * If set to a non-%NULL #GFileInfo object, and #GZlibCompressor:format is
3440 * %G_ZLIB_COMPRESSOR_FORMAT_GZIP, the compressor will write the file name
3441 * and modification time from the file info to the GZIP header.
3448 * GZlibDecompressor:
3450 * Zlib decompression
3455 * GZlibDecompressor:file-info:
3457 * A #GFileInfo containing the information found in the GZIP header
3458 * of the data stream processed, or %NULL if the header was not yet
3459 * fully processed, is not present at all, or the compressor's
3460 * #GZlibDecompressor:format property is not %G_ZLIB_COMPRESSOR_FORMAT_GZIP.
3467 * G_TLS_DATABASE_PURPOSE_AUTHENTICATE_CLIENT:
3469 * The purpose used to verify the client certificate in a TLS connection.
3470 * Used by TLS servers.
3475 * G_TLS_DATABASE_PURPOSE_AUTHENTICATE_SERVER:
3477 * The purpose used to verify the server certificate in a TLS connection. This
3478 * is the most common purpose in use. Used by TLS clients.
3483 * G_TYPE_SETTINGS_SCHEMA:
3485 * A boxed #GType corresponding to #GSettingsSchema.
3492 * G_TYPE_SETTINGS_SCHEMA_SOURCE:
3494 * A boxed #GType corresponding to #GSettingsSchemaSource.
3501 * SECTION:_GFreedesktopDBus
3502 * @title: _GFreedesktopDBus
3503 * @short_description: Generated C code for the org.freedesktop.DBus D-Bus interface
3505 * 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.
3510 * SECTION:extensionpoints
3511 * @short_description: Extension Points
3513 * @see_also: [Extending GIO][extending-gio]
3515 * #GIOExtensionPoint provides a mechanism for modules to extend the
3516 * functionality of the library or application that loaded it in an
3517 * organized fashion.
3519 * An extension point is identified by a name, and it may optionally
3520 * require that any implementation must be of a certain type (or derived
3521 * thereof). Use g_io_extension_point_register() to register an
3522 * extension point, and g_io_extension_point_set_required_type() to
3523 * set a required type.
3525 * A module can implement an extension point by specifying the #GType
3526 * that implements the functionality. Additionally, each implementation
3527 * of an extension point has a name, and a priority. Use
3528 * g_io_extension_point_implement() to implement an extension point.
3530 * |[<!-- language="C" -->
3531 * GIOExtensionPoint *ep;
3533 * // Register an extension point
3534 * ep = g_io_extension_point_register ("my-extension-point");
3535 * g_io_extension_point_set_required_type (ep, MY_TYPE_EXAMPLE);
3538 * |[<!-- language="C" -->
3539 * // Implement an extension point
3540 * G_DEFINE_TYPE (MyExampleImpl, my_example_impl, MY_TYPE_EXAMPLE);
3541 * g_io_extension_point_implement ("my-extension-point",
3542 * my_example_impl_get_type (),
3547 * It is up to the code that registered the extension point how
3548 * it uses the implementations that have been associated with it.
3549 * Depending on the use case, it may use all implementations, or
3550 * only the one with the highest priority, or pick a specific
3553 * To avoid opening all modules just to find out what extension
3554 * points they implement, GIO makes use of a caching mechanism,
3555 * see [gio-querymodules][gio-querymodules].
3556 * You are expected to run this command after installing a
3559 * The `GIO_EXTRA_MODULES` environment variable can be used to
3560 * specify additional directories to automatically load modules
3561 * from. This environment variable has the same syntax as the
3562 * `PATH`. If two modules have the same base name in different
3563 * directories, then the latter one will be ignored. If additional
3564 * directories are specified GIO will load modules from the built-in
3572 * @short_description: An action interface
3573 * @include: gio/gio.h
3575 * #GAction represents a single named action.
3577 * The main interface to an action is that it can be activated with
3578 * g_action_activate(). This results in the 'activate' signal being
3579 * emitted. An activation has a #GVariant parameter (which may be
3580 * %NULL). The correct type for the parameter is determined by a static
3581 * parameter type (which is given at construction time).
3583 * An action may optionally have a state, in which case the state may be
3584 * set with g_action_change_state(). This call takes a #GVariant. The
3585 * correct type for the state is determined by a static state type
3586 * (which is given at construction time).
3588 * The state may have a hint associated with it, specifying its valid
3591 * #GAction is merely the interface to the concept of an action, as
3592 * described above. Various implementations of actions exist, including
3595 * In all cases, the implementing class is responsible for storing the
3596 * name of the action, the parameter type, the enabled state, the
3597 * optional state type and the state and emitting the appropriate
3598 * signals when these change. The implementor responsible for filtering
3599 * calls to g_action_activate() and g_action_change_state() for type
3600 * safety and for the state being enabled.
3602 * Probably the only useful thing to do with a #GAction is to put it
3603 * inside of a #GSimpleActionGroup.
3608 * SECTION:gactiongroup
3609 * @title: GActionGroup
3610 * @short_description: A group of actions
3611 * @include: gio/gio.h
3612 * @see_also: #GAction
3614 * #GActionGroup represents a group of actions. Actions can be used to
3615 * expose functionality in a structured way, either from one part of a
3616 * program to another, or to the outside world. Action groups are often
3617 * used together with a #GMenuModel that provides additional
3618 * representation data for displaying the actions to the user, e.g. in
3621 * The main way to interact with the actions in a GActionGroup is to
3622 * activate them with g_action_group_activate_action(). Activating an
3623 * action may require a #GVariant parameter. The required type of the
3624 * parameter can be inquired with g_action_group_get_action_parameter_type().
3625 * Actions may be disabled, see g_action_group_get_action_enabled().
3626 * Activating a disabled action has no effect.
3628 * Actions may optionally have a state in the form of a #GVariant. The
3629 * current state of an action can be inquired with
3630 * g_action_group_get_action_state(). Activating a stateful action may
3631 * change its state, but it is also possible to set the state by calling
3632 * g_action_group_change_action_state().
3634 * As typical example, consider a text editing application which has an
3635 * option to change the current font to 'bold'. A good way to represent
3636 * this would be a stateful action, with a boolean state. Activating the
3637 * action would toggle the state.
3639 * Each action in the group has a unique name (which is a string). All
3640 * method calls, except g_action_group_list_actions() take the name of
3641 * an action as an argument.
3643 * The #GActionGroup API is meant to be the 'public' API to the action
3644 * group. The calls here are exactly the interaction that 'external
3645 * forces' (eg: UI, incoming D-Bus messages, etc.) are supposed to have
3646 * with actions. 'Internal' APIs (ie: ones meant only to be accessed by
3647 * the action group implementation) are found on subclasses. This is
3648 * why you will find - for example - g_action_group_get_action_enabled()
3649 * but not an equivalent set() call.
3651 * Signals are emitted on the action group in response to state changes
3652 * on individual actions.
3654 * Implementations of #GActionGroup should provide implementations for
3655 * the virtual functions g_action_group_list_actions() and
3656 * g_action_group_query_action(). The other virtual functions should
3657 * not be implemented - their "wrappers" are actually implemented with
3658 * calls to g_action_group_query_action().
3663 * SECTION:gactiongroupexporter
3664 * @title: GActionGroup exporter
3665 * @include: gio/gio.h
3666 * @short_description: Export GActionGroups on D-Bus
3667 * @see_also: #GActionGroup, #GDBusActionGroup
3669 * These functions support exporting a #GActionGroup on D-Bus.
3670 * The D-Bus interface that is used is a private implementation
3673 * To access an exported #GActionGroup remotely, use
3674 * g_dbus_action_group_get() to obtain a #GDBusActionGroup.
3679 * SECTION:gactionmap
3680 * @title: GActionMap
3681 * @include: gio/gio.h
3682 * @short_description: Interface for action containers
3684 * The GActionMap interface is implemented by #GActionGroup
3685 * implementations that operate by containing a number of
3686 * named #GAction instances, such as #GSimpleActionGroup.
3688 * One useful application of this interface is to map the
3689 * names of actions from various action groups to unique,
3690 * prefixed names (e.g. by prepending "app." or "win.").
3691 * This is the motivation for the 'Map' part of the interface
3700 * @short_description: Application information and launch contexts
3701 * @include: gio/gio.h
3702 * @see_also: #GAppInfoMonitor
3704 * #GAppInfo and #GAppLaunchContext are used for describing and launching
3705 * applications installed on the system.
3707 * As of GLib 2.20, URIs will always be converted to POSIX paths
3708 * (using g_file_get_path()) when using g_app_info_launch() even if
3709 * the application requested an URI and not a POSIX path. For example
3710 * for an desktop-file based application with Exec key `totem
3711 * %U` and a single URI, `sftp://foo/file.avi`, then
3712 * `/home/user/.gvfs/sftp on foo/file.avi` will be passed. This will
3713 * only work if a set of suitable GIO extensions (such as gvfs 2.26
3714 * compiled with FUSE support), is available and operational; if this
3715 * is not the case, the URI will be passed unmodified to the application.
3716 * Some URIs, such as `mailto:`, of course cannot be mapped to a POSIX
3717 * path (in gvfs there's no FUSE mount for it); such URIs will be
3718 * passed unmodified to the application.
3720 * Specifically for gvfs 2.26 and later, the POSIX URI will be mapped
3721 * back to the GIO URI in the #GFile constructors (since gvfs
3722 * implements the #GVfs extension point). As such, if the application
3723 * needs to examine the URI, it needs to use g_file_get_uri() or
3724 * similar on #GFile. In other words, an application cannot assume
3725 * that the URI passed to e.g. g_file_new_for_commandline_arg() is
3726 * equal to the result of g_file_get_uri(). The following snippet
3733 * file = g_file_new_for_commandline_arg (uri_from_commandline);
3735 * uri = g_file_get_uri (file);
3736 * strcmp (uri, uri_from_commandline) == 0;
3739 * if (g_file_has_uri_scheme (file, "cdda"))
3741 * // do something special with uri
3743 * g_object_unref (file);
3746 * This code will work when both `cdda://sr0/Track 1.wav` and
3747 * `/home/user/.gvfs/cdda on sr0/Track 1.wav` is passed to the
3748 * application. It should be noted that it's generally not safe
3749 * for applications to rely on the format of a particular URIs.
3750 * Different launcher applications (e.g. file managers) may have
3751 * different ideas of what a given URI means.
3756 * SECTION:gappinfomonitor
3757 * @short_description: Monitor application information for changes
3759 * #GAppInfoMonitor is a very simple object used for monitoring the app
3760 * info database for changes (ie: newly installed or removed
3763 * Call g_app_info_monitor_get() to get a #GAppInfoMonitor and connect
3764 * to the "changed" signal.
3766 * In the usual case, applications should try to make note of the change
3767 * (doing things like invalidating caches) but not act on it. In
3768 * particular, applications should avoid making calls to #GAppInfo APIs
3769 * in response to the change signal, deferring these until the time that
3770 * the data is actually required. The exception to this case is when
3771 * application information is actually being displayed on the screen
3772 * (eg: during a search or when the list of all applications is shown).
3773 * The reason for this is that changes to the list of installed
3774 * applications often come in groups (like during system updates) and
3775 * rescanning the list on every change is pointless and expensive.
3782 * SECTION:gapplication
3783 * @title: GApplication
3784 * @short_description: Core application class
3785 * @include: gio/gio.h
3787 * A #GApplication is the foundation of an application. It wraps some
3788 * low-level platform-specific services and is intended to act as the
3789 * foundation for higher-level application classes such as
3790 * #GtkApplication or #MxApplication. In general, you should not use
3791 * this class outside of a higher level framework.
3793 * GApplication provides convenient life cycle management by maintaining
3794 * a "use count" for the primary application instance. The use count can
3795 * be changed using g_application_hold() and g_application_release(). If
3796 * it drops to zero, the application exits. Higher-level classes such as
3797 * #GtkApplication employ the use count to ensure that the application
3798 * stays alive as long as it has any opened windows.
3800 * Another feature that GApplication (optionally) provides is process
3801 * uniqueness. Applications can make use of this functionality by
3802 * providing a unique application ID. If given, only one application
3803 * with this ID can be running at a time per session. The session
3804 * concept is platform-dependent, but corresponds roughly to a graphical
3805 * desktop login. When your application is launched again, its
3806 * arguments are passed through platform communication to the already
3807 * running program. The already running instance of the program is
3808 * called the "primary instance"; for non-unique applications this is
3809 * the always the current instance. On Linux, the D-Bus session bus
3810 * is used for communication.
3812 * The use of #GApplication differs from some other commonly-used
3813 * uniqueness libraries (such as libunique) in important ways. The
3814 * application is not expected to manually register itself and check
3815 * if it is the primary instance. Instead, the main() function of a
3816 * #GApplication should do very little more than instantiating the
3817 * application instance, possibly connecting signal handlers, then
3818 * calling g_application_run(). All checks for uniqueness are done
3819 * internally. If the application is the primary instance then the
3820 * startup signal is emitted and the mainloop runs. If the application
3821 * is not the primary instance then a signal is sent to the primary
3822 * instance and g_application_run() promptly returns. See the code
3825 * If used, the expected form of an application identifier is very close
3827 * [DBus bus name](http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-interface).
3828 * Examples include: "com.example.MyApp", "org.example.internal-apps.Calculator".
3829 * For details on valid application identifiers, see g_application_id_is_valid().
3831 * On Linux, the application identifier is claimed as a well-known bus name
3832 * on the user's session bus. This means that the uniqueness of your
3833 * application is scoped to the current session. It also means that your
3834 * application may provide additional services (through registration of other
3835 * object paths) at that bus name. The registration of these object paths
3836 * should be done with the shared GDBus session bus. Note that due to the
3837 * internal architecture of GDBus, method calls can be dispatched at any time
3838 * (even if a main loop is not running). For this reason, you must ensure that
3839 * any object paths that you wish to register are registered before #GApplication
3840 * attempts to acquire the bus name of your application (which happens in
3841 * g_application_register()). Unfortunately, this means that you cannot use
3842 * g_application_get_is_remote() to decide if you want to register object paths.
3844 * GApplication also implements the #GActionGroup and #GActionMap
3845 * interfaces and lets you easily export actions by adding them with
3846 * g_action_map_add_action(). When invoking an action by calling
3847 * g_action_group_activate_action() on the application, it is always
3848 * invoked in the primary instance. The actions are also exported on
3849 * the session bus, and GIO provides the #GDBusActionGroup wrapper to
3850 * conveniently access them remotely. GIO provides a #GDBusMenuModel wrapper
3851 * for remote access to exported #GMenuModels.
3853 * There is a number of different entry points into a GApplication:
3855 * - via 'Activate' (i.e. just starting the application)
3857 * - via 'Open' (i.e. opening some files)
3859 * - by handling a command-line
3861 * - via activating an action
3863 * The #GApplication::startup signal lets you handle the application
3864 * initialization for all of these in a single place.
3866 * Regardless of which of these entry points is used to start the
3867 * application, GApplication passes some "platform data from the
3868 * launching instance to the primary instance, in the form of a
3869 * #GVariant dictionary mapping strings to variants. To use platform
3870 * data, override the @before_emit or @after_emit virtual functions
3871 * in your #GApplication subclass. When dealing with
3872 * #GApplicationCommandLine objects, the platform data is
3873 * directly available via g_application_command_line_get_cwd(),
3874 * g_application_command_line_get_environ() and
3875 * g_application_command_line_get_platform_data().
3877 * As the name indicates, the platform data may vary depending on the
3878 * operating system, but it always includes the current directory (key
3879 * "cwd"), and optionally the environment (ie the set of environment
3880 * variables and their values) of the calling process (key "environ").
3881 * The environment is only added to the platform data if the
3882 * %G_APPLICATION_SEND_ENVIRONMENT flag is set. #GApplication subclasses
3883 * can add their own platform data by overriding the @add_platform_data
3884 * virtual function. For instance, #GtkApplication adds startup notification
3887 * To parse commandline arguments you may handle the
3888 * #GApplication::command-line signal or override the local_command_line()
3889 * vfunc, to parse them in either the primary instance or the local instance,
3892 * For an example of opening files with a GApplication, see
3893 * [gapplication-example-open.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-open.c).
3895 * For an example of using actions with GApplication, see
3896 * [gapplication-example-actions.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-actions.c).
3898 * For an example of using extra D-Bus hooks with GApplication, see
3899 * [gapplication-example-dbushooks.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-dbushooks.c).
3904 * SECTION:gapplicationcommandline
3905 * @title: GApplicationCommandLine
3906 * @short_description: A command-line invocation of an application
3907 * @include: gio/gio.h
3908 * @see_also: #GApplication
3910 * #GApplicationCommandLine represents a command-line invocation of
3911 * an application. It is created by #GApplication and emitted
3912 * in the #GApplication::command-line signal and virtual function.
3914 * The class contains the list of arguments that the program was invoked
3915 * with. It is also possible to query if the commandline invocation was
3916 * local (ie: the current process is running in direct response to the
3917 * invocation) or remote (ie: some other process forwarded the
3918 * commandline to this process).
3920 * The GApplicationCommandLine object can provide the @argc and @argv
3921 * parameters for use with the #GOptionContext command-line parsing API,
3922 * with the g_application_command_line_get_arguments() function. See
3923 * [gapplication-example-cmdline3.c][gapplication-example-cmdline3]
3926 * The exit status of the originally-invoked process may be set and
3927 * messages can be printed to stdout or stderr of that process. The
3928 * lifecycle of the originally-invoked process is tied to the lifecycle
3929 * of this object (ie: the process exits when the last reference is
3932 * The main use for #GApplicationCommandLine (and the
3933 * #GApplication::command-line signal) is 'Emacs server' like use cases:
3934 * You can set the `EDITOR` environment variable to have e.g. git use
3935 * your favourite editor to edit commit messages, and if you already
3936 * have an instance of the editor running, the editing will happen
3937 * in the running instance, instead of opening a new one. An important
3938 * aspect of this use case is that the process that gets started by git
3939 * does not return until the editing is done.
3941 * Normally, the commandline is completely handled in the
3942 * #GApplication::command-line handler. The launching instance exits
3943 * once the signal handler in the primary instance has returned, and
3944 * the return value of the signal handler becomes the exit status
3945 * of the launching instance.
3946 * |[<!-- language="C" -->
3948 * command_line (GApplication *application,
3949 * GApplicationCommandLine *cmdline)
3955 * argv = g_application_command_line_get_arguments (cmdline, &argc);
3957 * g_application_command_line_print (cmdline,
3958 * "This text is written back\n"
3959 * "to stdout of the caller\n");
3961 * for (i = 0; i < argc; i++)
3962 * g_print ("argument %d: %s\n", i, argv[i]);
3964 * g_strfreev (argv);
3969 * The complete example can be found here:
3970 * [gapplication-example-cmdline.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-cmdline.c)
3972 * In more complicated cases, the handling of the comandline can be
3973 * split between the launcher and the primary instance.
3974 * |[<!-- language="C" -->
3976 * test_local_cmdline (GApplication *application,
3977 * gchar ***arguments,
3978 * gint *exit_status)
3983 * argv = *arguments;
3988 * if (g_str_has_prefix (argv[i], "--local-"))
3990 * g_print ("handling argument %s locally\n", argv[i]);
3992 * for (j = i; argv[j]; j++)
3993 * argv[j] = argv[j + 1];
3997 * g_print ("not handling argument %s locally\n", argv[i]);
4008 * test_application_class_init (TestApplicationClass *class)
4010 * G_APPLICATION_CLASS (class)->local_command_line = test_local_cmdline;
4015 * In this example of split commandline handling, options that start
4016 * with `--local-` are handled locally, all other options are passed
4017 * to the #GApplication::command-line handler which runs in the primary
4020 * The complete example can be found here:
4021 * [gapplication-example-cmdline2.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-cmdline2.c)
4023 * If handling the commandline requires a lot of work, it may
4024 * be better to defer it.
4025 * |[<!-- language="C" -->
4027 * my_cmdline_handler (gpointer data)
4029 * GApplicationCommandLine *cmdline = data;
4031 * // do the heavy lifting in an idle
4033 * g_application_command_line_set_exit_status (cmdline, 0);
4034 * g_object_unref (cmdline); // this releases the application
4036 * return G_SOURCE_REMOVE;
4040 * command_line (GApplication *application,
4041 * GApplicationCommandLine *cmdline)
4043 * // keep the application running until we are done with this commandline
4044 * g_application_hold (application);
4046 * g_object_set_data_full (G_OBJECT (cmdline),
4047 * "application", application,
4048 * (GDestroyNotify)g_application_release);
4050 * g_object_ref (cmdline);
4051 * g_idle_add (my_cmdline_handler, cmdline);
4056 * In this example the commandline is not completely handled before
4057 * the #GApplication::command-line handler returns. Instead, we keep
4058 * a reference to the #GApplicationCommandLine object and handle it
4059 * later (in this example, in an idle). Note that it is necessary to
4060 * hold the application until you are done with the commandline.
4062 * The complete example can be found here:
4063 * [gapplication-example-cmdline3.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-cmdline3.c)
4068 * SECTION:gasyncinitable
4069 * @short_description: Asynchronously failable object initialization interface
4070 * @include: gio/gio.h
4071 * @see_also: #GInitable
4073 * This is the asynchronous version of #GInitable; it behaves the same
4074 * in all ways except that initialization is asynchronous. For more details
4075 * see the descriptions on #GInitable.
4077 * A class may implement both the #GInitable and #GAsyncInitable interfaces.
4079 * Users of objects implementing this are not intended to use the interface
4080 * method directly; instead it will be used automatically in various ways.
4081 * For C applications you generally just call g_async_initable_new_async()
4082 * directly, or indirectly via a foo_thing_new_async() wrapper. This will call
4083 * g_async_initable_init_async() under the cover, calling back with %NULL and
4084 * a set %GError on failure.
4086 * A typical implementation might look something like this:
4088 * |[<!-- language="C" -->
4096 * _foo_ready_cb (Foo *self)
4100 * self->priv->state = INITIALIZED;
4102 * for (l = self->priv->init_results; l != NULL; l = l->next)
4104 * GTask *task = l->data;
4106 * if (self->priv->success)
4107 * g_task_return_boolean (task, TRUE);
4109 * g_task_return_new_error (task, ...);
4110 * g_object_unref (task);
4113 * g_list_free (self->priv->init_results);
4114 * self->priv->init_results = NULL;
4118 * foo_init_async (GAsyncInitable *initable,
4120 * GCancellable *cancellable,
4121 * GAsyncReadyCallback callback,
4122 * gpointer user_data)
4124 * Foo *self = FOO (initable);
4127 * task = g_task_new (initable, cancellable, callback, user_data);
4129 * switch (self->priv->state)
4131 * case NOT_INITIALIZED:
4132 * _foo_get_ready (self);
4133 * self->priv->init_results = g_list_append (self->priv->init_results,
4135 * self->priv->state = INITIALIZING;
4137 * case INITIALIZING:
4138 * self->priv->init_results = g_list_append (self->priv->init_results,
4142 * if (!self->priv->success)
4143 * g_task_return_new_error (task, ...);
4145 * g_task_return_boolean (task, TRUE);
4146 * g_object_unref (task);
4152 * foo_init_finish (GAsyncInitable *initable,
4153 * GAsyncResult *result,
4156 * g_return_val_if_fail (g_task_is_valid (result, initable), FALSE);
4158 * return g_task_propagate_boolean (G_TASK (result), error);
4162 * foo_async_initable_iface_init (gpointer g_iface,
4165 * GAsyncInitableIface *iface = g_iface;
4167 * iface->init_async = foo_init_async;
4168 * iface->init_finish = foo_init_finish;
4175 * SECTION:gasyncresult
4176 * @short_description: Asynchronous Function Results
4177 * @include: gio/gio.h
4180 * Provides a base class for implementing asynchronous function results.
4182 * Asynchronous operations are broken up into two separate operations
4183 * which are chained together by a #GAsyncReadyCallback. To begin
4184 * an asynchronous operation, provide a #GAsyncReadyCallback to the
4185 * asynchronous function. This callback will be triggered when the
4186 * operation has completed, and will be passed a #GAsyncResult instance
4187 * filled with the details of the operation's success or failure, the
4188 * object the asynchronous function was started for and any error codes
4189 * returned. The asynchronous callback function is then expected to call
4190 * the corresponding "_finish()" function, passing the object the
4191 * function was called for, the #GAsyncResult instance, and (optionally)
4192 * an @error to grab any error conditions that may have occurred.
4194 * The "_finish()" function for an operation takes the generic result
4195 * (of type #GAsyncResult) and returns the specific result that the
4196 * operation in question yields (e.g. a #GFileEnumerator for a
4197 * "enumerate children" operation). If the result or error status of the
4198 * operation is not needed, there is no need to call the "_finish()"
4199 * function; GIO will take care of cleaning up the result and error
4200 * information after the #GAsyncReadyCallback returns. You can pass
4201 * %NULL for the #GAsyncReadyCallback if you don't need to take any
4202 * action at all after the operation completes. Applications may also
4203 * take a reference to the #GAsyncResult and call "_finish()" later;
4204 * however, the "_finish()" function may be called at most once.
4206 * Example of a typical asynchronous operation flow:
4207 * |[<!-- language="C" -->
4208 * void _theoretical_frobnitz_async (Theoretical *t,
4210 * GAsyncReadyCallback cb,
4213 * gboolean _theoretical_frobnitz_finish (Theoretical *t,
4214 * GAsyncResult *res,
4218 * frobnitz_result_func (GObject *source_object,
4219 * GAsyncResult *res,
4220 * gpointer user_data)
4222 * gboolean success = FALSE;
4224 * success = _theoretical_frobnitz_finish (source_object, res, NULL);
4227 * g_printf ("Hurray!\n");
4229 * g_printf ("Uh oh!\n");
4235 * int main (int argc, void *argv[])
4239 * _theoretical_frobnitz_async (theoretical_data,
4241 * frobnitz_result_func,
4248 * The callback for an asynchronous operation is called only once, and is
4249 * always called, even in the case of a cancelled operation. On cancellation
4250 * the result is a %G_IO_ERROR_CANCELLED error.
4252 * ## I/O Priority # {#io-priority}
4254 * Many I/O-related asynchronous operations have a priority parameter,
4255 * which is used in certain cases to determine the order in which
4256 * operations are executed. They are not used to determine system-wide
4257 * I/O scheduling. Priorities are integers, with lower numbers indicating
4258 * higher priority. It is recommended to choose priorities between
4259 * %G_PRIORITY_LOW and %G_PRIORITY_HIGH, with %G_PRIORITY_DEFAULT
4265 * SECTION:gbufferedinputstream
4266 * @short_description: Buffered Input Stream
4267 * @include: gio/gio.h
4268 * @see_also: #GFilterInputStream, #GInputStream
4270 * Buffered input stream implements #GFilterInputStream and provides
4271 * for buffered reads.
4273 * By default, #GBufferedInputStream's buffer size is set at 4 kilobytes.
4275 * To create a buffered input stream, use g_buffered_input_stream_new(),
4276 * or g_buffered_input_stream_new_sized() to specify the buffer's size at
4279 * To get the size of a buffer within a buffered input stream, use
4280 * g_buffered_input_stream_get_buffer_size(). To change the size of a
4281 * buffered input stream's buffer, use
4282 * g_buffered_input_stream_set_buffer_size(). Note that the buffer's size
4283 * cannot be reduced below the size of the data within the buffer.
4288 * SECTION:gbufferedoutputstream
4289 * @short_description: Buffered Output Stream
4290 * @include: gio/gio.h
4291 * @see_also: #GFilterOutputStream, #GOutputStream
4293 * Buffered output stream implements #GFilterOutputStream and provides
4294 * for buffered writes.
4296 * By default, #GBufferedOutputStream's buffer size is set at 4 kilobytes.
4298 * To create a buffered output stream, use g_buffered_output_stream_new(),
4299 * or g_buffered_output_stream_new_sized() to specify the buffer's size
4302 * To get the size of a buffer within a buffered input stream, use
4303 * g_buffered_output_stream_get_buffer_size(). To change the size of a
4304 * buffered output stream's buffer, use
4305 * g_buffered_output_stream_set_buffer_size(). Note that the buffer's
4306 * size cannot be reduced below the size of the data within the buffer.
4311 * SECTION:gbytesicon
4312 * @short_description: An icon stored in memory as a GBytes
4313 * @include: gio/gio.h
4314 * @see_also: #GIcon, #GLoadableIcon, #GBytes
4316 * #GBytesIcon specifies an image held in memory in a common format (usually
4317 * png) to be used as icon.
4324 * SECTION:gcancellable
4325 * @short_description: Thread-safe Operation Cancellation Stack
4326 * @include: gio/gio.h
4328 * GCancellable is a thread-safe operation cancellation stack used
4329 * throughout GIO to allow for cancellation of synchronous and
4330 * asynchronous operations.
4335 * SECTION:gcharsetconverter
4336 * @short_description: Convert between charsets
4337 * @include: gio/gio.h
4339 * #GCharsetConverter is an implementation of #GConverter based on
4345 * SECTION:gcontenttype
4346 * @short_description: Platform-specific content typing
4347 * @include: gio/gio.h
4349 * A content type is a platform specific string that defines the type
4350 * of a file. On UNIX it is a
4351 * [mime type](http://www.wikipedia.org/wiki/Internet_media_type)
4352 * like "text/plain" or "image/png".
4353 * On Win32 it is an extension string like ".doc", ".txt" or a perceived
4354 * string like "audio". Such strings can be looked up in the registry at
4355 * HKEY_CLASSES_ROOT.
4360 * SECTION:gconverter
4361 * @short_description: Data conversion interface
4362 * @include: gio/gio.h
4363 * @see_also: #GInputStream, #GOutputStream
4365 * #GConverter is implemented by objects that convert
4366 * binary data in various ways. The conversion can be
4367 * stateful and may fail at any place.
4369 * Some example conversions are: character set conversion,
4370 * compression, decompression and regular expression
4378 * SECTION:gconverterinputstream
4379 * @short_description: Converter Input Stream
4380 * @include: gio/gio.h
4381 * @see_also: #GInputStream, #GConverter
4383 * Converter input stream implements #GInputStream and allows
4384 * conversion of data of various types during reading.
4386 * As of GLib 2.34, #GConverterInputStream implements
4387 * #GPollableInputStream.
4392 * SECTION:gconverteroutputstream
4393 * @short_description: Converter Output Stream
4394 * @include: gio/gio.h
4395 * @see_also: #GOutputStream, #GConverter
4397 * Converter output stream implements #GOutputStream and allows
4398 * conversion of data of various types during reading.
4400 * As of GLib 2.34, #GConverterOutputStream implements
4401 * #GPollableOutputStream.
4406 * SECTION:gcredentials
4407 * @short_description: An object containing credentials
4408 * @include: gio/gio.h
4410 * The #GCredentials type is a reference-counted wrapper for native
4411 * credentials. This information is typically used for identifying,
4412 * authenticating and authorizing other processes.
4414 * Some operating systems supports looking up the credentials of the
4415 * remote peer of a communication endpoint - see e.g.
4416 * g_socket_get_credentials().
4418 * Some operating systems supports securely sending and receiving
4419 * credentials over a Unix Domain Socket, see
4420 * #GUnixCredentialsMessage, g_unix_connection_send_credentials() and
4421 * g_unix_connection_receive_credentials() for details.
4423 * On Linux, the native credential type is a struct ucred - see the
4424 * unix(7) man page for details. This corresponds to
4425 * %G_CREDENTIALS_TYPE_LINUX_UCRED.
4427 * On FreeBSD, Debian GNU/kFreeBSD, and GNU/Hurd, the native
4428 * credential type is a struct cmsgcred. This corresponds
4429 * to %G_CREDENTIALS_TYPE_FREEBSD_CMSGCRED.
4431 * On NetBSD, the native credential type is a struct unpcbid.
4432 * This corresponds to %G_CREDENTIALS_TYPE_NETBSD_UNPCBID.
4434 * On OpenBSD, the native credential type is a struct sockpeercred.
4435 * This corresponds to %G_CREDENTIALS_TYPE_OPENBSD_SOCKPEERCRED.
4437 * On Solaris (including OpenSolaris and its derivatives), the native
4438 * credential type is a ucred_t. This corresponds to
4439 * %G_CREDENTIALS_TYPE_SOLARIS_UCRED.
4444 * SECTION:gdatainputstream
4445 * @short_description: Data Input Stream
4446 * @include: gio/gio.h
4447 * @see_also: #GInputStream
4449 * Data input stream implements #GInputStream and includes functions for
4450 * reading structured data directly from a binary input stream.
4455 * SECTION:gdataoutputstream
4456 * @short_description: Data Output Stream
4457 * @include: gio/gio.h
4458 * @see_also: #GOutputStream
4460 * Data output stream implements #GOutputStream and includes functions for
4461 * writing data directly to an output stream.
4466 * SECTION:gdbusactiongroup
4467 * @title: GDBusActionGroup
4468 * @short_description: A D-Bus GActionGroup implementation
4469 * @include: gio/gio.h
4470 * @see_also: [GActionGroup exporter][gio-GActionGroup-exporter]
4472 * #GDBusActionGroup is an implementation of the #GActionGroup
4473 * interface that can be used as a proxy for an action group
4474 * that is exported over D-Bus with g_dbus_connection_export_action_group().
4479 * SECTION:gdbusaddress
4480 * @title: D-Bus Addresses
4481 * @short_description: D-Bus connection endpoints
4482 * @include: gio/gio.h
4484 * Routines for working with D-Bus addresses. A D-Bus address is a string
4485 * like "unix:tmpdir=/tmp/my-app-name". The exact format of addresses
4486 * is explained in detail in the [D-Bus specification](http://dbus.freedesktop.org/doc/dbus-specification.html\#addresses).
4491 * SECTION:gdbusauthobserver
4492 * @short_description: Object used for authenticating connections
4493 * @include: gio/gio.h
4495 * The #GDBusAuthObserver type provides a mechanism for participating
4496 * in how a #GDBusServer (or a #GDBusConnection) authenticates remote
4497 * peers. Simply instantiate a #GDBusAuthObserver and connect to the
4498 * signals you are interested in. Note that new signals may be added
4501 * ## Controlling Authentication # {#auth-observer}
4503 * For example, if you only want to allow D-Bus connections from
4504 * processes owned by the same uid as the server, you would use a
4505 * signal handler like the following:
4507 * |[<!-- language="C" -->
4509 * on_authorize_authenticated_peer (GDBusAuthObserver *observer,
4510 * GIOStream *stream,
4511 * GCredentials *credentials,
4512 * gpointer user_data)
4514 * gboolean authorized;
4516 * authorized = FALSE;
4517 * if (credentials != NULL)
4519 * GCredentials *own_credentials;
4520 * own_credentials = g_credentials_new ();
4521 * if (g_credentials_is_same_user (credentials, own_credentials, NULL))
4522 * authorized = TRUE;
4523 * g_object_unref (own_credentials);
4526 * return authorized;
4533 * SECTION:gdbusconnection
4534 * @short_description: D-Bus Connections
4535 * @include: gio/gio.h
4537 * The #GDBusConnection type is used for D-Bus connections to remote
4538 * peers such as a message buses. It is a low-level API that offers a
4539 * lot of flexibility. For instance, it lets you establish a connection
4540 * over any transport that can by represented as an #GIOStream.
4542 * This class is rarely used directly in D-Bus clients. If you are writing
4543 * a D-Bus client, it is often easier to use the g_bus_own_name(),
4544 * g_bus_watch_name() or g_dbus_proxy_new_for_bus() APIs.
4546 * As an exception to the usual GLib rule that a particular object must not
4547 * be used by two threads at the same time, #GDBusConnection's methods may be
4548 * called from any thread. This is so that g_bus_get() and g_bus_get_sync()
4549 * can safely return the same #GDBusConnection when called from any thread.
4551 * Most of the ways to obtain a #GDBusConnection automatically initialize it
4552 * (i.e. connect to D-Bus): for instance, g_dbus_connection_new() and
4553 * g_bus_get(), and the synchronous versions of those methods, give you an
4554 * initialized connection. Language bindings for GIO should use
4555 * g_initable_new() or g_async_initable_new_async(), which also initialize the
4558 * If you construct an uninitialized #GDBusConnection, such as via
4559 * g_object_new(), you must initialize it via g_initable_init() or
4560 * g_async_initable_init_async() before using its methods or properties.
4561 * Calling methods or accessing properties on a #GDBusConnection that has not
4562 * completed initialization successfully is considered to be invalid, and leads
4563 * to undefined behaviour. In particular, if initialization fails with a
4564 * #GError, the only valid thing you can do with that #GDBusConnection is to
4565 * free it with g_object_unref().
4567 * ## An example D-Bus server # {#gdbus-server}
4569 * Here is an example for a D-Bus server:
4570 * [gdbus-example-server.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-server.c)
4572 * ## An example for exporting a subtree # {#gdbus-subtree-server}
4574 * Here is an example for exporting a subtree:
4575 * [gdbus-example-subtree.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-subtree.c)
4577 * ## An example for file descriptor passing # {#gdbus-unix-fd-client}
4579 * Here is an example for passing UNIX file descriptors:
4580 * [gdbus-unix-fd-client.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-unix-fd-client.c)
4582 * ## An example for exporting a GObject # {#gdbus-export}
4584 * Here is an example for exporting a #GObject:
4585 * [gdbus-example-export.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-export.c)
4590 * SECTION:gdbuserror
4591 * @title: GDBusError
4592 * @short_description: Mapping D-Bus errors to and from GError
4593 * @include: gio/gio.h
4595 * All facilities that return errors from remote methods (such as
4596 * g_dbus_connection_call_sync()) use #GError to represent both D-Bus
4597 * errors (e.g. errors returned from the other peer) and locally
4598 * in-process generated errors.
4600 * To check if a returned #GError is an error from a remote peer, use
4601 * g_dbus_error_is_remote_error(). To get the actual D-Bus error name,
4602 * use g_dbus_error_get_remote_error(). Before presenting an error,
4603 * always use g_dbus_error_strip_remote_error().
4605 * In addition, facilities used to return errors to a remote peer also
4606 * use #GError. See g_dbus_method_invocation_return_error() for
4607 * discussion about how the D-Bus error name is set.
4609 * Applications can associate a #GError error domain with a set of D-Bus errors in order to
4610 * automatically map from D-Bus errors to #GError and back. This
4611 * is typically done in the function returning the #GQuark for the
4613 * |[<!-- language="C" -->
4614 * // foo-bar-error.h:
4616 * #define FOO_BAR_ERROR (foo_bar_error_quark ())
4617 * GQuark foo_bar_error_quark (void);
4621 * FOO_BAR_ERROR_FAILED,
4622 * FOO_BAR_ERROR_ANOTHER_ERROR,
4623 * FOO_BAR_ERROR_SOME_THIRD_ERROR,
4624 * FOO_BAR_N_ERRORS / *< skip >* /
4627 * // foo-bar-error.c:
4629 * static const GDBusErrorEntry foo_bar_error_entries[] =
4631 * {FOO_BAR_ERROR_FAILED, "org.project.Foo.Bar.Error.Failed"},
4632 * {FOO_BAR_ERROR_ANOTHER_ERROR, "org.project.Foo.Bar.Error.AnotherError"},
4633 * {FOO_BAR_ERROR_SOME_THIRD_ERROR, "org.project.Foo.Bar.Error.SomeThirdError"},
4636 * // Ensure that every error code has an associated D-Bus error name
4637 * G_STATIC_ASSERT (G_N_ELEMENTS (foo_bar_error_entries) == FOO_BAR_N_ERRORS);
4640 * foo_bar_error_quark (void)
4642 * static volatile gsize quark_volatile = 0;
4643 * g_dbus_error_register_error_domain ("foo-bar-error-quark",
4645 * foo_bar_error_entries,
4646 * G_N_ELEMENTS (foo_bar_error_entries));
4647 * return (GQuark) quark_volatile;
4650 * With this setup, a D-Bus peer can transparently pass e.g. %FOO_BAR_ERROR_ANOTHER_ERROR and
4651 * other peers will see the D-Bus error name org.project.Foo.Bar.Error.AnotherError.
4653 * If the other peer is using GDBus, and has registered the association with
4654 * g_dbus_error_register_error_domain() in advance (e.g. by invoking the %FOO_BAR_ERROR quark
4655 * generation itself in the previous example) the peer will see also %FOO_BAR_ERROR_ANOTHER_ERROR instead
4656 * of %G_IO_ERROR_DBUS_ERROR. Note that GDBus clients can still recover
4657 * org.project.Foo.Bar.Error.AnotherError using g_dbus_error_get_remote_error().
4659 * Note that errors in the %G_DBUS_ERROR error domain is intended only
4660 * for returning errors from a remote message bus process. Errors
4661 * generated locally in-process by e.g. #GDBusConnection is from the
4662 * %G_IO_ERROR domain.
4667 * SECTION:gdbusinterface
4668 * @short_description: Base type for D-Bus interfaces
4669 * @include: gio/gio.h
4671 * The #GDBusInterface type is the base type for D-Bus interfaces both
4672 * on the service side (see #GDBusInterfaceSkeleton) and client side
4673 * (see #GDBusProxy).
4678 * SECTION:gdbusinterfaceskeleton
4679 * @short_description: Service-side D-Bus interface
4680 * @include: gio/gio.h
4682 * Abstract base class for D-Bus interfaces on the service side.
4687 * SECTION:gdbusintrospection
4688 * @title: D-Bus Introspection Data
4689 * @short_description: Node and interface description data structures
4690 * @include: gio/gio.h
4692 * Various data structures and convenience routines to parse and
4693 * generate D-Bus introspection XML. Introspection information is
4694 * used when registering objects with g_dbus_connection_register_object().
4696 * The format of D-Bus introspection XML is specified in the
4697 * [D-Bus specification](http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format)
4702 * SECTION:gdbusmenumodel
4703 * @title: GDBusMenuModel
4704 * @short_description: A D-Bus GMenuModel implementation
4705 * @include: gio/gio.h
4706 * @see_also: [GMenuModel Exporter][gio-GMenuModel-exporter]
4708 * #GDBusMenuModel is an implementation of #GMenuModel that can be used
4709 * as a proxy for a menu model that is exported over D-Bus with
4710 * g_dbus_connection_export_menu_model().
4715 * SECTION:gdbusmessage
4716 * @short_description: D-Bus Message
4717 * @include: gio/gio.h
4719 * A type for representing D-Bus messages that can be sent or received
4720 * on a #GDBusConnection.
4725 * SECTION:gdbusmethodinvocation
4726 * @short_description: Object for handling remote calls
4727 * @include: gio/gio.h
4729 * Instances of the #GDBusMethodInvocation class are used when
4730 * handling D-Bus method calls. It provides a way to asynchronously
4731 * return results and errors.
4733 * The normal way to obtain a #GDBusMethodInvocation object is to receive
4734 * it as an argument to the handle_method_call() function in a
4735 * #GDBusInterfaceVTable that was passed to g_dbus_connection_register_object().
4740 * SECTION:gdbusnameowning
4741 * @title: Owning Bus Names
4742 * @short_description: Simple API for owning bus names
4743 * @include: gio/gio.h
4745 * Convenience API for owning bus names.
4747 * A simple example for owning a name can be found in
4748 * [gdbus-example-own-name.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-own-name.c)
4753 * SECTION:gdbusnamewatching
4754 * @title: Watching Bus Names
4755 * @short_description: Simple API for watching bus names
4756 * @include: gio/gio.h
4758 * Convenience API for watching bus names.
4760 * A simple example for watching a name can be found in
4761 * [gdbus-example-watch-name.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-watch-name.c)
4766 * SECTION:gdbusobject
4767 * @short_description: Base type for D-Bus objects
4768 * @include: gio/gio.h
4770 * The #GDBusObject type is the base type for D-Bus objects on both
4771 * the service side (see #GDBusObjectSkeleton) and the client side
4772 * (see #GDBusObjectProxy). It is essentially just a container of
4778 * SECTION:gdbusobjectmanager
4779 * @short_description: Base type for D-Bus object managers
4780 * @include: gio/gio.h
4782 * The #GDBusObjectManager type is the base type for service- and
4783 * client-side implementations of the standardized
4784 * [org.freedesktop.DBus.ObjectManager](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager)
4787 * See #GDBusObjectManagerClient for the client-side implementation
4788 * and #GDBusObjectManagerServer for the service-side implementation.
4793 * SECTION:gdbusobjectmanagerclient
4794 * @short_description: Client-side object manager
4795 * @include: gio/gio.h
4797 * #GDBusObjectManagerClient is used to create, monitor and delete object
4798 * proxies for remote objects exported by a #GDBusObjectManagerServer (or any
4799 * code implementing the
4800 * [org.freedesktop.DBus.ObjectManager](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager)
4803 * Once an instance of this type has been created, you can connect to
4804 * the #GDBusObjectManager::object-added and
4805 * #GDBusObjectManager::object-removed signals and inspect the
4806 * #GDBusObjectProxy objects returned by
4807 * g_dbus_object_manager_get_objects().
4809 * If the name for a #GDBusObjectManagerClient is not owned by anyone at
4810 * object construction time, the default behavior is to request the
4811 * message bus to launch an owner for the name. This behavior can be
4812 * disabled using the %G_DBUS_OBJECT_MANAGER_CLIENT_FLAGS_DO_NOT_AUTO_START
4813 * flag. It's also worth noting that this only works if the name of
4814 * interest is activatable in the first place. E.g. in some cases it
4815 * is not possible to launch an owner for the requested name. In this
4816 * case, #GDBusObjectManagerClient object construction still succeeds but
4817 * there will be no object proxies
4818 * (e.g. g_dbus_object_manager_get_objects() returns the empty list) and
4819 * the #GDBusObjectManagerClient:name-owner property is %NULL.
4821 * The owner of the requested name can come and go (for example
4822 * consider a system service being restarted) – #GDBusObjectManagerClient
4823 * handles this case too; simply connect to the #GObject::notify
4824 * signal to watch for changes on the #GDBusObjectManagerClient:name-owner
4825 * property. When the name owner vanishes, the behavior is that
4826 * #GDBusObjectManagerClient:name-owner is set to %NULL (this includes
4827 * emission of the #GObject::notify signal) and then
4828 * #GDBusObjectManager::object-removed signals are synthesized
4829 * for all currently existing object proxies. Since
4830 * #GDBusObjectManagerClient:name-owner is %NULL when this happens, you can
4831 * use this information to disambiguate a synthesized signal from a
4832 * genuine signal caused by object removal on the remote
4833 * #GDBusObjectManager. Similarly, when a new name owner appears,
4834 * #GDBusObjectManager::object-added signals are synthesized
4835 * while #GDBusObjectManagerClient:name-owner is still %NULL. Only when all
4836 * object proxies have been added, the #GDBusObjectManagerClient:name-owner
4837 * is set to the new name owner (this includes emission of the
4838 * #GObject::notify signal). Furthermore, you are guaranteed that
4839 * #GDBusObjectManagerClient:name-owner will alternate between a name owner
4840 * (e.g. `:1.42`) and %NULL even in the case where
4841 * the name of interest is atomically replaced
4843 * Ultimately, #GDBusObjectManagerClient is used to obtain #GDBusProxy
4844 * instances. All signals (including the
4845 * org.freedesktop.DBus.Properties::PropertiesChanged signal)
4846 * delivered to #GDBusProxy instances are guaranteed to originate
4847 * from the name owner. This guarantee along with the behavior
4848 * described above, means that certain race conditions including the
4849 * "half the proxy is from the old owner and the other half is from
4850 * the new owner" problem cannot happen.
4852 * To avoid having the application connect to signals on the returned
4853 * #GDBusObjectProxy and #GDBusProxy objects, the
4854 * #GDBusObject::interface-added,
4855 * #GDBusObject::interface-removed,
4856 * #GDBusProxy::g-properties-changed and
4857 * #GDBusProxy::g-signal signals
4858 * are also emitted on the #GDBusObjectManagerClient instance managing these
4859 * objects. The signals emitted are
4860 * #GDBusObjectManager::interface-added,
4861 * #GDBusObjectManager::interface-removed,
4862 * #GDBusObjectManagerClient::interface-proxy-properties-changed and
4863 * #GDBusObjectManagerClient::interface-proxy-signal.
4865 * Note that all callbacks and signals are emitted in the
4866 * [thread-default main context][g-main-context-push-thread-default]
4867 * that the #GDBusObjectManagerClient object was constructed
4868 * in. Additionally, the #GDBusObjectProxy and #GDBusProxy objects
4869 * originating from the #GDBusObjectManagerClient object will be created in
4870 * the same context and, consequently, will deliver signals in the
4876 * SECTION:gdbusobjectmanagerserver
4877 * @short_description: Service-side object manager
4878 * @include: gio/gio.h
4880 * #GDBusObjectManagerServer is used to export #GDBusObject instances using
4882 * [org.freedesktop.DBus.ObjectManager](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager)
4883 * interface. For example, remote D-Bus clients can get all objects
4884 * and properties in a single call. Additionally, any change in the
4885 * object hierarchy is broadcast using signals. This means that D-Bus
4886 * clients can keep caches up to date by only listening to D-Bus
4889 * See #GDBusObjectManagerClient for the client-side code that is
4890 * intended to be used with #GDBusObjectManagerServer or any D-Bus
4891 * object implementing the org.freedesktop.DBus.ObjectManager
4897 * SECTION:gdbusobjectproxy
4898 * @short_description: Client-side D-Bus object
4899 * @include: gio/gio.h
4901 * A #GDBusObjectProxy is an object used to represent a remote object
4902 * with one or more D-Bus interfaces. Normally, you don't instantiate
4903 * a #GDBusObjectProxy yourself - typically #GDBusObjectManagerClient
4904 * is used to obtain it.
4911 * SECTION:gdbusobjectskeleton
4912 * @short_description: Service-side D-Bus object
4913 * @include: gio/gio.h
4915 * A #GDBusObjectSkeleton instance is essentially a group of D-Bus
4916 * interfaces. The set of exported interfaces on the object may be
4917 * dynamic and change at runtime.
4919 * This type is intended to be used with #GDBusObjectManager.
4924 * SECTION:gdbusproxy
4925 * @short_description: Client-side D-Bus interface proxy
4926 * @include: gio/gio.h
4928 * #GDBusProxy is a base class used for proxies to access a D-Bus
4929 * interface on a remote object. A #GDBusProxy can be constructed for
4930 * both well-known and unique names.
4932 * By default, #GDBusProxy will cache all properties (and listen to
4933 * changes) of the remote object, and proxy all signals that gets
4934 * emitted. This behaviour can be changed by passing suitable
4935 * #GDBusProxyFlags when the proxy is created. If the proxy is for a
4936 * well-known name, the property cache is flushed when the name owner
4937 * vanishes and reloaded when a name owner appears.
4939 * If a #GDBusProxy is used for a well-known name, the owner of the
4940 * name is tracked and can be read from
4941 * #GDBusProxy:g-name-owner. Connect to the #GObject::notify signal to
4942 * get notified of changes. Additionally, only signals and property
4943 * changes emitted from the current name owner are considered and
4944 * calls are always sent to the current name owner. This avoids a
4945 * number of race conditions when the name is lost by one owner and
4946 * claimed by another. However, if no name owner currently exists,
4947 * then calls will be sent to the well-known name which may result in
4948 * the message bus launching an owner (unless
4949 * %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START is set).
4951 * The generic #GDBusProxy::g-properties-changed and
4952 * #GDBusProxy::g-signal signals are not very convenient to work with.
4953 * Therefore, the recommended way of working with proxies is to subclass
4954 * #GDBusProxy, and have more natural properties and signals in your derived
4955 * class. This [example][gdbus-example-gdbus-codegen] shows how this can
4956 * easily be done using the [gdbus-codegen][gdbus-codegen] tool.
4958 * A #GDBusProxy instance can be used from multiple threads but note
4959 * that all signals (e.g. #GDBusProxy::g-signal, #GDBusProxy::g-properties-changed
4960 * and #GObject::notify) are emitted in the
4961 * [thread-default main context][g-main-context-push-thread-default]
4962 * of the thread where the instance was constructed.
4964 * An example using a proxy for a well-known name can be found in
4965 * [gdbus-example-watch-proxy.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-watch-proxy.c)
4970 * SECTION:gdbusserver
4971 * @short_description: Helper for accepting connections
4972 * @include: gio/gio.h
4974 * #GDBusServer is a helper for listening to and accepting D-Bus
4975 * connections. This can be used to create a new D-Bus server, allowing two
4976 * peers to use the D-Bus protocol for their own specialized communication.
4977 * A server instance provided in this way will not perform message routing or
4978 * implement the org.freedesktop.DBus interface.
4980 * To just export an object on a well-known name on a message bus, such as the
4981 * session or system bus, you should instead use g_bus_own_name().
4983 * An example of peer-to-peer communication with G-DBus can be found
4984 * in [gdbus-example-peer.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-peer.c).
4989 * SECTION:gdbusutils
4990 * @title: D-Bus Utilities
4991 * @short_description: Various utilities related to D-Bus
4992 * @include: gio/gio.h
4994 * Various utility routines related to D-Bus.
4999 * SECTION:gdesktopappinfo
5000 * @title: GDesktopAppInfo
5001 * @short_description: Application information from desktop files
5002 * @include: gio/gdesktopappinfo.h
5004 * #GDesktopAppInfo is an implementation of #GAppInfo based on
5007 * Note that `<gio/gdesktopappinfo.h>` belongs to the UNIX-specific
5008 * GIO interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config
5009 * file when using it.
5015 * @short_description: Drive management
5016 * @include: gio/gio.h
5018 * #GDrive - this represent a piece of hardware connected to the machine.
5019 * It's generally only created for removable hardware or hardware with
5022 * #GDrive is a container class for #GVolume objects that stem from
5023 * the same piece of media. As such, #GDrive abstracts a drive with
5024 * (or without) removable media and provides operations for querying
5025 * whether media is available, determining whether media change is
5026 * automatically detected and ejecting the media.
5028 * If the #GDrive reports that media isn't automatically detected, one
5029 * can poll for media; typically one should not do this periodically
5030 * as a poll for media operation is potententially expensive and may
5031 * spin up the drive creating noise.
5033 * #GDrive supports starting and stopping drives with authentication
5034 * support for the former. This can be used to support a diverse set
5035 * of use cases including connecting/disconnecting iSCSI devices,
5036 * powering down external disk enclosures and starting/stopping
5037 * multi-disk devices such as RAID devices. Note that the actual
5038 * semantics and side-effects of starting/stopping a #GDrive may vary
5039 * according to implementation. To choose the correct verbs in e.g. a
5040 * file manager, use g_drive_get_start_stop_type().
5042 * For porting from GnomeVFS note that there is no equivalent of
5043 * #GDrive in that API.
5049 * @short_description: An object for emblems
5050 * @include: gio/gio.h
5051 * @see_also: #GIcon, #GEmblemedIcon, #GLoadableIcon, #GThemedIcon
5053 * #GEmblem is an implementation of #GIcon that supports
5054 * having an emblem, which is an icon with additional properties.
5055 * It can than be added to a #GEmblemedIcon.
5057 * Currently, only metainformation about the emblem's origin is
5058 * supported. More may be added in the future.
5063 * SECTION:gemblemedicon
5064 * @short_description: Icon with emblems
5065 * @include: gio/gio.h
5066 * @see_also: #GIcon, #GLoadableIcon, #GThemedIcon, #GEmblem
5068 * #GEmblemedIcon is an implementation of #GIcon that supports
5069 * adding an emblem to an icon. Adding multiple emblems to an
5070 * icon is ensured via g_emblemed_icon_add_emblem().
5072 * Note that #GEmblemedIcon allows no control over the position
5073 * of the emblems. See also #GEmblem for more information.
5079 * @short_description: File and Directory Handling
5080 * @include: gio/gio.h
5081 * @see_also: #GFileInfo, #GFileEnumerator
5083 * #GFile is a high level abstraction for manipulating files on a
5084 * virtual file system. #GFiles are lightweight, immutable objects
5085 * that do no I/O upon creation. It is necessary to understand that
5086 * #GFile objects do not represent files, merely an identifier for a
5087 * file. All file content I/O is implemented as streaming operations
5088 * (see #GInputStream and #GOutputStream).
5090 * To construct a #GFile, you can use:
5091 * - g_file_new_for_path() if you have a path.
5092 * - g_file_new_for_uri() if you have a URI.
5093 * - g_file_new_for_commandline_arg() for a command line argument.
5094 * - g_file_new_tmp() to create a temporary file from a template.
5095 * - g_file_parse_name() from a UTF-8 string gotten from g_file_get_parse_name().
5097 * One way to think of a #GFile is as an abstraction of a pathname. For
5098 * normal files the system pathname is what is stored internally, but as
5099 * #GFiles are extensible it could also be something else that corresponds
5100 * to a pathname in a userspace implementation of a filesystem.
5102 * #GFiles make up hierarchies of directories and files that correspond to
5103 * the files on a filesystem. You can move through the file system with
5104 * #GFile using g_file_get_parent() to get an identifier for the parent
5105 * directory, g_file_get_child() to get a child within a directory,
5106 * g_file_resolve_relative_path() to resolve a relative path between two
5107 * #GFiles. There can be multiple hierarchies, so you may not end up at
5108 * the same root if you repeatedly call g_file_get_parent() on two different
5111 * All #GFiles have a basename (get with g_file_get_basename()). These names
5112 * are byte strings that are used to identify the file on the filesystem
5113 * (relative to its parent directory) and there is no guarantees that they
5114 * have any particular charset encoding or even make any sense at all. If
5115 * you want to use filenames in a user interface you should use the display
5116 * name that you can get by requesting the
5117 * %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME attribute with g_file_query_info().
5118 * This is guaranteed to be in UTF-8 and can be used in a user interface.
5119 * But always store the real basename or the #GFile to use to actually
5120 * access the file, because there is no way to go from a display name to
5123 * Using #GFile as an identifier has the same weaknesses as using a path
5124 * in that there may be multiple aliases for the same file. For instance,
5125 * hard or soft links may cause two different #GFiles to refer to the same
5126 * file. Other possible causes for aliases are: case insensitive filesystems,
5127 * short and long names on FAT/NTFS, or bind mounts in Linux. If you want to
5128 * check if two #GFiles point to the same file you can query for the
5129 * %G_FILE_ATTRIBUTE_ID_FILE attribute. Note that #GFile does some trivial
5130 * canonicalization of pathnames passed in, so that trivial differences in
5131 * the path string used at creation (duplicated slashes, slash at end of
5132 * path, "." or ".." path segments, etc) does not create different #GFiles.
5134 * Many #GFile operations have both synchronous and asynchronous versions
5135 * to suit your application. Asynchronous versions of synchronous functions
5136 * simply have _async() appended to their function names. The asynchronous
5137 * I/O functions call a #GAsyncReadyCallback which is then used to finalize
5138 * the operation, producing a GAsyncResult which is then passed to the
5139 * function's matching _finish() operation.
5141 * Some #GFile operations do not have synchronous analogs, as they may
5142 * take a very long time to finish, and blocking may leave an application
5143 * unusable. Notable cases include:
5144 * - g_file_mount_mountable() to mount a mountable file.
5145 * - g_file_unmount_mountable_with_operation() to unmount a mountable file.
5146 * - g_file_eject_mountable_with_operation() to eject a mountable file.
5148 * ## Entity Tags # {#gfile-etag}
5150 * One notable feature of #GFiles are entity tags, or "etags" for
5151 * short. Entity tags are somewhat like a more abstract version of the
5152 * traditional mtime, and can be used to quickly determine if the file
5153 * has been modified from the version on the file system. See the
5155 * [specification](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html)
5156 * for HTTP Etag headers, which are a very similar concept.
5161 * SECTION:gfileattribute
5162 * @short_description: Key-Value Paired File Attributes
5163 * @include: gio/gio.h
5164 * @see_also: #GFile, #GFileInfo
5166 * File attributes in GIO consist of a list of key-value pairs.
5168 * Keys are strings that contain a key namespace and a key name, separated
5169 * by a colon, e.g. "namespace::keyname". Namespaces are included to sort
5170 * key-value pairs by namespaces for relevance. Keys can be retrived
5171 * using wildcards, e.g. "standard::*" will return all of the keys in the
5172 * "standard" namespace.
5174 * The list of possible attributes for a filesystem (pointed to by a #GFile) is
5175 * available as a #GFileAttributeInfoList. This list is queryable by key names
5176 * as indicated earlier.
5178 * Information is stored within the list in #GFileAttributeInfo structures.
5179 * The info structure can store different types, listed in the enum
5180 * #GFileAttributeType. Upon creation of a #GFileAttributeInfo, the type will
5181 * be set to %G_FILE_ATTRIBUTE_TYPE_INVALID.
5183 * Classes that implement #GFileIface will create a #GFileAttributeInfoList and
5184 * install default keys and values for their given file system, architecture,
5185 * and other possible implementation details (e.g., on a UNIX system, a file
5186 * attribute key will be registered for the user id for a given file).
5188 * ## Default Namespaces
5190 * - `"standard"`: The "Standard" namespace. General file information that
5191 * any application may need should be put in this namespace. Examples
5192 * include the file's name, type, and size.
5193 * - `"etag`: The [Entity Tag][gfile-etag] namespace. Currently, the only key
5194 * in this namespace is "value", which contains the value of the current
5196 * - `"id"`: The "Identification" namespace. This namespace is used by file
5197 * managers and applications that list directories to check for loops and
5198 * to uniquely identify files.
5199 * - `"access"`: The "Access" namespace. Used to check if a user has the
5200 * proper privileges to access files and perform file operations. Keys in
5201 * this namespace are made to be generic and easily understood, e.g. the
5202 * "can_read" key is %TRUE if the current user has permission to read the
5203 * file. UNIX permissions and NTFS ACLs in Windows should be mapped to
5205 * - `"mountable"`: The "Mountable" namespace. Includes simple boolean keys
5206 * for checking if a file or path supports mount operations, e.g. mount,
5207 * unmount, eject. These are used for files of type %G_FILE_TYPE_MOUNTABLE.
5208 * - `"time"`: The "Time" namespace. Includes file access, changed, created
5210 * - `"unix"`: The "Unix" namespace. Includes UNIX-specific information and
5211 * may not be available for all files. Examples include the UNIX "UID",
5213 * - `"dos"`: The "DOS" namespace. Includes DOS-specific information and may
5214 * not be available for all files. Examples include "is_system" for checking
5215 * if a file is marked as a system file, and "is_archive" for checking if a
5216 * file is marked as an archive file.
5217 * - `"owner"`: The "Owner" namespace. Includes information about who owns a
5218 * file. May not be available for all file systems. Examples include "user"
5219 * for getting the user name of the file owner. This information is often
5220 * mapped from some backend specific data such as a UNIX UID.
5221 * - `"thumbnail"`: The "Thumbnail" namespace. Includes information about file
5222 * thumbnails and their location within the file system. Examples of keys in
5223 * this namespace include "path" to get the location of a thumbnail, "failed"
5224 * to check if thumbnailing of the file failed, and "is-valid" to check if
5225 * the thumbnail is outdated.
5226 * - `"filesystem"`: The "Filesystem" namespace. Gets information about the
5227 * file system where a file is located, such as its type, how much space is
5228 * left available, and the overall size of the file system.
5229 * - `"gvfs"`: The "GVFS" namespace. Keys in this namespace contain information
5230 * about the current GVFS backend in use.
5231 * - `"xattr"`: The "xattr" namespace. Gets information about extended
5232 * user attributes. See attr(5). The "user." prefix of the extended user
5233 * attribute name is stripped away when constructing keys in this namespace,
5234 * e.g. "xattr::mime_type" for the extended attribute with the name
5235 * "user.mime_type". Note that this information is only available if
5236 * GLib has been built with extended attribute support.
5237 * - `"xattr-sys"`: The "xattr-sys" namespace. Gets information about
5238 * extended attributes which are not user-specific. See attr(5). Note
5239 * that this information is only available if GLib has been built with
5240 * extended attribute support.
5241 * - `"selinux"`: The "SELinux" namespace. Includes information about the
5242 * SELinux context of files. Note that this information is only available
5243 * if GLib has been built with SELinux support.
5245 * Please note that these are not all of the possible namespaces.
5246 * More namespaces can be added from GIO modules or by individual applications.
5247 * For more information about writing GIO modules, see #GIOModule.
5249 * <!-- TODO: Implementation note about using extended attributes on supported
5254 * For a list of the built-in keys and their types, see the
5255 * [GFileInfo][GFileInfo] documentation.
5257 * Note that there are no predefined keys in the "xattr" and "xattr-sys"
5258 * namespaces. Keys for the "xattr" namespace are constructed by stripping
5259 * away the "user." prefix from the extended user attribute, and prepending
5260 * "xattr::". Keys for the "xattr-sys" namespace are constructed by
5261 * concatenating "xattr-sys::" with the extended attribute name. All extended
5262 * attribute values are returned as hex-encoded strings in which bytes outside
5263 * the ASCII range are encoded as escape sequences of the form \x`nn`
5264 * where `nn` is a 2-digit hexadecimal number.
5269 * SECTION:gfiledescriptorbased
5270 * @short_description: Interface for file descriptor based IO
5271 * @include: gio/gfiledescriptorbased.h
5272 * @see_also: #GInputStream, #GOutputStream
5274 * #GFileDescriptorBased is implemented by streams (implementations of
5275 * #GInputStream or #GOutputStream) that are based on file descriptors.
5277 * Note that `<gio/gfiledescriptorbased.h>` belongs to the UNIX-specific
5278 * GIO interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config
5279 * file when using it.
5286 * SECTION:gfileenumerator
5287 * @short_description: Enumerated Files Routines
5288 * @include: gio/gio.h
5290 * #GFileEnumerator allows you to operate on a set of #GFiles,
5291 * returning a #GFileInfo structure for each file enumerated (e.g.
5292 * g_file_enumerate_children() will return a #GFileEnumerator for each
5293 * of the children within a directory).
5295 * To get the next file's information from a #GFileEnumerator, use
5296 * g_file_enumerator_next_file() or its asynchronous version,
5297 * g_file_enumerator_next_files_async(). Note that the asynchronous
5298 * version will return a list of #GFileInfos, whereas the
5299 * synchronous will only return the next file in the enumerator.
5301 * The ordering of returned files is unspecified for non-Unix
5302 * platforms; for more information, see g_dir_read_name(). On Unix,
5303 * when operating on local files, returned files will be sorted by
5304 * inode number. Effectively you can assume that the ordering of
5305 * returned files will be stable between successive calls (and
5306 * applications) assuming the directory is unchanged.
5308 * If your application needs a specific ordering, such as by name or
5309 * modification time, you will have to implement that in your
5312 * To close a #GFileEnumerator, use g_file_enumerator_close(), or
5313 * its asynchronous version, g_file_enumerator_close_async(). Once
5314 * a #GFileEnumerator is closed, no further actions may be performed
5315 * on it, and it should be freed with g_object_unref().
5321 * @short_description: Icons pointing to an image file
5322 * @include: gio/gio.h
5323 * @see_also: #GIcon, #GLoadableIcon
5325 * #GFileIcon specifies an icon by pointing to an image file
5326 * to be used as icon.
5332 * @short_description: File Information and Attributes
5333 * @include: gio/gio.h
5334 * @see_also: #GFile, [GFileAttribute][gio-GFileAttribute]
5336 * Functionality for manipulating basic metadata for files. #GFileInfo
5337 * implements methods for getting information that all files should
5338 * contain, and allows for manipulation of extended attributes.
5340 * See [GFileAttribute][gio-GFileAttribute for more information on how
5341 * GIO handles file attributes.
5343 * To obtain a #GFileInfo for a #GFile, use g_file_query_info() (or its
5344 * async variant). To obtain a #GFileInfo for a file input or output
5345 * stream, use g_file_input_stream_query_info() or
5346 * g_file_output_stream_query_info() (or their async variants).
5348 * To change the actual attributes of a file, you should then set the
5349 * attribute in the #GFileInfo and call g_file_set_attributes_from_info()
5350 * or g_file_set_attributes_async() on a GFile.
5352 * However, not all attributes can be changed in the file. For instance,
5353 * the actual size of a file cannot be changed via g_file_info_set_size().
5354 * You may call g_file_query_settable_attributes() and
5355 * g_file_query_writable_namespaces() to discover the settable attributes
5356 * of a particular file at runtime.
5358 * #GFileAttributeMatcher allows for searching through a #GFileInfo for
5364 * SECTION:gfileinputstream
5365 * @short_description: File input streaming operations
5366 * @include: gio/gio.h
5367 * @see_also: #GInputStream, #GDataInputStream, #GSeekable
5369 * GFileInputStream provides input streams that take their
5370 * content from a file.
5372 * GFileInputStream implements #GSeekable, which allows the input
5373 * stream to jump to arbitrary positions in the file, provided the
5374 * filesystem of the file allows it. To find the position of a file
5375 * input stream, use g_seekable_tell(). To find out if a file input
5376 * stream supports seeking, use g_seekable_can_seek().
5377 * To position a file input stream, use g_seekable_seek().
5382 * SECTION:gfileiostream
5383 * @short_description: File read and write streaming operations
5384 * @include: gio/gio.h
5385 * @see_also: #GIOStream, #GFileInputStream, #GFileOutputStream, #GSeekable
5387 * GFileIOStream provides io streams that both read and write to the same
5390 * GFileIOStream implements #GSeekable, which allows the io
5391 * stream to jump to arbitrary positions in the file and to truncate
5392 * the file, provided the filesystem of the file supports these
5395 * To find the position of a file io stream, use
5396 * g_seekable_tell().
5398 * To find out if a file io stream supports seeking, use g_seekable_can_seek().
5399 * To position a file io stream, use g_seekable_seek().
5400 * To find out if a file io stream supports truncating, use
5401 * g_seekable_can_truncate(). To truncate a file io
5402 * stream, use g_seekable_truncate().
5404 * The default implementation of all the #GFileIOStream operations
5405 * and the implementation of #GSeekable just call into the same operations
5406 * on the output stream.
5413 * SECTION:gfilemonitor
5414 * @short_description: File Monitor
5415 * @include: gio/gio.h
5417 * Monitors a file or directory for changes.
5419 * To obtain a #GFileMonitor for a file or directory, use
5420 * g_file_monitor(), g_file_monitor_file(), or
5421 * g_file_monitor_directory().
5423 * To get informed about changes to the file or directory you are
5424 * monitoring, connect to the #GFileMonitor::changed signal. The
5425 * signal will be emitted in the
5426 * [thread-default main context][g-main-context-push-thread-default]
5427 * of the thread that the monitor was created in
5428 * (though if the global default main context is blocked, this may
5429 * cause notifications to be blocked even if the thread-default
5430 * context is still running).
5435 * SECTION:gfilenamecompleter
5436 * @short_description: Filename Completer
5437 * @include: gio/gio.h
5439 * Completes partial file and directory names given a partial string by
5440 * looking in the file system for clues. Can return a list of possible
5441 * completion strings for widget implementations.
5446 * SECTION:gfileoutputstream
5447 * @short_description: File output streaming operations
5448 * @include: gio/gio.h
5449 * @see_also: #GOutputStream, #GDataOutputStream, #GSeekable
5451 * GFileOutputStream provides output streams that write their
5452 * content to a file.
5454 * GFileOutputStream implements #GSeekable, which allows the output
5455 * stream to jump to arbitrary positions in the file and to truncate
5456 * the file, provided the filesystem of the file supports these
5459 * To find the position of a file output stream, use g_seekable_tell().
5460 * To find out if a file output stream supports seeking, use
5461 * g_seekable_can_seek().To position a file output stream, use
5462 * g_seekable_seek(). To find out if a file output stream supports
5463 * truncating, use g_seekable_can_truncate(). To truncate a file output
5464 * stream, use g_seekable_truncate().
5469 * SECTION:gfilterinputstream
5470 * @short_description: Filter Input Stream
5471 * @include: gio/gio.h
5473 * Base class for input stream implementations that perform some
5474 * kind of filtering operation on a base stream. Typical examples
5475 * of filtering operations are character set conversion, compression
5476 * and byte order flipping.
5481 * SECTION:gfilteroutputstream
5482 * @short_description: Filter Output Stream
5483 * @include: gio/gio.h
5485 * Base class for output stream implementations that perform some
5486 * kind of filtering operation on a base stream. Typical examples
5487 * of filtering operations are character set conversion, compression
5488 * and byte order flipping.
5494 * @short_description: Interface for icons
5495 * @include: gio/gio.h
5497 * #GIcon is a very minimal interface for icons. It provides functions
5498 * for checking the equality of two icons, hashing of icons and
5499 * serializing an icon to and from strings.
5501 * #GIcon does not provide the actual pixmap for the icon as this is out
5502 * of GIO's scope, however implementations of #GIcon may contain the name
5503 * of an icon (see #GThemedIcon), or the path to an icon (see #GLoadableIcon).
5505 * To obtain a hash of a #GIcon, see g_icon_hash().
5507 * To check if two #GIcons are equal, see g_icon_equal().
5509 * For serializing a #GIcon, use g_icon_serialize() and
5510 * g_icon_deserialize().
5512 * If you want to consume #GIcon (for example, in a toolkit) you must
5513 * be prepared to handle at least the three following cases:
5514 * #GLoadableIcon, #GThemedIcon and #GEmblemedIcon. It may also make
5515 * sense to have fast-paths for other cases (like handling #GdkPixbuf
5516 * directly, for example) but all compliant #GIcon implementations
5517 * outside of GIO must implement #GLoadableIcon.
5519 * If your application or library provides one or more #GIcon
5520 * implementations you need to ensure that your new implementation also
5521 * implements #GLoadableIcon. Additionally, you must provide an
5522 * implementation of g_icon_serialize() that gives a result that is
5523 * understood by g_icon_deserialize(), yielding one of the built-in icon
5529 * SECTION:ginetaddress
5530 * @short_description: An IPv4/IPv6 address
5531 * @include: gio/gio.h
5533 * #GInetAddress represents an IPv4 or IPv6 internet address. Use
5534 * g_resolver_lookup_by_name() or g_resolver_lookup_by_name_async() to
5535 * look up the #GInetAddress for a hostname. Use
5536 * g_resolver_lookup_by_address() or
5537 * g_resolver_lookup_by_address_async() to look up the hostname for a
5540 * To actually connect to a remote host, you will need a
5541 * #GInetSocketAddress (which includes a #GInetAddress as well as a
5547 * SECTION:ginetaddressmask
5548 * @short_description: An IPv4/IPv6 address mask
5549 * @include: gio/gio.h
5551 * #GInetAddressMask represents a range of IPv4 or IPv6 addresses
5552 * described by a base address and a length indicating how many bits
5553 * of the base address are relevant for matching purposes. These are
5554 * often given in string form. Eg, "10.0.0.0/8", or "fe80::/10".
5559 * SECTION:ginetsocketaddress
5560 * @short_description: Internet GSocketAddress
5561 * @include: gio/gio.h
5563 * An IPv4 or IPv6 socket address; that is, the combination of a
5564 * #GInetAddress and a port number.
5570 * @short_description: Failable object initialization interface
5571 * @include: gio/gio.h
5572 * @see_also: #GAsyncInitable
5574 * #GInitable is implemented by objects that can fail during
5575 * initialization. If an object implements this interface then
5576 * it must be initialized as the first thing after construction,
5577 * either via g_initable_init() or g_async_initable_init_async()
5578 * (the latter is only available if it also implements #GAsyncInitable).
5580 * If the object is not initialized, or initialization returns with an
5581 * error, then all operations on the object except g_object_ref() and
5582 * g_object_unref() are considered to be invalid, and have undefined
5583 * behaviour. They will often fail with g_critical() or g_warning(), but
5584 * this must not be relied on.
5586 * Users of objects implementing this are not intended to use
5587 * the interface method directly, instead it will be used automatically
5588 * in various ways. For C applications you generally just call
5589 * g_initable_new() directly, or indirectly via a foo_thing_new() wrapper.
5590 * This will call g_initable_init() under the cover, returning %NULL and
5591 * setting a #GError on failure (at which point the instance is
5594 * For bindings in languages where the native constructor supports
5595 * exceptions the binding could check for objects implemention %GInitable
5596 * during normal construction and automatically initialize them, throwing
5597 * an exception on failure.
5602 * SECTION:ginputstream
5603 * @short_description: Base class for implementing streaming input
5604 * @include: gio/gio.h
5606 * #GInputStream has functions to read from a stream (g_input_stream_read()),
5607 * to close a stream (g_input_stream_close()) and to skip some content
5608 * (g_input_stream_skip()).
5610 * To copy the content of an input stream to an output stream without
5611 * manually handling the reads and writes, use g_output_stream_splice().
5613 * All of these functions have async variants too.
5619 * @short_description: Error helper functions
5620 * @include: gio/gio.h
5622 * Contains helper functions for reporting errors to the user.
5628 * @short_description: Loadable GIO Modules
5629 * @include: gio/gio.h
5631 * Provides an interface and default functions for loading and unloading
5632 * modules. This is used internally to make GIO extensible, but can also
5633 * be used by others to implement module loading.
5638 * SECTION:gioscheduler
5639 * @short_description: I/O Scheduler
5640 * @include: gio/gio.h
5642 * As of GLib 2.36, #GIOScheduler is deprecated in favor of
5643 * #GThreadPool and #GTask.
5645 * Schedules asynchronous I/O operations. #GIOScheduler integrates
5646 * into the main event loop (#GMainLoop) and uses threads.
5652 * @short_description: Base class for implementing read/write streams
5653 * @include: gio/gio.h
5654 * @see_also: #GInputStream, #GOutputStream
5656 * GIOStream represents an object that has both read and write streams.
5657 * Generally the two streams acts as separate input and output streams,
5658 * but they share some common resources and state. For instance, for
5659 * seekable streams they may use the same position in both streams.
5661 * Examples of #GIOStream objects are #GSocketConnection which represents
5662 * a two-way network connection, and #GFileIOStream which represent a
5663 * file handle opened in read-write mode.
5665 * To do the actual reading and writing you need to get the substreams
5666 * with g_io_stream_get_input_stream() and g_io_stream_get_output_stream().
5668 * The #GIOStream object owns the input and the output streams, not the other
5669 * way around, so keeping the substreams alive will not keep the #GIOStream
5670 * object alive. If the #GIOStream object is freed it will be closed, thus
5671 * closing the substream, so even if the substreams stay alive they will
5672 * always just return a %G_IO_ERROR_CLOSED for all operations.
5674 * To close a stream use g_io_stream_close() which will close the common
5675 * stream object and also the individual substreams. You can also close
5676 * the substreams themselves. In most cases this only marks the
5677 * substream as closed, so further I/O on it fails but common state in the
5678 * #GIOStream may still be open. However, some streams may support
5679 * "half-closed" states where one direction of the stream is actually shut down.
5686 * SECTION:gloadableicon
5687 * @short_description: Loadable Icons
5688 * @include: gio/gio.h
5689 * @see_also: #GIcon, #GThemedIcon
5691 * Extends the #GIcon interface and adds the ability to
5692 * load icons from streams.
5697 * SECTION:gmemoryinputstream
5698 * @short_description: Streaming input operations on memory chunks
5699 * @include: gio/gio.h
5700 * @see_also: #GMemoryOutputStream
5702 * #GMemoryInputStream is a class for using arbitrary
5703 * memory chunks as input for GIO streaming input operations.
5705 * As of GLib 2.34, #GMemoryInputStream implements
5706 * #GPollableInputStream.
5711 * SECTION:gmemoryoutputstream
5712 * @short_description: Streaming output operations on memory chunks
5713 * @include: gio/gio.h
5714 * @see_also: #GMemoryInputStream
5716 * #GMemoryOutputStream is a class for using arbitrary
5717 * memory chunks as output for GIO streaming output operations.
5719 * As of GLib 2.34, #GMemoryOutputStream trivially implements
5720 * #GPollableOutputStream: it always polls as ready.
5727 * @short_description: A simple implementation of GMenuModel
5728 * @include: gio/gio.h
5730 * #GMenu is a simple implementation of #GMenuModel.
5731 * You populate a #GMenu by adding #GMenuItem instances to it.
5733 * There are some convenience functions to allow you to directly
5734 * add items (avoiding #GMenuItem) for the common cases. To add
5735 * a regular item, use g_menu_insert(). To add a section, use
5736 * g_menu_insert_section(). To add a submenu, use
5737 * g_menu_insert_submenu().
5742 * SECTION:gmenuexporter
5743 * @title: GMenuModel exporter
5744 * @short_description: Export GMenuModels on D-Bus
5745 * @include: gio/gio.h
5746 * @see_also: #GMenuModel, #GDBusMenuModel
5748 * These functions support exporting a #GMenuModel on D-Bus.
5749 * The D-Bus interface that is used is a private implementation
5752 * To access an exported #GMenuModel remotely, use
5753 * g_dbus_menu_model_get() to obtain a #GDBusMenuModel.
5758 * SECTION:gmenumodel
5759 * @title: GMenuModel
5760 * @short_description: An abstract class representing the contents of a menu
5761 * @include: gio/gio.h
5762 * @see_also: #GActionGroup
5764 * #GMenuModel represents the contents of a menu -- an ordered list of
5765 * menu items. The items are associated with actions, which can be
5766 * activated through them. Items can be grouped in sections, and may
5767 * have submenus associated with them. Both items and sections usually
5768 * have some representation data, such as labels or icons. The type of
5769 * the associated action (ie whether it is stateful, and what kind of
5770 * state it has) can influence the representation of the item.
5772 * The conceptual model of menus in #GMenuModel is hierarchical:
5773 * sections and submenus are again represented by #GMenuModels.
5774 * Menus themselves do not define their own roles. Rather, the role
5775 * of a particular #GMenuModel is defined by the item that references
5776 * it (or, in the case of the 'root' menu, is defined by the context
5777 * in which it is used).
5779 * As an example, consider the visible portions of this menu:
5781 * ## An example menu # {#menu-example}
5783 * ![](menu-example.png)
5785 * There are 8 "menus" visible in the screenshot: one menubar, two
5786 * submenus and 5 sections:
5788 * - the toplevel menubar (containing 4 items)
5789 * - the View submenu (containing 3 sections)
5790 * - the first section of the View submenu (containing 2 items)
5791 * - the second section of the View submenu (containing 1 item)
5792 * - the final section of the View submenu (containing 1 item)
5793 * - the Highlight Mode submenu (containing 2 sections)
5794 * - the Sources section (containing 2 items)
5795 * - the Markup section (containing 2 items)
5797 * The [example][menu-model] illustrates the conceptual connection between
5798 * these 8 menus. Each large block in the figure represents a menu and the
5799 * smaller blocks within the large block represent items in that menu. Some
5800 * items contain references to other menus.
5802 * ## A menu example # {#menu-model}
5804 * ![](menu-model.png)
5806 * Notice that the separators visible in the [example][menu-example]
5807 * appear nowhere in the [menu model][menu-model]. This is because
5808 * separators are not explicitly represented in the menu model. Instead,
5809 * a separator is inserted between any two non-empty sections of a menu.
5810 * Section items can have labels just like any other item. In that case,
5811 * a display system may show a section header instead of a separator.
5813 * The motivation for this abstract model of application controls is
5814 * that modern user interfaces tend to make these controls available
5815 * outside the application. Examples include global menus, jumplists,
5816 * dash boards, etc. To support such uses, it is necessary to 'export'
5817 * information about actions and their representation in menus, which
5818 * is exactly what the [GActionGroup exporter][gio-GActionGroup-exporter]
5819 * and the [GMenuModel exporter][gio-GMenuModel-exporter] do for
5820 * #GActionGroup and #GMenuModel. The client-side counterparts to
5821 * make use of the exported information are #GDBusActionGroup and
5824 * The API of #GMenuModel is very generic, with iterators for the
5825 * attributes and links of an item, see g_menu_model_iterate_item_attributes()
5826 * and g_menu_model_iterate_item_links(). The 'standard' attributes and
5827 * link types have predefined names: %G_MENU_ATTRIBUTE_LABEL,
5828 * %G_MENU_ATTRIBUTE_ACTION, %G_MENU_ATTRIBUTE_TARGET, %G_MENU_LINK_SECTION
5829 * and %G_MENU_LINK_SUBMENU.
5831 * Items in a #GMenuModel represent active controls if they refer to
5832 * an action that can get activated when the user interacts with the
5833 * menu item. The reference to the action is encoded by the string id
5834 * in the %G_MENU_ATTRIBUTE_ACTION attribute. An action id uniquely
5835 * identifies an action in an action group. Which action group(s) provide
5836 * actions depends on the context in which the menu model is used.
5837 * E.g. when the model is exported as the application menu of a
5838 * #GtkApplication, actions can be application-wide or window-specific
5839 * (and thus come from two different action groups). By convention, the
5840 * application-wide actions have names that start with "app.", while the
5841 * names of window-specific actions start with "win.".
5843 * While a wide variety of stateful actions is possible, the following
5844 * is the minimum that is expected to be supported by all users of exported
5846 * - an action with no parameter type and no state
5847 * - an action with no parameter type and boolean state
5848 * - an action with string parameter type and string state
5852 * A stateless action typically corresponds to an ordinary menu item.
5854 * Selecting such a menu item will activate the action (with no parameter).
5858 * An action with a boolean state will most typically be used with a "toggle"
5859 * or "switch" menu item. The state can be set directly, but activating the
5860 * action (with no parameter) results in the state being toggled.
5862 * Selecting a toggle menu item will activate the action. The menu item should
5863 * be rendered as "checked" when the state is true.
5865 * ## String Parameter and State
5867 * Actions with string parameters and state will most typically be used to
5868 * represent an enumerated choice over the items available for a group of
5869 * radio menu items. Activating the action with a string parameter is
5870 * equivalent to setting that parameter as the state.
5872 * Radio menu items, in addition to being associated with the action, will
5873 * have a target value. Selecting that menu item will result in activation
5874 * of the action with the target value as the parameter. The menu item should
5875 * be rendered as "selected" when the state of the action is equal to the
5876 * target value of the menu item.
5882 * @short_description: Mount management
5883 * @include: gio/gio.h
5884 * @see_also: GVolume, GUnixMountEntry, GUnixMountPoint
5886 * The #GMount interface represents user-visible mounts. Note, when
5887 * porting from GnomeVFS, #GMount is the moral equivalent of #GnomeVFSVolume.
5889 * #GMount is a "mounted" filesystem that you can access. Mounted is in
5890 * quotes because it's not the same as a unix mount, it might be a gvfs
5891 * mount, but you can still access the files on it if you use GIO. Might or
5892 * might not be related to a volume object.
5894 * Unmounting a #GMount instance is an asynchronous operation. For
5895 * more information about asynchronous operations, see #GAsyncResult
5896 * and #GTask. To unmount a #GMount instance, first call
5897 * g_mount_unmount_with_operation() with (at least) the #GMount instance and a
5898 * #GAsyncReadyCallback. The callback will be fired when the
5899 * operation has resolved (either with success or failure), and a
5900 * #GAsyncReady structure will be passed to the callback. That
5901 * callback should then call g_mount_unmount_with_operation_finish() with the #GMount
5902 * and the #GAsyncReady data to see if the operation was completed
5903 * successfully. If an @error is present when g_mount_unmount_with_operation_finish()
5904 * is called, then it will be filled with any error information.
5909 * SECTION:gmountoperation
5910 * @short_description: Object used for authentication and user interaction
5911 * @include: gio/gio.h
5913 * #GMountOperation provides a mechanism for interacting with the user.
5914 * It can be used for authenticating mountable operations, such as loop
5915 * mounting files, hard drive partitions or server locations. It can
5916 * also be used to ask the user questions or show a list of applications
5917 * preventing unmount or eject operations from completing.
5919 * Note that #GMountOperation is used for more than just #GMount
5920 * objects – for example it is also used in g_drive_start() and
5923 * Users should instantiate a subclass of this that implements all the
5924 * various callbacks to show the required dialogs, such as
5925 * #GtkMountOperation. If no user interaction is desired (for example
5926 * when automounting filesystems at login time), usually %NULL can be
5927 * passed, see each method taking a #GMountOperation for details.
5932 * SECTION:gnetworkaddress
5933 * @short_description: A GSocketConnectable for resolving hostnames
5934 * @include: gio/gio.h
5936 * #GNetworkAddress provides an easy way to resolve a hostname and
5937 * then attempt to connect to that host, handling the possibility of
5938 * multiple IP addresses and multiple address families.
5940 * See #GSocketConnectable for and example of using the connectable
5946 * SECTION:gnetworking
5947 * @title: gnetworking.h
5948 * @short_description: System networking includes
5949 * @include: gio/gnetworking.h
5951 * The `<gio/gnetworking.h>` header can be included to get
5952 * various low-level networking-related system headers, automatically
5953 * taking care of certain portability issues for you.
5955 * This can be used, for example, if you want to call setsockopt()
5958 * Note that while WinSock has many of the same APIs as the
5959 * traditional UNIX socket API, most of them behave at least slightly
5960 * differently (particularly with respect to error handling). If you
5961 * want your code to work under both UNIX and Windows, you will need
5962 * to take these differences into account.
5964 * Also, under GNU libc, certain non-portable functions are only visible
5965 * in the headers if you define %_GNU_SOURCE before including them. Note
5966 * that this symbol must be defined before including any headers, or it
5967 * may not take effect.
5972 * SECTION:gnetworkmonitor
5973 * @title: GNetworkMonitor
5974 * @short_description: Network status monitor
5975 * @include: gio/gio.h
5977 * #GNetworkMonitor provides an easy-to-use cross-platform API
5978 * for monitoring network connectivity. On Linux, the implementation
5979 * is based on the kernel's netlink interface.
5984 * SECTION:gnetworkservice
5985 * @short_description: A GSocketConnectable for resolving SRV records
5986 * @include: gio/gio.h
5988 * Like #GNetworkAddress does with hostnames, #GNetworkService
5989 * provides an easy way to resolve a SRV record, and then attempt to
5990 * connect to one of the hosts that implements that service, handling
5991 * service priority/weighting, multiple IP addresses, and multiple
5994 * See #GSrvTarget for more information about SRV records, and see
5995 * #GSocketConnectable for and example of using the connectable
6001 * SECTION:gnotification
6002 * @short_description: User Notifications (pop up messages)
6003 * @include: gio/gio.h
6005 * #GNotification is a mechanism for creating a notification to be shown
6006 * to the user -- typically as a pop-up notification presented by the
6007 * desktop environment shell.
6009 * The key difference between #GNotification and other similar APIs is
6010 * that, if supported by the desktop environment, notifications sent
6011 * with #GNotification will persist after the application has exited,
6012 * and even across system reboots.
6014 * Since the user may click on a notification while the application is
6015 * not running, applications using #GNotification should be able to be
6016 * started as a D-Bus service, using #GApplication.
6018 * User interaction with a notification (either the default action, or
6019 * buttons) must be associated with actions on the application (ie:
6020 * "app." actions). It is not possible to route user interaction
6021 * through the notification itself, because the object will not exist if
6022 * the application is autostarted as a result of a notification being
6025 * A notification can be sent with g_application_send_notification().
6032 * SECTION:goutputstream
6033 * @short_description: Base class for implementing streaming output
6034 * @include: gio/gio.h
6036 * #GOutputStream has functions to write to a stream (g_output_stream_write()),
6037 * to close a stream (g_output_stream_close()) and to flush pending writes
6038 * (g_output_stream_flush()).
6040 * To copy the content of an input stream to an output stream without
6041 * manually handling the reads and writes, use g_output_stream_splice().
6043 * All of these functions have async variants too.
6048 * SECTION:gpermission
6049 * @title: GPermission
6050 * @short_description: An object representing the permission
6051 * to perform a certain action
6052 * @include: gio/gio.h
6054 * A #GPermission represents the status of the caller's permission to
6055 * perform a certain action.
6057 * You can query if the action is currently allowed and if it is
6058 * possible to acquire the permission so that the action will be allowed
6061 * There is also an API to actually acquire the permission and one to
6064 * As an example, a #GPermission might represent the ability for the
6065 * user to write to a #GSettings object. This #GPermission object could
6066 * then be used to decide if it is appropriate to show a "Click here to
6067 * unlock" button in a dialog and to provide the mechanism to invoke
6068 * when that button is clicked.
6073 * SECTION:gpollableinputstream
6074 * @short_description: Interface for pollable input streams
6075 * @include: gio/gio.h
6076 * @see_also: #GInputStream, #GPollableOutputStream, #GFileDescriptorBased
6078 * #GPollableInputStream is implemented by #GInputStreams that
6079 * can be polled for readiness to read. This can be used when
6080 * interfacing with a non-GIO API that expects
6081 * UNIX-file-descriptor-style asynchronous I/O rather than GIO-style.
6088 * SECTION:gpollableoutputstream
6089 * @short_description: Interface for pollable output streams
6090 * @include: gio/gio.h
6091 * @see_also: #GOutputStream, #GFileDescriptorBased, #GPollableInputStream
6093 * #GPollableOutputStream is implemented by #GOutputStreams that
6094 * can be polled for readiness to write. This can be used when
6095 * interfacing with a non-GIO API that expects
6096 * UNIX-file-descriptor-style asynchronous I/O rather than GIO-style.
6103 * SECTION:gpollableutils
6104 * @short_description: Utilities for pollable streams
6105 * @include: gio/gio.h
6107 * Utility functions for #GPollableInputStream and
6108 * #GPollableOutputStream implementations.
6113 * SECTION:gpropertyaction
6114 * @title: GPropertyAction
6115 * @short_description: A GAction reflecting a GObject property
6116 * @include: gio/gio.h
6118 * A #GPropertyAction is a way to get a #GAction with a state value
6119 * reflecting and controlling the value of a #GObject property.
6121 * The state of the action will correspond to the value of the property.
6122 * Changing it will change the property (assuming the requested value
6123 * matches the requirements as specified in the #GParamSpec).
6125 * Only the most common types are presently supported. Booleans are
6126 * mapped to booleans, strings to strings, signed/unsigned integers to
6127 * int32/uint32 and floats and doubles to doubles.
6129 * If the property is an enum then the state will be string-typed and
6130 * conversion will automatically be performed between the enum value and
6131 * "nick" string as per the #GEnumValue table.
6133 * Flags types are not currently supported.
6135 * Properties of object types, boxed types and pointer types are not
6136 * supported and probably never will be.
6138 * Properties of #GVariant types are not currently supported.
6140 * If the property is boolean-valued then the action will have a NULL
6141 * parameter type, and activating the action (with no parameter) will
6142 * toggle the value of the property.
6144 * In all other cases, the parameter type will correspond to the type of
6147 * The general idea here is to reduce the number of locations where a
6148 * particular piece of state is kept (and therefore has to be synchronised
6149 * between). #GPropertyAction does not have a separate state that is kept
6150 * in sync with the property value -- its state is the property value.
6152 * For example, it might be useful to create a #GAction corresponding to
6153 * the "visible-child-name" property of a #GtkStack so that the current
6154 * page can be switched from a menu. The active radio indication in the
6155 * menu is then directly determined from the active page of the
6158 * An anti-example would be binding the "active-id" property on a
6159 * #GtkComboBox. This is because the state of the combobox itself is
6160 * probably uninteresting and is actually being used to control
6163 * Another anti-example would be to bind to the "visible-child-name"
6164 * property of a #GtkStack if this value is actually stored in
6165 * #GSettings. In that case, the real source of the value is
6166 * #GSettings. If you want a #GAction to control a setting stored in
6167 * #GSettings, see g_settings_create_action() instead, and possibly
6168 * combine its use with g_settings_bind().
6176 * @short_description: Interface for proxy handling
6177 * @include: gio/gio.h
6179 * A #GProxy handles connecting to a remote host via a given type of
6180 * proxy server. It is implemented by the 'gio-proxy' extension point.
6181 * The extensions are named after their proxy protocol name. As an
6182 * example, a SOCKS5 proxy implementation can be retrieved with the
6183 * name 'socks5' using the function
6184 * g_io_extension_point_get_extension_by_name().
6191 * SECTION:gproxyaddress
6192 * @short_description: An internet address with proxy information
6193 * @include: gio/gio.h
6195 * Support for proxied #GInetSocketAddress.
6200 * SECTION:gproxyresolver
6201 * @short_description: Asynchronous and cancellable network proxy resolver
6202 * @include: gio/gio.h
6204 * #GProxyResolver provides synchronous and asynchronous network proxy
6205 * resolution. #GProxyResolver is used within #GSocketClient through
6206 * the method g_socket_connectable_proxy_enumerate().
6211 * SECTION:gremoteactiongroup
6212 * @title: GRemoteActionGroup
6213 * @short_description: A GActionGroup that interacts with other processes
6214 * @include: gio/gio.h
6216 * The GRemoteActionGroup interface is implemented by #GActionGroup
6217 * instances that either transmit action invocations to other processes
6218 * or receive action invocations in the local process from other
6221 * The interface has `_full` variants of the two
6222 * methods on #GActionGroup used to activate actions:
6223 * g_action_group_activate_action() and
6224 * g_action_group_change_action_state(). These variants allow a
6225 * "platform data" #GVariant to be specified: a dictionary providing
6226 * context for the action invocation (for example: timestamps, startup
6227 * notification IDs, etc).
6229 * #GDBusActionGroup implements #GRemoteActionGroup. This provides a
6230 * mechanism to send platform data for action invocations over D-Bus.
6232 * Additionally, g_dbus_connection_export_action_group() will check if
6233 * the exported #GActionGroup implements #GRemoteActionGroup and use the
6234 * `_full` variants of the calls if available. This
6235 * provides a mechanism by which to receive platform data for action
6236 * invocations that arrive by way of D-Bus.
6244 * @short_description: Asynchronous and cancellable DNS resolver
6245 * @include: gio/gio.h
6247 * #GResolver provides cancellable synchronous and asynchronous DNS
6248 * resolution, for hostnames (g_resolver_lookup_by_address(),
6249 * g_resolver_lookup_by_name() and their async variants) and SRV
6250 * (service) records (g_resolver_lookup_service()).
6252 * #GNetworkAddress and #GNetworkService provide wrappers around
6253 * #GResolver functionality that also implement #GSocketConnectable,
6254 * making it easy to connect to a remote host/service.
6260 * @short_description: Resource framework
6261 * @include: gio/gio.h
6263 * Applications and libraries often contain binary or textual data that is
6264 * really part of the application, rather than user data. For instance
6265 * #GtkBuilder .ui files, splashscreen images, GMenu markup xml, CSS files,
6266 * icons, etc. These are often shipped as files in `$datadir/appname`, or
6267 * manually included as literal strings in the code.
6269 * The #GResource API and the [glib-compile-resources][glib-compile-resources] program
6270 * provide a convenient and efficient alternative to this which has some nice properties. You
6271 * maintain the files as normal files, so its easy to edit them, but during the build the files
6272 * are combined into a binary bundle that is linked into the executable. This means that loading
6273 * the resource files are efficient (as they are already in memory, shared with other instances) and
6274 * simple (no need to check for things like I/O errors or locate the files in the filesystem). It
6275 * also makes it easier to create relocatable applications.
6277 * Resource files can also be marked as compressed. Such files will be included in the resource bundle
6278 * in a compressed form, but will be automatically uncompressed when the resource is used. This
6279 * is very useful e.g. for larger text files that are parsed once (or rarely) and then thrown away.
6281 * Resource files can also be marked to be preprocessed, by setting the value of the
6282 * `preprocess` attribute to a comma-separated list of preprocessing options.
6283 * The only options currently supported are:
6285 * `xml-stripblanks` which will use the xmllint command
6286 * to strip ignorable whitespace from the xml file. For this to work,
6287 * the `XMLLINT` environment variable must be set to the full path to
6288 * the xmllint executable, or xmllint must be in the `PATH`; otherwise
6289 * the preprocessing step is skipped.
6291 * `to-pixdata` which will use the gdk-pixbuf-pixdata command to convert
6292 * images to the GdkPixdata format, which allows you to create pixbufs directly using the data inside
6293 * the resource file, rather than an (uncompressed) copy if it. For this, the gdk-pixbuf-pixdata
6294 * program must be in the PATH, or the `GDK_PIXBUF_PIXDATA` environment variable must be
6295 * set to the full path to the gdk-pixbuf-pixdata executable; otherwise the resource compiler will
6298 * Resource bundles are created by the [glib-compile-resources][glib-compile-resources] program
6299 * which takes an xml file that describes the bundle, and a set of files that the xml references. These
6300 * are combined into a binary resource bundle.
6302 * An example resource description:
6304 * <?xml version="1.0" encoding="UTF-8"?>
6306 * <gresource prefix="/org/gtk/Example">
6307 * <file>data/splashscreen.png</file>
6308 * <file compressed="true">dialog.ui</file>
6309 * <file preprocess="xml-stripblanks">menumarkup.xml</file>
6314 * This will create a resource bundle with the following files:
6316 * /org/gtk/Example/data/splashscreen.png
6317 * /org/gtk/Example/dialog.ui
6318 * /org/gtk/Example/menumarkup.xml
6321 * Note that all resources in the process share the same namespace, so use java-style
6322 * path prefixes (like in the above example) to avoid conflicts.
6324 * You can then use [glib-compile-resources][glib-compile-resources] to compile the xml to a
6325 * binary bundle that you can load with g_resource_load(). However, its more common to use the --generate-source and
6326 * --generate-header arguments to create a source file and header to link directly into your application.
6328 * Once a #GResource has been created and registered all the data in it can be accessed globally in the process by
6329 * using API calls like g_resources_open_stream() to stream the data or g_resources_lookup_data() to get a direct pointer
6330 * to the data. You can also use uris like "resource:///org/gtk/Example/data/splashscreen.png" with #GFile to access
6331 * the resource data.
6333 * There are two forms of the generated source, the default version uses the compiler support for constructor
6334 * and destructor functions (where available) to automatically create and register the #GResource on startup
6335 * or library load time. If you pass --manual-register two functions to register/unregister the resource is instead
6336 * created. This requires an explicit initialization call in your application/library, but it works on all platforms,
6337 * even on the minor ones where this is not available. (Constructor support is available for at least Win32, MacOS and Linux.)
6339 * Note that resource data can point directly into the data segment of e.g. a library, so if you are unloading libraries
6340 * during runtime you need to be very careful with keeping around pointers to data from a resource, as this goes away
6341 * when the library is unloaded. However, in practice this is not generally a problem, since most resource accesses
6342 * is for your own resources, and resource data is often used once, during parsing, and then released.
6350 * @short_description: Stream seeking interface
6351 * @include: gio/gio.h
6352 * @see_also: #GInputStream, #GOutputStream
6354 * #GSeekable is implemented by streams (implementations of
6355 * #GInputStream or #GOutputStream) that support seeking.
6357 * Seekable streams largely fall into two categories: resizable and
6360 * #GSeekable on fixed-sized streams is approximately the same as POSIX
6361 * lseek() on a block device (for example: attmepting to seek past the
6362 * end of the device is an error). Fixed streams typically cannot be
6365 * #GSeekable on resizable streams is approximately the same as POSIX
6366 * lseek() on a normal file. Seeking past the end and writing data will
6367 * usually cause the stream to resize by introducing zero bytes.
6373 * @short_description: High-level API for application settings
6374 * @include: gio/gio.h
6376 * The #GSettings class provides a convenient API for storing and retrieving
6377 * application settings.
6379 * Reads and writes can be considered to be non-blocking. Reading
6380 * settings with #GSettings is typically extremely fast: on
6381 * approximately the same order of magnitude (but slower than) a
6382 * #GHashTable lookup. Writing settings is also extremely fast in terms
6383 * of time to return to your application, but can be extremely expensive
6384 * for other threads and other processes. Many settings backends
6385 * (including dconf) have lazy initialisation which means in the common
6386 * case of the user using their computer without modifying any settings
6387 * a lot of work can be avoided. For dconf, the D-Bus service doesn't
6388 * even need to be started in this case. For this reason, you should
6389 * only ever modify #GSettings keys in response to explicit user action.
6390 * Particular care should be paid to ensure that modifications are not
6391 * made during startup -- for example, when setting the initial value
6392 * of preferences widgets. The built-in g_settings_bind() functionality
6393 * is careful not to write settings in response to notify signals as a
6394 * result of modifications that it makes to widgets.
6396 * When creating a GSettings instance, you have to specify a schema
6397 * that describes the keys in your settings and their types and default
6398 * values, as well as some other information.
6400 * Normally, a schema has as fixed path that determines where the settings
6401 * are stored in the conceptual global tree of settings. However, schemas
6402 * can also be 'relocatable', i.e. not equipped with a fixed path. This is
6403 * useful e.g. when the schema describes an 'account', and you want to be
6404 * able to store a arbitrary number of accounts.
6406 * Paths must start with and end with a forward slash character ('/')
6407 * and must not contain two sequential slash characters. Paths should
6408 * be chosen based on a domain name associated with the program or
6409 * library to which the settings belong. Examples of paths are
6410 * "/org/gtk/settings/file-chooser/" and "/ca/desrt/dconf-editor/".
6411 * Paths should not start with "/apps/", "/desktop/" or "/system/" as
6412 * they often did in GConf.
6414 * Unlike other configuration systems (like GConf), GSettings does not
6415 * restrict keys to basic types like strings and numbers. GSettings stores
6416 * values as #GVariant, and allows any #GVariantType for keys. Key names
6417 * are restricted to lowercase characters, numbers and '-'. Furthermore,
6418 * the names must begin with a lowercase character, must not end
6419 * with a '-', and must not contain consecutive dashes.
6421 * Similar to GConf, the default values in GSettings schemas can be
6422 * localized, but the localized values are stored in gettext catalogs
6423 * and looked up with the domain that is specified in the
6424 * gettext-domain attribute of the <schemalist> or <schema>
6425 * elements and the category that is specified in the l10n attribute of
6426 * the <key> element.
6428 * GSettings uses schemas in a compact binary form that is created
6429 * by the [glib-compile-schemas][glib-compile-schemas]
6430 * utility. The input is a schema description in an XML format.
6432 * A DTD for the gschema XML format can be found here:
6433 * [gschema.dtd](https://git.gnome.org/browse/glib/tree/gio/gschema.dtd)
6435 * The [glib-compile-schemas][glib-compile-schemas] tool expects schema
6436 * files to have the extension `.gschema.xml`.
6438 * At runtime, schemas are identified by their id (as specified in the
6439 * id attribute of the <schema> element). The convention for schema
6440 * ids is to use a dotted name, similar in style to a D-Bus bus name,
6441 * e.g. "org.gnome.SessionManager". In particular, if the settings are
6442 * for a specific service that owns a D-Bus bus name, the D-Bus bus name
6443 * and schema id should match. For schemas which deal with settings not
6444 * associated with one named application, the id should not use
6445 * StudlyCaps, e.g. "org.gnome.font-rendering".
6447 * In addition to #GVariant types, keys can have types that have
6448 * enumerated types. These can be described by a <choice>,
6449 * <enum> or <flags> element, as seen in the
6450 * [example][schema-enumerated]. The underlying type of such a key
6451 * is string, but you can use g_settings_get_enum(), g_settings_set_enum(),
6452 * g_settings_get_flags(), g_settings_set_flags() access the numeric values
6453 * corresponding to the string value of enum and flags keys.
6455 * An example for default value:
6458 * <schema id="org.gtk.Test" path="/org/gtk/Test/" gettext-domain="test">
6460 * <key name="greeting" type="s">
6461 * <default l10n="messages">"Hello, earthlings"</default>
6462 * <summary>A greeting</summary>
6464 * Greeting of the invading martians
6468 * <key name="box" type="(ii)">
6469 * <default>(20,30)</default>
6476 * An example for ranges, choices and enumerated types:
6480 * <enum id="org.gtk.Test.myenum">
6481 * <value nick="first" value="1"/>
6482 * <value nick="second" value="2"/>
6485 * <flags id="org.gtk.Test.myflags">
6486 * <value nick="flag1" value="1"/>
6487 * <value nick="flag2" value="2"/>
6488 * <value nick="flag3" value="4"/>
6491 * <schema id="org.gtk.Test">
6493 * <key name="key-with-range" type="i">
6494 * <range min="1" max="100"/>
6495 * <default>10</default>
6498 * <key name="key-with-choices" type="s">
6500 * <choice value='Elisabeth'/>
6501 * <choice value='Annabeth'/>
6502 * <choice value='Joe'/>
6505 * <alias value='Anna' target='Annabeth'/>
6506 * <alias value='Beth' target='Elisabeth'/>
6508 * <default>'Joe'</default>
6511 * <key name='enumerated-key' enum='org.gtk.Test.myenum'>
6512 * <default>'first'</default>
6515 * <key name='flags-key' flags='org.gtk.Test.myflags'>
6516 * <default>["flag1",flag2"]</default>
6522 * ## Vendor overrides
6524 * Default values are defined in the schemas that get installed by
6525 * an application. Sometimes, it is necessary for a vendor or distributor
6526 * to adjust these defaults. Since patching the XML source for the schema
6527 * is inconvenient and error-prone,
6528 * [glib-compile-schemas][glib-compile-schemas] reads so-called vendor
6529 * override' files. These are keyfiles in the same directory as the XML
6530 * schema sources which can override default values. The schema id serves
6531 * as the group name in the key file, and the values are expected in
6532 * serialized GVariant form, as in the following example:
6539 * glib-compile-schemas expects schema files to have the extension
6540 * `.gschema.override`.
6544 * A very convenient feature of GSettings lets you bind #GObject properties
6545 * directly to settings, using g_settings_bind(). Once a GObject property
6546 * has been bound to a setting, changes on either side are automatically
6547 * propagated to the other side. GSettings handles details like mapping
6548 * between GObject and GVariant types, and preventing infinite cycles.
6550 * This makes it very easy to hook up a preferences dialog to the
6551 * underlying settings. To make this even more convenient, GSettings
6552 * looks for a boolean property with the name "sensitivity" and
6553 * automatically binds it to the writability of the bound setting.
6554 * If this 'magic' gets in the way, it can be suppressed with the
6555 * #G_SETTINGS_BIND_NO_SENSITIVITY flag.
6560 * SECTION:gsettingsbackend
6561 * @title: GSettingsBackend
6562 * @short_description: Interface for settings backend implementations
6563 * @include: gio/gsettingsbackend.h
6564 * @see_also: #GSettings, #GIOExtensionPoint
6566 * The #GSettingsBackend interface defines a generic interface for
6567 * non-strictly-typed data that is stored in a hierarchy. To implement
6568 * an alternative storage backend for #GSettings, you need to implement
6569 * the #GSettingsBackend interface and then make it implement the
6570 * extension point #G_SETTINGS_BACKEND_EXTENSION_POINT_NAME.
6572 * The interface defines methods for reading and writing values, a
6573 * method for determining if writing of certain values will fail
6574 * (lockdown) and a change notification mechanism.
6576 * The semantics of the interface are very precisely defined and
6577 * implementations must carefully adhere to the expectations of
6578 * callers that are documented on each of the interface methods.
6580 * Some of the GSettingsBackend functions accept or return a #GTree.
6581 * These trees always have strings as keys and #GVariant as values.
6582 * g_settings_backend_create_tree() is a convenience function to create
6585 * The GSettingsBackend API is exported to allow third-party
6586 * implementations, but does not carry the same stability guarantees
6587 * as the public GIO API. For this reason, you have to define the
6588 * C preprocessor symbol %G_SETTINGS_ENABLE_BACKEND before including
6589 * `gio/gsettingsbackend.h`.
6594 * SECTION:gsettingsschema
6595 * @short_description: Introspecting and controlling the loading
6596 * of GSettings schemas
6597 * @include: gio/gio.h
6599 * The #GSettingsSchemaSource and #GSettingsSchema APIs provide a
6600 * mechanism for advanced control over the loading of schemas and a
6601 * mechanism for introspecting their content.
6603 * Plugin loading systems that wish to provide plugins a way to access
6604 * settings face the problem of how to make the schemas for these
6605 * settings visible to GSettings. Typically, a plugin will want to ship
6606 * the schema along with itself and it won't be installed into the
6607 * standard system directories for schemas.
6609 * #GSettingsSchemaSource provides a mechanism for dealing with this by
6610 * allowing the creation of a new 'schema source' from which schemas can
6611 * be acquired. This schema source can then become part of the metadata
6612 * associated with the plugin and queried whenever the plugin requires
6613 * access to some settings.
6615 * Consider the following example:
6617 * |[<!-- language="C" -->
6621 * GSettingsSchemaSource *schema_source;
6626 * initialise_plugin (const gchar *dir)
6632 * plugin->schema_source =
6633 * g_settings_new_schema_source_from_directory (dir,
6634 * g_settings_schema_source_get_default (), FALSE, NULL);
6644 * plugin_get_settings (Plugin *plugin,
6645 * const gchar *schema_id)
6647 * GSettingsSchema *schema;
6649 * if (schema_id == NULL)
6650 * schema_id = plugin->identifier;
6652 * schema = g_settings_schema_source_lookup (plugin->schema_source,
6653 * schema_id, FALSE);
6655 * if (schema == NULL)
6657 * ... disable the plugin or abort, etc ...
6660 * return g_settings_new_full (schema, NULL, NULL);
6664 * The code above shows how hooks should be added to the code that
6665 * initialises (or enables) the plugin to create the schema source and
6666 * how an API can be added to the plugin system to provide a convenient
6667 * way for the plugin to access its settings, using the schemas that it
6670 * From the standpoint of the plugin, it would need to ensure that it
6671 * ships a gschemas.compiled file as part of itself, and then simply do
6674 * |[<!-- language="C" -->
6676 * GSettings *settings;
6679 * settings = plugin_get_settings (self, NULL);
6680 * some_value = g_settings_get_int (settings, "some-value");
6685 * It's also possible that the plugin system expects the schema source
6686 * files (ie: .gschema.xml files) instead of a gschemas.compiled file.
6687 * In that case, the plugin loading system must compile the schemas for
6688 * itself before attempting to create the settings source.
6695 * SECTION:gsimpleaction
6696 * @title: GSimpleAction
6697 * @short_description: A simple GAction implementation
6698 * @include: gio/gio.h
6700 * A #GSimpleAction is the obvious simple implementation of the #GAction
6701 * interface. This is the easiest way to create an action for purposes of
6702 * adding it to a #GSimpleActionGroup.
6704 * See also #GtkAction.
6709 * SECTION:gsimpleactiongroup
6710 * @title: GSimpleActionGroup
6711 * @short_description: A simple GActionGroup implementation
6712 * @include: gio/gio.h
6714 * #GSimpleActionGroup is a hash table filled with #GAction objects,
6715 * implementing the #GActionGroup and #GActionMap interfaces.
6720 * SECTION:gsimpleasyncresult
6721 * @short_description: Simple asynchronous results implementation
6722 * @include: gio/gio.h
6723 * @see_also: #GAsyncResult, #GTask
6725 * As of GLib 2.36, #GSimpleAsyncResult is deprecated in favor of
6726 * #GTask, which provides a simpler API.
6728 * #GSimpleAsyncResult implements #GAsyncResult.
6730 * GSimpleAsyncResult handles #GAsyncReadyCallbacks, error
6731 * reporting, operation cancellation and the final state of an operation,
6732 * completely transparent to the application. Results can be returned
6733 * as a pointer e.g. for functions that return data that is collected
6734 * asynchronously, a boolean value for checking the success or failure
6735 * of an operation, or a #gssize for operations which return the number
6736 * of bytes modified by the operation; all of the simple return cases
6739 * Most of the time, an application will not need to know of the details
6740 * of this API; it is handled transparently, and any necessary operations
6741 * are handled by #GAsyncResult's interface. However, if implementing a
6742 * new GIO module, for writing language bindings, or for complex
6743 * applications that need better control of how asynchronous operations
6744 * are completed, it is important to understand this functionality.
6746 * GSimpleAsyncResults are tagged with the calling function to ensure
6747 * that asynchronous functions and their finishing functions are used
6748 * together correctly.
6750 * To create a new #GSimpleAsyncResult, call g_simple_async_result_new().
6751 * If the result needs to be created for a #GError, use
6752 * g_simple_async_result_new_from_error() or
6753 * g_simple_async_result_new_take_error(). If a #GError is not available
6754 * (e.g. the asynchronous operation's doesn't take a #GError argument),
6755 * but the result still needs to be created for an error condition, use
6756 * g_simple_async_result_new_error() (or g_simple_async_result_set_error_va()
6757 * if your application or binding requires passing a variable argument list
6758 * directly), and the error can then be propagated through the use of
6759 * g_simple_async_result_propagate_error().
6761 * An asynchronous operation can be made to ignore a cancellation event by
6762 * calling g_simple_async_result_set_handle_cancellation() with a
6763 * #GSimpleAsyncResult for the operation and %FALSE. This is useful for
6764 * operations that are dangerous to cancel, such as close (which would
6765 * cause a leak if cancelled before being run).
6767 * GSimpleAsyncResult can integrate into GLib's event loop, #GMainLoop,
6768 * or it can use #GThreads.
6769 * g_simple_async_result_complete() will finish an I/O task directly
6770 * from the point where it is called. g_simple_async_result_complete_in_idle()
6771 * will finish it from an idle handler in the
6772 * [thread-default main context][g-main-context-push-thread-default]
6773 * . g_simple_async_result_run_in_thread() will run the
6774 * job in a separate thread and then deliver the result to the
6775 * thread-default main context.
6777 * To set the results of an asynchronous function,
6778 * g_simple_async_result_set_op_res_gpointer(),
6779 * g_simple_async_result_set_op_res_gboolean(), and
6780 * g_simple_async_result_set_op_res_gssize()
6781 * are provided, setting the operation's result to a gpointer, gboolean, or
6782 * gssize, respectively.
6784 * Likewise, to get the result of an asynchronous function,
6785 * g_simple_async_result_get_op_res_gpointer(),
6786 * g_simple_async_result_get_op_res_gboolean(), and
6787 * g_simple_async_result_get_op_res_gssize() are
6788 * provided, getting the operation's result as a gpointer, gboolean, and
6789 * gssize, respectively.
6791 * For the details of the requirements implementations must respect, see
6792 * #GAsyncResult. A typical implementation of an asynchronous operation
6793 * using GSimpleAsyncResult looks something like this:
6795 * |[<!-- language="C" -->
6797 * baked_cb (Cake *cake,
6798 * gpointer user_data)
6800 * // In this example, this callback is not given a reference to the cake,
6801 * // so the GSimpleAsyncResult has to take a reference to it.
6802 * GSimpleAsyncResult *result = user_data;
6805 * g_simple_async_result_set_error (result,
6807 * BAKER_ERROR_NO_FLOUR,
6808 * "Go to the supermarket");
6810 * g_simple_async_result_set_op_res_gpointer (result,
6811 * g_object_ref (cake),
6815 * // In this example, we assume that baked_cb is called as a callback from
6816 * // the mainloop, so it's safe to complete the operation synchronously here.
6817 * // If, however, _baker_prepare_cake () might call its callback without
6818 * // first returning to the mainloop — inadvisable, but some APIs do so —
6819 * // we would need to use g_simple_async_result_complete_in_idle().
6820 * g_simple_async_result_complete (result);
6821 * g_object_unref (result);
6825 * baker_bake_cake_async (Baker *self,
6827 * GAsyncReadyCallback callback,
6828 * gpointer user_data)
6830 * GSimpleAsyncResult *simple;
6835 * g_simple_async_report_error_in_idle (G_OBJECT (self),
6839 * BAKER_ERROR_TOO_SMALL,
6840 * "%ucm radius cakes are silly",
6845 * simple = g_simple_async_result_new (G_OBJECT (self),
6848 * baker_bake_cake_async);
6849 * cake = _baker_get_cached_cake (self, radius);
6853 * g_simple_async_result_set_op_res_gpointer (simple,
6854 * g_object_ref (cake),
6856 * g_simple_async_result_complete_in_idle (simple);
6857 * g_object_unref (simple);
6858 * // Drop the reference returned by _baker_get_cached_cake();
6859 * // the GSimpleAsyncResult has taken its own reference.
6860 * g_object_unref (cake);
6864 * _baker_prepare_cake (self, radius, baked_cb, simple);
6868 * baker_bake_cake_finish (Baker *self,
6869 * GAsyncResult *result,
6872 * GSimpleAsyncResult *simple;
6875 * g_return_val_if_fail (g_simple_async_result_is_valid (result,
6877 * baker_bake_cake_async),
6880 * simple = (GSimpleAsyncResult *) result;
6882 * if (g_simple_async_result_propagate_error (simple, error))
6885 * cake = CAKE (g_simple_async_result_get_op_res_gpointer (simple));
6886 * return g_object_ref (cake);
6893 * SECTION:gsimplepermission
6894 * @title: GSimplePermission
6895 * @short_description: A GPermission that doesn't change value
6896 * @include: gio/gio.h
6898 * #GSimplePermission is a trivial implementation of #GPermission that
6899 * represents a permission that is either always or never allowed. The
6900 * value is given at construction and doesn't change.
6902 * Calling request or release will result in errors.
6907 * SECTION:gsimpleproxyresolver
6908 * @short_description: Simple proxy resolver implementation
6909 * @include: gio/gio.h
6910 * @see_also: g_socket_client_set_proxy_resolver()
6912 * #GSimpleProxyResolver is a simple #GProxyResolver implementation
6913 * that handles a single default proxy, multiple URI-scheme-specific
6914 * proxies, and a list of hosts that proxies should not be used for.
6916 * #GSimpleProxyResolver is never the default proxy resolver, but it
6917 * can be used as the base class for another proxy resolver
6918 * implementation, or it can be created and used manually, such as
6919 * with g_socket_client_set_proxy_resolver().
6927 * @short_description: Low-level socket object
6928 * @include: gio/gio.h
6929 * @see_also: #GInitable, [<gnetworking.h>][gio-gnetworking.h]
6931 * A #GSocket is a low-level networking primitive. It is a more or less
6932 * direct mapping of the BSD socket API in a portable GObject based API.
6933 * It supports both the UNIX socket implementations and winsock2 on Windows.
6935 * #GSocket is the platform independent base upon which the higher level
6936 * network primitives are based. Applications are not typically meant to
6937 * use it directly, but rather through classes like #GSocketClient,
6938 * #GSocketService and #GSocketConnection. However there may be cases where
6939 * direct use of #GSocket is useful.
6941 * #GSocket implements the #GInitable interface, so if it is manually constructed
6942 * by e.g. g_object_new() you must call g_initable_init() and check the
6943 * results before using the object. This is done automatically in
6944 * g_socket_new() and g_socket_new_from_fd(), so these functions can return
6947 * Sockets operate in two general modes, blocking or non-blocking. When
6948 * in blocking mode all operations block until the requested operation
6949 * is finished or there is an error. In non-blocking mode all calls that
6950 * would block return immediately with a %G_IO_ERROR_WOULD_BLOCK error.
6951 * To know when a call would successfully run you can call g_socket_condition_check(),
6952 * or g_socket_condition_wait(). You can also use g_socket_create_source() and
6953 * attach it to a #GMainContext to get callbacks when I/O is possible.
6954 * Note that all sockets are always set to non blocking mode in the system, and
6955 * blocking mode is emulated in GSocket.
6957 * When working in non-blocking mode applications should always be able to
6958 * handle getting a %G_IO_ERROR_WOULD_BLOCK error even when some other
6959 * function said that I/O was possible. This can easily happen in case
6960 * of a race condition in the application, but it can also happen for other
6961 * reasons. For instance, on Windows a socket is always seen as writable
6962 * until a write returns %G_IO_ERROR_WOULD_BLOCK.
6964 * #GSockets can be either connection oriented or datagram based.
6965 * For connection oriented types you must first establish a connection by
6966 * either connecting to an address or accepting a connection from another
6967 * address. For connectionless socket types the target/source address is
6968 * specified or received in each I/O operation.
6970 * All socket file descriptors are set to be close-on-exec.
6972 * Note that creating a #GSocket causes the signal %SIGPIPE to be
6973 * ignored for the remainder of the program. If you are writing a
6974 * command-line utility that uses #GSocket, you may need to take into
6975 * account the fact that your program will not automatically be killed
6976 * if it tries to write to %stdout after it has been closed.
6978 * Like most other APIs in GLib, #GSocket is not inherently thread safe. To use
6979 * a #GSocket concurrently from multiple threads, you must implement your own
6987 * SECTION:gsocketaddress
6988 * @short_description: Abstract base class representing endpoints
6989 * for socket communication
6990 * @include: gio/gio.h
6992 * #GSocketAddress is the equivalent of struct sockaddr in the BSD
6993 * sockets API. This is an abstract class; use #GInetSocketAddress
6994 * for internet sockets, or #GUnixSocketAddress for UNIX domain sockets.
6999 * SECTION:gsocketclient
7000 * @short_description: Helper for connecting to a network service
7001 * @include: gio/gio.h
7002 * @see_also: #GSocketConnection, #GSocketListener
7004 * #GSocketClient is a lightweight high-level utility class for connecting to
7005 * a network host using a connection oriented socket type.
7007 * You create a #GSocketClient object, set any options you want, and then
7008 * call a sync or async connect operation, which returns a #GSocketConnection
7009 * subclass on success.
7011 * The type of the #GSocketConnection object returned depends on the type of
7012 * the underlying socket that is in use. For instance, for a TCP/IP connection
7013 * it will be a #GTcpConnection.
7015 * As #GSocketClient is a lightweight object, you don't need to cache it. You
7016 * can just create a new one any time you need one.
7023 * SECTION:gsocketconnectable
7024 * @short_description: Interface for potential socket endpoints
7025 * @include: gio/gio.h
7027 * Objects that describe one or more potential socket endpoints
7028 * implement #GSocketConnectable. Callers can then use
7029 * g_socket_connectable_enumerate() to get a #GSocketAddressEnumerator
7030 * to try out each socket address in turn until one succeeds, as shown
7031 * in the sample code below.
7033 * |[<!-- language="C" -->
7034 * MyConnectionType *
7035 * connect_to_host (const char *hostname,
7037 * GCancellable *cancellable,
7040 * MyConnection *conn = NULL;
7041 * GSocketConnectable *addr;
7042 * GSocketAddressEnumerator *enumerator;
7043 * GSocketAddress *sockaddr;
7044 * GError *conn_error = NULL;
7046 * addr = g_network_address_new (hostname, port);
7047 * enumerator = g_socket_connectable_enumerate (addr);
7048 * g_object_unref (addr);
7050 * // Try each sockaddr until we succeed. Record the first connection error,
7051 * // but not any further ones (since they'll probably be basically the same
7053 * while (!conn && (sockaddr = g_socket_address_enumerator_next (enumerator, cancellable, error))
7055 * conn = connect_to_sockaddr (sockaddr, conn_error ? NULL : &conn_error);
7056 * g_object_unref (sockaddr);
7058 * g_object_unref (enumerator);
7064 * // We couldn't connect to the first address, but we succeeded
7065 * // in connecting to a later address.
7066 * g_error_free (conn_error);
7072 * /// Either initial lookup failed, or else the caller cancelled us.
7074 * g_error_free (conn_error);
7079 * g_error_propagate (error, conn_error);
7088 * SECTION:gsocketconnection
7089 * @short_description: A socket connection
7090 * @include: gio/gio.h
7091 * @see_also: #GIOStream, #GSocketClient, #GSocketListener
7093 * #GSocketConnection is a #GIOStream for a connected socket. They
7094 * can be created either by #GSocketClient when connecting to a host,
7095 * or by #GSocketListener when accepting a new client.
7097 * The type of the #GSocketConnection object returned from these calls
7098 * depends on the type of the underlying socket that is in use. For
7099 * instance, for a TCP/IP connection it will be a #GTcpConnection.
7101 * Choosing what type of object to construct is done with the socket
7102 * connection factory, and it is possible for 3rd parties to register
7103 * custom socket connection types for specific combination of socket
7104 * family/type/protocol using g_socket_connection_factory_register_type().
7106 * To close a #GSocketConnection, use g_io_stream_close(). Closing both
7107 * substreams of the #GIOStream separately will not close the underlying
7115 * SECTION:gsocketcontrolmessage
7116 * @title: GSocketControlMessage
7117 * @short_description: A GSocket control message
7118 * @include: gio/gio.h
7119 * @see_also: #GSocket.
7121 * A #GSocketControlMessage is a special-purpose utility message that
7122 * can be sent to or received from a #GSocket. These types of
7123 * messages are often called "ancillary data".
7125 * The message can represent some sort of special instruction to or
7126 * information from the socket or can represent a special kind of
7127 * transfer to the peer (for example, sending a file descriptor over
7130 * These messages are sent with g_socket_send_message() and received
7131 * with g_socket_receive_message().
7133 * To extend the set of control message that can be sent, subclass this
7134 * class and override the get_size, get_level, get_type and serialize
7137 * To extend the set of control messages that can be received, subclass
7138 * this class and implement the deserialize method. Also, make sure your
7139 * class is registered with the GType typesystem before calling
7140 * g_socket_receive_message() to read such a message.
7147 * SECTION:gsocketlistener
7148 * @title: GSocketListener
7149 * @short_description: Helper for accepting network client connections
7150 * @include: gio/gio.h
7151 * @see_also: #GThreadedSocketService, #GSocketService.
7153 * A #GSocketListener is an object that keeps track of a set
7154 * of server sockets and helps you accept sockets from any of the
7155 * socket, either sync or async.
7157 * If you want to implement a network server, also look at #GSocketService
7158 * and #GThreadedSocketService which are subclass of #GSocketListener
7159 * that makes this even easier.
7166 * SECTION:gsocketservice
7167 * @title: GSocketService
7168 * @short_description: Make it easy to implement a network service
7169 * @include: gio/gio.h
7170 * @see_also: #GThreadedSocketService, #GSocketListener.
7172 * A #GSocketService is an object that represents a service that
7173 * is provided to the network or over local sockets. When a new
7174 * connection is made to the service the #GSocketService::incoming
7175 * signal is emitted.
7177 * A #GSocketService is a subclass of #GSocketListener and you need
7178 * to add the addresses you want to accept connections on with the
7179 * #GSocketListener APIs.
7181 * There are two options for implementing a network service based on
7182 * #GSocketService. The first is to create the service using
7183 * g_socket_service_new() and to connect to the #GSocketService::incoming
7184 * signal. The second is to subclass #GSocketService and override the
7185 * default signal handler implementation.
7187 * In either case, the handler must immediately return, or else it
7188 * will block additional incoming connections from being serviced.
7189 * If you are interested in writing connection handlers that contain
7190 * blocking code then see #GThreadedSocketService.
7192 * The socket service runs on the main loop of the
7193 * [thread-default context][g-main-context-push-thread-default-context]
7194 * of the thread it is created in, and is not
7195 * threadsafe in general. However, the calls to start and stop the
7196 * service are thread-safe so these can be used from threads that
7197 * handle incoming clients.
7204 * SECTION:gsrvtarget
7205 * @short_description: DNS SRV record target
7206 * @include: gio/gio.h
7208 * SRV (service) records are used by some network protocols to provide
7209 * service-specific aliasing and load-balancing. For example, XMPP
7210 * (Jabber) uses SRV records to locate the XMPP server for a domain;
7211 * rather than connecting directly to "example.com" or assuming a
7212 * specific server hostname like "xmpp.example.com", an XMPP client
7213 * would look up the "xmpp-client" SRV record for "example.com", and
7214 * then connect to whatever host was pointed to by that record.
7216 * You can use g_resolver_lookup_service() or
7217 * g_resolver_lookup_service_async() to find the #GSrvTargets
7218 * for a given service. However, if you are simply planning to connect
7219 * to the remote service, you can use #GNetworkService's
7220 * #GSocketConnectable interface and not need to worry about
7221 * #GSrvTarget at all.
7226 * SECTION:gsubprocess
7227 * @title: GSubprocess
7228 * @short_description: Child processes
7229 * @include: gio/gio.h
7230 * @see_also: #GSubprocessLauncher
7232 * #GSubprocess allows the creation of and interaction with child
7235 * Processes can be communicated with using standard GIO-style APIs (ie:
7236 * #GInputStream, #GOutputStream). There are GIO-style APIs to wait for
7237 * process termination (ie: cancellable and with an asynchronous
7240 * There is an API to force a process to terminate, as well as a
7241 * race-free API for sending UNIX signals to a subprocess.
7243 * One major advantage that GIO brings over the core GLib library is
7244 * comprehensive API for asynchronous I/O, such
7245 * g_output_stream_splice_async(). This makes GSubprocess
7246 * significantly more powerful and flexible than equivalent APIs in
7247 * some other languages such as the `subprocess.py`
7248 * included with Python. For example, using #GSubprocess one could
7249 * create two child processes, reading standard output from the first,
7250 * processing it, and writing to the input stream of the second, all
7251 * without blocking the main loop.
7253 * A powerful g_subprocess_communicate() API is provided similar to the
7254 * `communicate()` method of `subprocess.py`. This enables very easy
7255 * interaction with a subprocess that has been opened with pipes.
7257 * #GSubprocess defaults to tight control over the file descriptors open
7258 * in the child process, avoiding dangling-fd issues that are caused by
7259 * a simple fork()/exec(). The only open file descriptors in the
7260 * spawned process are ones that were explicitly specified by the
7261 * #GSubprocess API (unless %G_SUBPROCESS_FLAGS_INHERIT_FDS was
7264 * #GSubprocess will quickly reap all child processes as they exit,
7265 * avoiding "zombie processes" remaining around for long periods of
7266 * time. g_subprocess_wait() can be used to wait for this to happen,
7267 * but it will happen even without the call being explicitly made.
7269 * As a matter of principle, #GSubprocess has no API that accepts
7270 * shell-style space-separated strings. It will, however, match the
7271 * typical shell behaviour of searching the PATH for executables that do
7272 * not contain a directory separator in their name.
7274 * #GSubprocess attempts to have a very simple API for most uses (ie:
7275 * spawning a subprocess with arguments and support for most typical
7276 * kinds of input and output redirection). See g_subprocess_new(). The
7277 * #GSubprocessLauncher API is provided for more complicated cases
7278 * (advanced types of redirection, environment variable manipulation,
7279 * change of working directory, child setup functions, etc).
7281 * A typical use of #GSubprocess will involve calling
7282 * g_subprocess_new(), followed by g_subprocess_wait_async() or
7283 * g_subprocess_wait(). After the process exits, the status can be
7284 * checked using functions such as g_subprocess_get_if_exited() (which
7285 * are similar to the familiar WIFEXITED-style POSIX macros).
7292 * SECTION:gsubprocesslauncher
7293 * @title: GSubprocess Launcher
7294 * @short_description: Environment options for launching a child process
7295 * @include: gio/gio.h
7297 * This class contains a set of options for launching child processes,
7298 * such as where its standard input and output will be directed, the
7299 * argument list, the environment, and more.
7301 * While the #GSubprocess class has high level functions covering
7302 * popular cases, use of this class allows access to more advanced
7303 * options. It can also be used to launch multiple subprocesses with
7304 * a similar configuration.
7312 * @short_description: Cancellable synchronous or asynchronous task
7314 * @include: gio/gio.h
7315 * @see_also: #GAsyncResult
7317 * A #GTask represents and manages a cancellable "task".
7319 * ## Asynchronous operations
7321 * The most common usage of #GTask is as a #GAsyncResult, to
7322 * manage data during an asynchronous operation. You call
7323 * g_task_new() in the "start" method, followed by
7324 * g_task_set_task_data() and the like if you need to keep some
7325 * additional data associated with the task, and then pass the
7326 * task object around through your asynchronous operation.
7327 * Eventually, you will call a method such as
7328 * g_task_return_pointer() or g_task_return_error(), which will
7329 * save the value you give it and then invoke the task's callback
7330 * function (waiting until the next iteration of the main
7331 * loop first, if necessary). The caller will pass the #GTask back
7332 * to the operation's finish function (as a #GAsyncResult), and
7333 * you can use g_task_propagate_pointer() or the like to extract
7336 * Here is an example for using GTask as a GAsyncResult:
7337 * |[<!-- language="C" -->
7339 * CakeFrostingType frosting;
7344 * decoration_data_free (DecorationData *decoration)
7346 * g_free (decoration->message);
7347 * g_slice_free (DecorationData, decoration);
7351 * baked_cb (Cake *cake,
7352 * gpointer user_data)
7354 * GTask *task = user_data;
7355 * DecorationData *decoration = g_task_get_task_data (task);
7356 * GError *error = NULL;
7360 * g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_NO_FLOUR,
7361 * "Go to the supermarket");
7362 * g_object_unref (task);
7366 * if (!cake_decorate (cake, decoration->frosting, decoration->message, &error))
7368 * g_object_unref (cake);
7369 * // g_task_return_error() takes ownership of error
7370 * g_task_return_error (task, error);
7371 * g_object_unref (task);
7375 * g_task_return_pointer (task, cake, g_object_unref);
7376 * g_object_unref (task);
7380 * baker_bake_cake_async (Baker *self,
7382 * CakeFlavor flavor,
7383 * CakeFrostingType frosting,
7384 * const char *message,
7385 * GCancellable *cancellable,
7386 * GAsyncReadyCallback callback,
7387 * gpointer user_data)
7390 * DecorationData *decoration;
7393 * task = g_task_new (self, cancellable, callback, user_data);
7396 * g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_TOO_SMALL,
7397 * "%ucm radius cakes are silly",
7399 * g_object_unref (task);
7403 * cake = _baker_get_cached_cake (self, radius, flavor, frosting, message);
7406 * // _baker_get_cached_cake() returns a reffed cake
7407 * g_task_return_pointer (task, cake, g_object_unref);
7408 * g_object_unref (task);
7412 * decoration = g_slice_new (DecorationData);
7413 * decoration->frosting = frosting;
7414 * decoration->message = g_strdup (message);
7415 * g_task_set_task_data (task, decoration, (GDestroyNotify) decoration_data_free);
7417 * _baker_begin_cake (self, radius, flavor, cancellable, baked_cb, task);
7421 * baker_bake_cake_finish (Baker *self,
7422 * GAsyncResult *result,
7425 * g_return_val_if_fail (g_task_is_valid (result, self), NULL);
7427 * return g_task_propagate_pointer (G_TASK (result), error);
7431 * ## Chained asynchronous operations
7433 * #GTask also tries to simplify asynchronous operations that
7434 * internally chain together several smaller asynchronous
7435 * operations. g_task_get_cancellable(), g_task_get_context(),
7436 * and g_task_get_priority() allow you to get back the task's
7437 * #GCancellable, #GMainContext, and [I/O priority][io-priority]
7438 * when starting a new subtask, so you don't have to keep track
7439 * of them yourself. g_task_attach_source() simplifies the case
7440 * of waiting for a source to fire (automatically using the correct
7441 * #GMainContext and priority).
7443 * Here is an example for chained asynchronous operations:
7444 * |[<!-- language="C" -->
7447 * CakeFrostingType frosting;
7452 * decoration_data_free (BakingData *bd)
7455 * g_object_unref (bd->cake);
7456 * g_free (bd->message);
7457 * g_slice_free (BakingData, bd);
7461 * decorated_cb (Cake *cake,
7462 * GAsyncResult *result,
7463 * gpointer user_data)
7465 * GTask *task = user_data;
7466 * GError *error = NULL;
7468 * if (!cake_decorate_finish (cake, result, &error))
7470 * g_object_unref (cake);
7471 * g_task_return_error (task, error);
7472 * g_object_unref (task);
7476 * // baking_data_free() will drop its ref on the cake, so we have to
7477 * // take another here to give to the caller.
7478 * g_task_return_pointer (result, g_object_ref (cake), g_object_unref);
7479 * g_object_unref (task);
7483 * decorator_ready (gpointer user_data)
7485 * GTask *task = user_data;
7486 * BakingData *bd = g_task_get_task_data (task);
7488 * cake_decorate_async (bd->cake, bd->frosting, bd->message,
7489 * g_task_get_cancellable (task),
7490 * decorated_cb, task);
7494 * baked_cb (Cake *cake,
7495 * gpointer user_data)
7497 * GTask *task = user_data;
7498 * BakingData *bd = g_task_get_task_data (task);
7499 * GError *error = NULL;
7503 * g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_NO_FLOUR,
7504 * "Go to the supermarket");
7505 * g_object_unref (task);
7511 * // Bail out now if the user has already cancelled
7512 * if (g_task_return_error_if_cancelled (task))
7514 * g_object_unref (task);
7518 * if (cake_decorator_available (cake))
7519 * decorator_ready (task);
7524 * source = cake_decorator_wait_source_new (cake);
7525 * // Attach @source to @task's GMainContext and have it call
7526 * // decorator_ready() when it is ready.
7527 * g_task_attach_source (task, source,
7528 * G_CALLBACK (decorator_ready));
7529 * g_source_unref (source);
7534 * baker_bake_cake_async (Baker *self,
7536 * CakeFlavor flavor,
7537 * CakeFrostingType frosting,
7538 * const char *message,
7540 * GCancellable *cancellable,
7541 * GAsyncReadyCallback callback,
7542 * gpointer user_data)
7547 * task = g_task_new (self, cancellable, callback, user_data);
7548 * g_task_set_priority (task, priority);
7550 * bd = g_slice_new0 (BakingData);
7551 * bd->frosting = frosting;
7552 * bd->message = g_strdup (message);
7553 * g_task_set_task_data (task, bd, (GDestroyNotify) baking_data_free);
7555 * _baker_begin_cake (self, radius, flavor, cancellable, baked_cb, task);
7559 * baker_bake_cake_finish (Baker *self,
7560 * GAsyncResult *result,
7563 * g_return_val_if_fail (g_task_is_valid (result, self), NULL);
7565 * return g_task_propagate_pointer (G_TASK (result), error);
7569 * ## Asynchronous operations from synchronous ones
7571 * You can use g_task_run_in_thread() to turn a synchronous
7572 * operation into an asynchronous one, by running it in a thread
7573 * which will then dispatch the result back to the caller's
7574 * #GMainContext when it completes.
7576 * Running a task in a thread:
7577 * |[<!-- language="C" -->
7580 * CakeFlavor flavor;
7581 * CakeFrostingType frosting;
7586 * cake_data_free (CakeData *cake_data)
7588 * g_free (cake_data->message);
7589 * g_slice_free (CakeData, cake_data);
7593 * bake_cake_thread (GTask *task,
7594 * gpointer source_object,
7595 * gpointer task_data,
7596 * GCancellable *cancellable)
7598 * Baker *self = source_object;
7599 * CakeData *cake_data = task_data;
7601 * GError *error = NULL;
7603 * cake = bake_cake (baker, cake_data->radius, cake_data->flavor,
7604 * cake_data->frosting, cake_data->message,
7605 * cancellable, &error);
7607 * g_task_return_pointer (task, cake, g_object_unref);
7609 * g_task_return_error (task, error);
7613 * baker_bake_cake_async (Baker *self,
7615 * CakeFlavor flavor,
7616 * CakeFrostingType frosting,
7617 * const char *message,
7618 * GCancellable *cancellable,
7619 * GAsyncReadyCallback callback,
7620 * gpointer user_data)
7622 * CakeData *cake_data;
7625 * cake_data = g_slice_new (CakeData);
7626 * cake_data->radius = radius;
7627 * cake_data->flavor = flavor;
7628 * cake_data->frosting = frosting;
7629 * cake_data->message = g_strdup (message);
7630 * task = g_task_new (self, cancellable, callback, user_data);
7631 * g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free);
7632 * g_task_run_in_thread (task, bake_cake_thread);
7633 * g_object_unref (task);
7637 * baker_bake_cake_finish (Baker *self,
7638 * GAsyncResult *result,
7641 * g_return_val_if_fail (g_task_is_valid (result, self), NULL);
7643 * return g_task_propagate_pointer (G_TASK (result), error);
7647 * ## Adding cancellability to uncancellable tasks
7649 * Finally, g_task_run_in_thread() and g_task_run_in_thread_sync()
7650 * can be used to turn an uncancellable operation into a
7651 * cancellable one. If you call g_task_set_return_on_cancel(),
7652 * passing %TRUE, then if the task's #GCancellable is cancelled,
7653 * it will return control back to the caller immediately, while
7654 * allowing the task thread to continue running in the background
7655 * (and simply discarding its result when it finally does finish).
7656 * Provided that the task thread is careful about how it uses
7657 * locks and other externally-visible resources, this allows you
7658 * to make "GLib-friendly" asynchronous and cancellable
7659 * synchronous variants of blocking APIs.
7661 * Cancelling a task:
7662 * |[<!-- language="C" -->
7664 * bake_cake_thread (GTask *task,
7665 * gpointer source_object,
7666 * gpointer task_data,
7667 * GCancellable *cancellable)
7669 * Baker *self = source_object;
7670 * CakeData *cake_data = task_data;
7672 * GError *error = NULL;
7674 * cake = bake_cake (baker, cake_data->radius, cake_data->flavor,
7675 * cake_data->frosting, cake_data->message,
7679 * g_task_return_error (task, error);
7683 * // If the task has already been cancelled, then we don't want to add
7684 * // the cake to the cake cache. Likewise, we don't want to have the
7685 * // task get cancelled in the middle of updating the cache.
7686 * // g_task_set_return_on_cancel() will return %TRUE here if it managed
7687 * // to disable return-on-cancel, or %FALSE if the task was cancelled
7688 * // before it could.
7689 * if (g_task_set_return_on_cancel (task, FALSE))
7691 * // If the caller cancels at this point, their
7692 * // GAsyncReadyCallback won't be invoked until we return,
7693 * // so we don't have to worry that this code will run at
7694 * // the same time as that code does. But if there were
7695 * // other functions that might look at the cake cache,
7696 * // then we'd probably need a GMutex here as well.
7697 * baker_add_cake_to_cache (baker, cake);
7698 * g_task_return_pointer (task, cake, g_object_unref);
7703 * baker_bake_cake_async (Baker *self,
7705 * CakeFlavor flavor,
7706 * CakeFrostingType frosting,
7707 * const char *message,
7708 * GCancellable *cancellable,
7709 * GAsyncReadyCallback callback,
7710 * gpointer user_data)
7712 * CakeData *cake_data;
7715 * cake_data = g_slice_new (CakeData);
7719 * task = g_task_new (self, cancellable, callback, user_data);
7720 * g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free);
7721 * g_task_set_return_on_cancel (task, TRUE);
7722 * g_task_run_in_thread (task, bake_cake_thread);
7726 * baker_bake_cake_sync (Baker *self,
7728 * CakeFlavor flavor,
7729 * CakeFrostingType frosting,
7730 * const char *message,
7731 * GCancellable *cancellable,
7734 * CakeData *cake_data;
7738 * cake_data = g_slice_new (CakeData);
7742 * task = g_task_new (self, cancellable, NULL, NULL);
7743 * g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free);
7744 * g_task_set_return_on_cancel (task, TRUE);
7745 * g_task_run_in_thread_sync (task, bake_cake_thread);
7747 * cake = g_task_propagate_pointer (task, error);
7748 * g_object_unref (task);
7753 * ## Porting from GSimpleAsyncResult
7755 * #GTask's API attempts to be simpler than #GSimpleAsyncResult's
7757 * - You can save task-specific data with g_task_set_task_data(), and
7758 * retrieve it later with g_task_get_task_data(). This replaces the
7759 * abuse of g_simple_async_result_set_op_res_gpointer() for the same
7760 * purpose with #GSimpleAsyncResult.
7761 * - In addition to the task data, #GTask also keeps track of the
7762 * [priority][io-priority], #GCancellable, and
7763 * #GMainContext associated with the task, so tasks that consist of
7764 * a chain of simpler asynchronous operations will have easy access
7765 * to those values when starting each sub-task.
7766 * - g_task_return_error_if_cancelled() provides simplified
7767 * handling for cancellation. In addition, cancellation
7768 * overrides any other #GTask return value by default, like
7769 * #GSimpleAsyncResult does when
7770 * g_simple_async_result_set_check_cancellable() is called.
7771 * (You can use g_task_set_check_cancellable() to turn off that
7772 * behavior.) On the other hand, g_task_run_in_thread()
7773 * guarantees that it will always run your
7774 * `task_func`, even if the task's #GCancellable
7775 * is already cancelled before the task gets a chance to run;
7776 * you can start your `task_func` with a
7777 * g_task_return_error_if_cancelled() check if you need the
7779 * - The "return" methods (eg, g_task_return_pointer())
7780 * automatically cause the task to be "completed" as well, and
7781 * there is no need to worry about the "complete" vs "complete
7782 * in idle" distinction. (#GTask automatically figures out
7783 * whether the task's callback can be invoked directly, or
7784 * if it needs to be sent to another #GMainContext, or delayed
7785 * until the next iteration of the current #GMainContext.)
7786 * - The "finish" functions for #GTask-based operations are generally
7787 * much simpler than #GSimpleAsyncResult ones, normally consisting
7788 * of only a single call to g_task_propagate_pointer() or the like.
7789 * Since g_task_propagate_pointer() "steals" the return value from
7790 * the #GTask, it is not necessary to juggle pointers around to
7791 * prevent it from being freed twice.
7792 * - With #GSimpleAsyncResult, it was common to call
7793 * g_simple_async_result_propagate_error() from the
7794 * `_finish()` wrapper function, and have
7795 * virtual method implementations only deal with successful
7796 * returns. This behavior is deprecated, because it makes it
7797 * difficult for a subclass to chain to a parent class's async
7798 * methods. Instead, the wrapper function should just be a
7799 * simple wrapper, and the virtual method should call an
7800 * appropriate `g_task_propagate_` function.
7801 * Note that wrapper methods can now use
7802 * g_async_result_legacy_propagate_error() to do old-style
7803 * #GSimpleAsyncResult error-returning behavior, and
7804 * g_async_result_is_tagged() to check if a result is tagged as
7805 * having come from the `_async()` wrapper
7806 * function (for "short-circuit" results, such as when passing
7807 * 0 to g_input_stream_read_async()).
7812 * SECTION:gtcpconnection
7813 * @title: GTcpConnection
7814 * @short_description: A TCP GSocketConnection
7815 * @include: gio/gio.h
7816 * @see_also: #GSocketConnection.
7818 * This is the subclass of #GSocketConnection that is created
7819 * for TCP/IP sockets.
7826 * SECTION:gtcpwrapperconnection
7827 * @title: GTcpWrapperConnection
7828 * @short_description: Wrapper for non-GSocketConnection-based,
7829 * GSocket-based GIOStreams
7830 * @include: gio/gio.h
7831 * @see_also: #GSocketConnection.
7833 * A #GTcpWrapperConnection can be used to wrap a #GIOStream that is
7834 * based on a #GSocket, but which is not actually a
7835 * #GSocketConnection. This is used by #GSocketClient so that it can
7836 * always return a #GSocketConnection, even when the connection it has
7837 * actually created is not directly a #GSocketConnection.
7845 * @short_description: D-Bus testing helper
7846 * @include: gio/gio.h
7848 * A helper class for testing code which uses D-Bus without touching the user's
7851 * Note that #GTestDBus modifies the user’s environment, calling setenv().
7852 * This is not thread-safe, so all #GTestDBus calls should be completed before
7853 * threads are spawned, or should have appropriate locking to ensure no access
7854 * conflicts to environment variables shared between #GTestDBus and other
7857 * ## Creating unit tests using GTestDBus
7859 * Testing of D-Bus services can be tricky because normally we only ever run
7860 * D-Bus services over an existing instance of the D-Bus daemon thus we
7861 * usually don't activate D-Bus services that are not yet installed into the
7862 * target system. The #GTestDBus object makes this easier for us by taking care
7863 * of the lower level tasks such as running a private D-Bus daemon and looking
7864 * up uninstalled services in customizable locations, typically in your source
7867 * The first thing you will need is a separate service description file for the
7868 * D-Bus daemon. Typically a `services` subdirectory of your `tests` directory
7869 * is a good place to put this file.
7871 * The service file should list your service along with an absolute path to the
7872 * uninstalled service executable in your source tree. Using autotools we would
7873 * achieve this by adding a file such as `my-server.service.in` in the services
7874 * directory and have it processed by configure.
7877 * Name=org.gtk.GDBus.Examples.ObjectManager
7878 * Exec=@abs_top_builddir@/gio/tests/gdbus-example-objectmanager-server
7880 * You will also need to indicate this service directory in your test
7881 * fixtures, so you will need to pass the path while compiling your
7882 * test cases. Typically this is done with autotools with an added
7883 * preprocessor flag specified to compile your tests such as:
7885 * -DTEST_SERVICES=\""$(abs_top_builddir)/tests/services"\"
7887 * Once you have a service definition file which is local to your source tree,
7888 * you can proceed to set up a GTest fixture using the #GTestDBus scaffolding.
7890 * An example of a test fixture for D-Bus services can be found
7892 * [gdbus-test-fixture.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-test-fixture.c)
7894 * Note that these examples only deal with isolating the D-Bus aspect of your
7895 * service. To successfully run isolated unit tests on your service you may need
7896 * some additional modifications to your test case fixture. For example; if your
7897 * service uses GSettings and installs a schema then it is important that your test service
7898 * not load the schema in the ordinary installed location (chances are that your service
7899 * and schema files are not yet installed, or worse; there is an older version of the
7900 * schema file sitting in the install location).
7902 * Most of the time we can work around these obstacles using the
7903 * environment. Since the environment is inherited by the D-Bus daemon
7904 * created by #GTestDBus and then in turn inherited by any services the
7905 * D-Bus daemon activates, using the setup routine for your fixture is
7906 * a practical place to help sandbox your runtime environment. For the
7907 * rather typical GSettings case we can work around this by setting
7908 * `GSETTINGS_SCHEMA_DIR` to the in tree directory holding your schemas
7909 * in the above fixture_setup() routine.
7911 * The GSettings schemas need to be locally pre-compiled for this to work. This can be achieved
7912 * by compiling the schemas locally as a step before running test cases, an autotools setup might
7913 * do the following in the directory holding schemas:
7916 * $(GLIB_COMPILE_SCHEMAS) .
7918 * CLEANFILES += gschemas.compiled
7924 * SECTION:gthemedicon
7925 * @short_description: Icon theming support
7926 * @include: gio/gio.h
7927 * @see_also: #GIcon, #GLoadableIcon
7929 * #GThemedIcon is an implementation of #GIcon that supports icon themes.
7930 * #GThemedIcon contains a list of all of the icons present in an icon
7931 * theme, so that icons can be looked up quickly. #GThemedIcon does
7932 * not provide actual pixmaps for icons, just the icon names.
7933 * Ideally something like gtk_icon_theme_choose_icon() should be used to
7934 * resolve the list of names so that fallback icons work nicely with
7935 * themes that inherit other themes.
7940 * SECTION:gthreadedsocketservice
7941 * @title: GThreadedSocketService
7942 * @short_description: A threaded GSocketService
7943 * @include: gio/gio.h
7944 * @see_also: #GSocketService.
7946 * A #GThreadedSocketService is a simple subclass of #GSocketService
7947 * that handles incoming connections by creating a worker thread and
7948 * dispatching the connection to it by emitting the
7949 * #GThreadedSocketService::run signal in the new thread.
7951 * The signal handler may perform blocking IO and need not return
7952 * until the connection is closed.
7954 * The service is implemented using a thread pool, so there is a
7955 * limited amount of threads available to serve incoming requests.
7956 * The service automatically stops the #GSocketService from accepting
7957 * new connections when all threads are busy.
7959 * As with #GSocketService, you may connect to #GThreadedSocketService::run,
7960 * or subclass and override the default handler.
7966 * @title: TLS Overview
7967 * @short_description: TLS (aka SSL) support for GSocketConnection
7968 * @include: gio/gio.h
7970 * #GTlsConnection and related classes provide TLS (Transport Layer
7971 * Security, previously known as SSL, Secure Sockets Layer) support for
7972 * gio-based network streams.
7974 * In the simplest case, for a client connection, you can just set the
7975 * #GSocketClient:tls flag on a #GSocketClient, and then any
7976 * connections created by that client will have TLS negotiated
7977 * automatically, using appropriate default settings, and rejecting
7978 * any invalid or self-signed certificates (unless you change that
7979 * default by setting the #GSocketClient:tls-validation-flags
7980 * property). The returned object will be a #GTcpWrapperConnection,
7981 * which wraps the underlying #GTlsClientConnection.
7983 * For greater control, you can create your own #GTlsClientConnection,
7984 * wrapping a #GSocketConnection (or an arbitrary #GIOStream with
7985 * pollable input and output streams) and then connect to its signals,
7986 * such as #GTlsConnection::accept-certificate, before starting the
7989 * Server-side TLS is similar, using #GTlsServerConnection. At the
7990 * moment, there is no support for automatically wrapping server-side
7991 * connections in the way #GSocketClient does for client-side
7997 * SECTION:gtlsbackend
7998 * @title: GTlsBackend
7999 * @short_description: TLS backend implementation
8000 * @include: gio/gio.h
8005 * SECTION:gtlscertificate
8006 * @title: GTlsCertificate
8007 * @short_description: TLS certificate
8008 * @include: gio/gio.h
8009 * @see_also: #GTlsConnection
8011 * A certificate used for TLS authentication and encryption.
8012 * This can represent either a certificate only (eg, the certificate
8013 * received by a client from a server), or the combination of
8014 * a certificate and a private key (which is needed when acting as a
8015 * #GTlsServerConnection).
8022 * SECTION:gtlsclientconnection
8023 * @short_description: TLS client-side connection
8024 * @include: gio/gio.h
8026 * #GTlsClientConnection is the client-side subclass of
8027 * #GTlsConnection, representing a client-side TLS connection.
8032 * SECTION:gtlsconnection
8033 * @short_description: TLS connection type
8034 * @include: gio/gio.h
8036 * #GTlsConnection is the base TLS connection class type, which wraps
8037 * a #GIOStream and provides TLS encryption on top of it. Its
8038 * subclasses, #GTlsClientConnection and #GTlsServerConnection,
8039 * implement client-side and server-side TLS, respectively.
8046 * SECTION:gtlsdatabase
8047 * @short_description: TLS database type
8048 * @include: gio/gio.h
8050 * #GTlsDatabase is used to lookup certificates and other information
8051 * from a certificate or key store. It is an abstract base class which
8052 * TLS library specific subtypes override.
8054 * Most common client applications will not directly interact with
8055 * #GTlsDatabase. It is used internally by #GTlsConnection.
8062 * SECTION:gtlsfiledatabase
8063 * @short_description: TLS file based database type
8064 * @include: gio/gio.h
8066 * #GTlsFileDatabase is implemented by #GTlsDatabase objects which load
8067 * their certificate information from a file. It is an interface which
8068 * TLS library specific subtypes implement.
8075 * SECTION:gtlsinteraction
8076 * @short_description: Interaction with the user during TLS operations.
8077 * @include: gio/gio.h
8079 * #GTlsInteraction provides a mechanism for the TLS connection and database
8080 * code to interact with the user. It can be used to ask the user for passwords.
8082 * To use a #GTlsInteraction with a TLS connection use
8083 * g_tls_connection_set_interaction().
8085 * Callers should instantiate a derived class that implements the various
8086 * interaction methods to show the required dialogs.
8088 * Callers should use the 'invoke' functions like
8089 * g_tls_interaction_invoke_ask_password() to run interaction methods. These
8090 * functions make sure that the interaction is invoked in the main loop
8091 * and not in the current thread, if the current thread is not running the
8094 * Derived classes can choose to implement whichever interactions methods they'd
8095 * like to support by overriding those virtual methods in their class
8096 * initialization function. Any interactions not implemented will return
8097 * %G_TLS_INTERACTION_UNHANDLED. If a derived class implements an async method,
8098 * it must also implement the corresponding finish method.
8103 * SECTION:gtlspassword
8104 * @title: GTlsPassword
8105 * @short_description: TLS Passwords for prompting
8106 * @include: gio/gio.h
8108 * Holds a password used in TLS.
8113 * SECTION:gtlsserverconnection
8114 * @short_description: TLS server-side connection
8115 * @include: gio/gio.h
8117 * #GTlsServerConnection is the server-side subclass of #GTlsConnection,
8118 * representing a server-side TLS connection.
8125 * SECTION:gunixconnection
8126 * @title: GUnixConnection
8127 * @short_description: A UNIX domain GSocketConnection
8128 * @include: gio/gunixconnection.h
8129 * @see_also: #GSocketConnection.
8131 * This is the subclass of #GSocketConnection that is created
8132 * for UNIX domain sockets.
8134 * It contains functions to do some of the UNIX socket specific
8135 * functionality like passing file descriptors.
8137 * Note that `<gio/gunixconnection.h>` belongs to the UNIX-specific
8138 * GIO interfaces, thus you have to use the `gio-unix-2.0.pc`
8139 * pkg-config file when using it.
8146 * SECTION:gunixcredentialsmessage
8147 * @title: GUnixCredentialsMessage
8148 * @short_description: A GSocketControlMessage containing credentials
8149 * @include: gio/gunixcredentialsmessage.h
8150 * @see_also: #GUnixConnection, #GSocketControlMessage
8152 * This #GSocketControlMessage contains a #GCredentials instance. It
8153 * may be sent using g_socket_send_message() and received using
8154 * g_socket_receive_message() over UNIX sockets (ie: sockets in the
8155 * %G_SOCKET_FAMILY_UNIX family).
8157 * For an easier way to send and receive credentials over
8158 * stream-oriented UNIX sockets, see
8159 * g_unix_connection_send_credentials() and
8160 * g_unix_connection_receive_credentials(). To receive credentials of
8161 * a foreign process connected to a socket, use
8162 * g_socket_get_credentials().
8167 * SECTION:gunixfdlist
8168 * @title: GUnixFDList
8169 * @short_description: An object containing a set of UNIX file descriptors
8170 * @include: gio/gunixfdlist.h
8171 * @see_also: #GUnixFDMessage
8173 * A #GUnixFDList contains a list of file descriptors. It owns the file
8174 * descriptors that it contains, closing them when finalized.
8176 * It may be wrapped in a #GUnixFDMessage and sent over a #GSocket in
8177 * the %G_SOCKET_ADDRESS_UNIX family by using g_socket_send_message()
8178 * and received using g_socket_receive_message().
8180 * Note that `<gio/gunixfdlist.h>` belongs to the UNIX-specific GIO
8181 * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config
8182 * file when using it.
8187 * SECTION:gunixfdmessage
8188 * @title: GUnixFDMessage
8189 * @short_description: A GSocketControlMessage containing a GUnixFDList
8190 * @include: gio/gunixfdmessage.h
8191 * @see_also: #GUnixConnection, #GUnixFDList, #GSocketControlMessage
8193 * This #GSocketControlMessage contains a #GUnixFDList.
8194 * It may be sent using g_socket_send_message() and received using
8195 * g_socket_receive_message() over UNIX sockets (ie: sockets in the
8196 * %G_SOCKET_ADDRESS_UNIX family). The file descriptors are copied
8197 * between processes by the kernel.
8199 * For an easier way to send and receive file descriptors over
8200 * stream-oriented UNIX sockets, see g_unix_connection_send_fd() and
8201 * g_unix_connection_receive_fd().
8203 * Note that `<gio/gunixfdmessage.h>` belongs to the UNIX-specific GIO
8204 * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config
8205 * file when using it.
8210 * SECTION:gunixinputstream
8211 * @short_description: Streaming input operations for UNIX file descriptors
8212 * @include: gio/gunixinputstream.h
8213 * @see_also: #GInputStream
8215 * #GUnixInputStream implements #GInputStream for reading from a UNIX
8216 * file descriptor, including asynchronous operations. (If the file
8217 * descriptor refers to a socket or pipe, this will use poll() to do
8218 * asynchronous I/O. If it refers to a regular file, it will fall back
8219 * to doing asynchronous I/O in another thread.)
8221 * Note that `<gio/gunixinputstream.h>` belongs to the UNIX-specific GIO
8222 * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config
8223 * file when using it.
8228 * SECTION:gunixmounts
8229 * @include: gio/gunixmounts.h
8230 * @short_description: UNIX mounts
8232 * Routines for managing mounted UNIX mount points and paths.
8234 * Note that `<gio/gunixmounts.h>` belongs to the UNIX-specific GIO
8235 * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config
8236 * file when using it.
8241 * SECTION:gunixoutputstream
8242 * @short_description: Streaming output operations for UNIX file descriptors
8243 * @include: gio/gunixoutputstream.h
8244 * @see_also: #GOutputStream
8246 * #GUnixOutputStream implements #GOutputStream for writing to a UNIX
8247 * file descriptor, including asynchronous operations. (If the file
8248 * descriptor refers to a socket or pipe, this will use poll() to do
8249 * asynchronous I/O. If it refers to a regular file, it will fall back
8250 * to doing asynchronous I/O in another thread.)
8252 * Note that `<gio/gunixoutputstream.h>` belongs to the UNIX-specific GIO
8253 * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config file
8259 * SECTION:gunixsocketaddress
8260 * @short_description: UNIX GSocketAddress
8261 * @include: gio/gunixsocketaddress.h
8263 * Support for UNIX-domain (also known as local) sockets.
8265 * UNIX domain sockets are generally visible in the filesystem.
8266 * However, some systems support abstract socket names which are not
8267 * visible in the filesystem and not affected by the filesystem
8268 * permissions, visibility, etc. Currently this is only supported
8269 * under Linux. If you attempt to use abstract sockets on other
8270 * systems, function calls may return %G_IO_ERROR_NOT_SUPPORTED
8271 * errors. You can use g_unix_socket_address_abstract_names_supported()
8272 * to see if abstract names are supported.
8274 * Note that `<gio/gunixsocketaddress.h>` belongs to the UNIX-specific GIO
8275 * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config file
8282 * @short_description: Virtual File System
8283 * @include: gio/gio.h
8285 * Entry point for using GIO functionality.
8291 * @short_description: Volume management
8292 * @include: gio/gio.h
8294 * The #GVolume interface represents user-visible objects that can be
8295 * mounted. Note, when porting from GnomeVFS, #GVolume is the moral
8296 * equivalent of #GnomeVFSDrive.
8298 * Mounting a #GVolume instance is an asynchronous operation. For more
8299 * information about asynchronous operations, see #GAsyncResult and
8300 * #GTask. To mount a #GVolume, first call g_volume_mount() with (at
8301 * least) the #GVolume instance, optionally a #GMountOperation object
8302 * and a #GAsyncReadyCallback.
8304 * Typically, one will only want to pass %NULL for the
8305 * #GMountOperation if automounting all volumes when a desktop session
8306 * starts since it's not desirable to put up a lot of dialogs asking
8309 * The callback will be fired when the operation has resolved (either
8310 * with success or failure), and a #GAsyncReady structure will be
8311 * passed to the callback. That callback should then call
8312 * g_volume_mount_finish() with the #GVolume instance and the
8313 * #GAsyncReady data to see if the operation was completed
8314 * successfully. If an @error is present when g_volume_mount_finish()
8315 * is called, then it will be filled with any error information.
8317 * ## Volume Identifiers # {#volume-identifier}
8319 * It is sometimes necessary to directly access the underlying
8320 * operating system object behind a volume (e.g. for passing a volume
8321 * to an application via the commandline). For this purpose, GIO
8322 * allows to obtain an 'identifier' for the volume. There can be
8323 * different kinds of identifiers, such as Hal UDIs, filesystem labels,
8324 * traditional Unix devices (e.g. `/dev/sda2`), UUIDs. GIO uses predefined
8325 * strings as names for the different kinds of identifiers:
8326 * #G_VOLUME_IDENTIFIER_KIND_HAL_UDI, #G_VOLUME_IDENTIFIER_KIND_LABEL, etc.
8327 * Use g_volume_get_identifier() to obtain an identifier for a volume.
8330 * Note that #G_VOLUME_IDENTIFIER_KIND_HAL_UDI will only be available
8331 * when the gvfs hal volume monitor is in use. Other volume monitors
8332 * will generally be able to provide the #G_VOLUME_IDENTIFIER_KIND_UNIX_DEVICE
8333 * identifier, which can be used to obtain a hal device by means of
8334 * libhal_manager_find_device_string_match().
8339 * SECTION:gvolumemonitor
8340 * @short_description: Volume Monitor
8341 * @include: gio/gio.h
8342 * @see_also: #GFileMonitor
8344 * #GVolumeMonitor is for listing the user interesting devices and volumes
8345 * on the computer. In other words, what a file selector or file manager
8346 * would show in a sidebar.
8348 * #GVolumeMonitor is not
8349 * [thread-default-context aware][g-main-context-push-thread-default],
8350 * and so should not be used other than from the main thread, with no
8351 * thread-default-context active.
8356 * SECTION:gwin32inputstream
8357 * @short_description: Streaming input operations for Windows file handles
8358 * @include: gio/gwin32inputstream.h
8359 * @see_also: #GInputStream
8361 * #GWin32InputStream implements #GInputStream for reading from a
8362 * Windows file handle.
8364 * Note that `<gio/gwin32inputstream.h>` belongs to the Windows-specific GIO
8365 * interfaces, thus you have to use the `gio-windows-2.0.pc` pkg-config file
8371 * SECTION:gwin32outputstream
8372 * @short_description: Streaming output operations for Windows file handles
8373 * @include: gio/gwin32outputstream.h
8374 * @see_also: #GOutputStream
8376 * #GWin32OutputStream implements #GOutputStream for writing to a
8377 * Windows file handle.
8379 * Note that `<gio/gwin32outputstream.h>` belongs to the Windows-specific GIO
8380 * interfaces, thus you have to use the `gio-windows-2.0.pc` pkg-config file
8386 * SECTION:gzcompressor
8387 * @short_description: Zlib compressor
8388 * @include: gio/gio.h
8390 * #GZlibCompressor is an implementation of #GConverter that
8391 * compresses data using zlib.
8396 * SECTION:gzdecompressor
8397 * @short_description: Zlib decompressor
8398 * @include: gio/gio.h
8400 * #GZlibDecompressor is an implementation of #GConverter that
8401 * decompresses data compressed with zlib.
8406 * _GFreedesktopDBus:
8408 * Abstract interface type for the D-Bus interface <link linkend="gdbus-interface-org-freedesktop-DBus.top_of_page">org.freedesktop.DBus</link>.
8413 * _GFreedesktopDBus::handle-add-match:
8414 * @object: A #_GFreedesktopDBus.
8415 * @invocation: A #GDBusMethodInvocation.
8416 * @arg_rule: Argument passed by remote caller.
8418 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.AddMatch">AddMatch()</link> D-Bus method.
8420 * 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.
8422 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
8427 * _GFreedesktopDBus::handle-get-connection-selinux-security-context:
8428 * @object: A #_GFreedesktopDBus.
8429 * @invocation: A #GDBusMethodInvocation.
8430 * @arg_name: Argument passed by remote caller.
8432 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionSELinuxSecurityContext">GetConnectionSELinuxSecurityContext()</link> D-Bus method.
8434 * 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.
8436 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
8441 * _GFreedesktopDBus::handle-get-connection-unix-process-id:
8442 * @object: A #_GFreedesktopDBus.
8443 * @invocation: A #GDBusMethodInvocation.
8444 * @arg_name: Argument passed by remote caller.
8446 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionUnixProcessID">GetConnectionUnixProcessID()</link> D-Bus method.
8448 * 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.
8450 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
8455 * _GFreedesktopDBus::handle-get-connection-unix-user:
8456 * @object: A #_GFreedesktopDBus.
8457 * @invocation: A #GDBusMethodInvocation.
8458 * @arg_name: Argument passed by remote caller.
8460 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionUnixUser">GetConnectionUnixUser()</link> D-Bus method.
8462 * 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.
8464 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
8469 * _GFreedesktopDBus::handle-get-id:
8470 * @object: A #_GFreedesktopDBus.
8471 * @invocation: A #GDBusMethodInvocation.
8473 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.GetId">GetId()</link> D-Bus method.
8475 * 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.
8477 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
8482 * _GFreedesktopDBus::handle-get-name-owner:
8483 * @object: A #_GFreedesktopDBus.
8484 * @invocation: A #GDBusMethodInvocation.
8485 * @arg_name: Argument passed by remote caller.
8487 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.GetNameOwner">GetNameOwner()</link> D-Bus method.
8489 * 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.
8491 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
8496 * _GFreedesktopDBus::handle-hello:
8497 * @object: A #_GFreedesktopDBus.
8498 * @invocation: A #GDBusMethodInvocation.
8500 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.Hello">Hello()</link> D-Bus method.
8502 * 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.
8504 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
8509 * _GFreedesktopDBus::handle-list-activatable-names:
8510 * @object: A #_GFreedesktopDBus.
8511 * @invocation: A #GDBusMethodInvocation.
8513 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.ListActivatableNames">ListActivatableNames()</link> D-Bus method.
8515 * 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.
8517 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
8522 * _GFreedesktopDBus::handle-list-names:
8523 * @object: A #_GFreedesktopDBus.
8524 * @invocation: A #GDBusMethodInvocation.
8526 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.ListNames">ListNames()</link> D-Bus method.
8528 * 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.
8530 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
8535 * _GFreedesktopDBus::handle-list-queued-owners:
8536 * @object: A #_GFreedesktopDBus.
8537 * @invocation: A #GDBusMethodInvocation.
8538 * @arg_name: Argument passed by remote caller.
8540 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.ListQueuedOwners">ListQueuedOwners()</link> D-Bus method.
8542 * 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.
8544 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
8549 * _GFreedesktopDBus::handle-name-has-owner:
8550 * @object: A #_GFreedesktopDBus.
8551 * @invocation: A #GDBusMethodInvocation.
8552 * @arg_name: Argument passed by remote caller.
8554 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.NameHasOwner">NameHasOwner()</link> D-Bus method.
8556 * 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.
8558 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
8563 * _GFreedesktopDBus::handle-release-name:
8564 * @object: A #_GFreedesktopDBus.
8565 * @invocation: A #GDBusMethodInvocation.
8566 * @arg_name: Argument passed by remote caller.
8568 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.ReleaseName">ReleaseName()</link> D-Bus method.
8570 * 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.
8572 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
8577 * _GFreedesktopDBus::handle-reload-config:
8578 * @object: A #_GFreedesktopDBus.
8579 * @invocation: A #GDBusMethodInvocation.
8581 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.ReloadConfig">ReloadConfig()</link> D-Bus method.
8583 * 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.
8585 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
8590 * _GFreedesktopDBus::handle-remove-match:
8591 * @object: A #_GFreedesktopDBus.
8592 * @invocation: A #GDBusMethodInvocation.
8593 * @arg_rule: Argument passed by remote caller.
8595 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.RemoveMatch">RemoveMatch()</link> D-Bus method.
8597 * 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.
8599 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
8604 * _GFreedesktopDBus::handle-request-name:
8605 * @object: A #_GFreedesktopDBus.
8606 * @invocation: A #GDBusMethodInvocation.
8607 * @arg_name: Argument passed by remote caller.
8608 * @arg_flags: Argument passed by remote caller.
8610 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.RequestName">RequestName()</link> D-Bus method.
8612 * 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.
8614 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
8619 * _GFreedesktopDBus::handle-start-service-by-name:
8620 * @object: A #_GFreedesktopDBus.
8621 * @invocation: A #GDBusMethodInvocation.
8622 * @arg_name: Argument passed by remote caller.
8623 * @arg_flags: Argument passed by remote caller.
8625 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.StartServiceByName">StartServiceByName()</link> D-Bus method.
8627 * 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.
8629 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
8634 * _GFreedesktopDBus::handle-update-activation-environment:
8635 * @object: A #_GFreedesktopDBus.
8636 * @invocation: A #GDBusMethodInvocation.
8637 * @arg_environment: Argument passed by remote caller.
8639 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.UpdateActivationEnvironment">UpdateActivationEnvironment()</link> D-Bus method.
8641 * 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.
8643 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
8648 * _GFreedesktopDBus::name-acquired:
8649 * @object: A #_GFreedesktopDBus.
8650 * @arg_name: Argument.
8652 * 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.
8654 * 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.
8659 * _GFreedesktopDBus::name-lost:
8660 * @object: A #_GFreedesktopDBus.
8661 * @arg_name: Argument.
8663 * 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.
8665 * 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.
8670 * _GFreedesktopDBus::name-owner-changed:
8671 * @object: A #_GFreedesktopDBus.
8672 * @arg_name: Argument.
8673 * @arg_old_owner: Argument.
8674 * @arg_new_owner: Argument.
8676 * 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.
8678 * 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.
8683 * _GFreedesktopDBusIface:
8684 * @parent_iface: The parent interface.
8685 * @handle_add_match: Handler for the #_GFreedesktopDBus::handle-add-match signal.
8686 * @handle_get_connection_selinux_security_context: Handler for the #_GFreedesktopDBus::handle-get-connection-selinux-security-context signal.
8687 * @handle_get_connection_unix_process_id: Handler for the #_GFreedesktopDBus::handle-get-connection-unix-process-id signal.
8688 * @handle_get_connection_unix_user: Handler for the #_GFreedesktopDBus::handle-get-connection-unix-user signal.
8689 * @handle_get_id: Handler for the #_GFreedesktopDBus::handle-get-id signal.
8690 * @handle_get_name_owner: Handler for the #_GFreedesktopDBus::handle-get-name-owner signal.
8691 * @handle_hello: Handler for the #_GFreedesktopDBus::handle-hello signal.
8692 * @handle_list_activatable_names: Handler for the #_GFreedesktopDBus::handle-list-activatable-names signal.
8693 * @handle_list_names: Handler for the #_GFreedesktopDBus::handle-list-names signal.
8694 * @handle_list_queued_owners: Handler for the #_GFreedesktopDBus::handle-list-queued-owners signal.
8695 * @handle_name_has_owner: Handler for the #_GFreedesktopDBus::handle-name-has-owner signal.
8696 * @handle_release_name: Handler for the #_GFreedesktopDBus::handle-release-name signal.
8697 * @handle_reload_config: Handler for the #_GFreedesktopDBus::handle-reload-config signal.
8698 * @handle_remove_match: Handler for the #_GFreedesktopDBus::handle-remove-match signal.
8699 * @handle_request_name: Handler for the #_GFreedesktopDBus::handle-request-name signal.
8700 * @handle_start_service_by_name: Handler for the #_GFreedesktopDBus::handle-start-service-by-name signal.
8701 * @handle_update_activation_environment: Handler for the #_GFreedesktopDBus::handle-update-activation-environment signal.
8702 * @name_acquired: Handler for the #_GFreedesktopDBus::name-acquired signal.
8703 * @name_lost: Handler for the #_GFreedesktopDBus::name-lost signal.
8704 * @name_owner_changed: Handler for the #_GFreedesktopDBus::name-owner-changed signal.
8706 * Virtual table for the D-Bus interface <link linkend="gdbus-interface-org-freedesktop-DBus.top_of_page">org.freedesktop.DBus</link>.
8711 * _GFreedesktopDBusProxy:
8713 * The #_GFreedesktopDBusProxy structure contains only private data and should only be accessed using the provided API.
8718 * _GFreedesktopDBusProxyClass:
8719 * @parent_class: The parent class.
8721 * Class structure for #_GFreedesktopDBusProxy.
8726 * _GFreedesktopDBusSkeleton:
8728 * The #_GFreedesktopDBusSkeleton structure contains only private data and should only be accessed using the provided API.
8733 * _GFreedesktopDBusSkeletonClass:
8734 * @parent_class: The parent class.
8736 * Class structure for #_GFreedesktopDBusSkeleton.
8741 * _g_dbus_initialize:
8743 * Does various one-time init things such as
8745 * - registering the G_DBUS_ERROR error domain
8746 * - parses the G_DBUS_DEBUG environment variable
8751 * _g_file_attribute_value_as_string:
8752 * @attr: a #GFileAttributeValue.
8754 * Converts a #GFileAttributeValue to a string for display.
8755 * The returned string should be freed when no longer needed.
8757 * Returns: a string from the @attr, %NULL on error, or "<invalid>"
8758 * if @attr is of type %G_FILE_ATTRIBUTE_TYPE_INVALID.
8763 * _g_file_attribute_value_clear:
8764 * @attr: a #GFileAttributeValue.
8766 * Clears the value of @attr and sets its type to
8767 * %G_FILE_ATTRIBUTE_TYPE_INVALID.
8772 * _g_file_attribute_value_free:
8773 * @attr: a #GFileAttributeValue.
8775 * Frees the memory used by @attr.
8780 * _g_file_attribute_value_get_boolean:
8781 * @attr: a #GFileAttributeValue.
8783 * Gets the boolean value from a file attribute value. If the value is not the
8784 * right type then %FALSE will be returned.
8786 * Returns: the boolean value contained within the attribute, or %FALSE.
8791 * _g_file_attribute_value_get_byte_string:
8792 * @attr: a #GFileAttributeValue.
8794 * Gets the byte string from a file attribute value. If the value is not the
8795 * right type then %NULL will be returned.
8797 * Returns: the byte string contained within the attribute or %NULL.
8802 * _g_file_attribute_value_get_int32:
8803 * @attr: a #GFileAttributeValue.
8805 * Gets the signed 32-bit integer from a file attribute value. If the value
8806 * is not the right type then 0 will be returned.
8808 * Returns: the signed 32-bit integer from the attribute, or 0.
8813 * _g_file_attribute_value_get_int64:
8814 * @attr: a #GFileAttributeValue.
8816 * Gets the signed 64-bit integer from a file attribute value. If the value
8817 * is not the right type then 0 will be returned.
8819 * Returns: the signed 64-bit integer from the attribute, or 0.
8824 * _g_file_attribute_value_get_object:
8825 * @attr: a #GFileAttributeValue.
8827 * Gets the GObject from a file attribute value. If the value
8828 * is not the right type then %NULL will be returned.
8830 * Returns: the GObject from the attribute, or %NULL.
8835 * _g_file_attribute_value_get_string:
8836 * @attr: a #GFileAttributeValue.
8838 * Gets the string from a file attribute value. If the value is not the
8839 * right type then %NULL will be returned.
8841 * Returns: the UTF-8 string value contained within the attribute, or %NULL.
8846 * _g_file_attribute_value_get_uint32:
8847 * @attr: a #GFileAttributeValue.
8849 * Gets the unsigned 32-bit integer from a file attribute value. If the value
8850 * is not the right type then 0 will be returned.
8852 * Returns: the unsigned 32-bit integer from the attribute, or 0.
8857 * _g_file_attribute_value_get_uint64:
8858 * @attr: a #GFileAttributeValue.
8860 * Gets the unsigned 64-bit integer from a file attribute value. If the value
8861 * is not the right type then 0 will be returned.
8863 * Returns: the unsigned 64-bit integer from the attribute, or 0.
8868 * _g_file_attribute_value_new:
8870 * Creates a new file attribute.
8872 * Returns: a #GFileAttributeValue.
8877 * _g_file_attribute_value_set_boolean:
8878 * @attr: a #GFileAttributeValue.
8879 * @value: a #gboolean to set within the type.
8881 * Sets the attribute value to the given boolean value.
8886 * _g_file_attribute_value_set_byte_string:
8887 * @attr: a #GFileAttributeValue.
8888 * @string: a byte string to set within the type.
8890 * Sets the attribute value to a given byte string.
8895 * _g_file_attribute_value_set_int32:
8896 * @attr: a #GFileAttributeValue.
8897 * @value: a #gint32 to set within the type.
8899 * Sets the attribute value to the given signed 32-bit integer.
8904 * _g_file_attribute_value_set_int64:
8905 * @attr: a #GFileAttributeValue.
8906 * @value: a #gint64 to set within the type.
8908 * Sets the attribute value to a given signed 64-bit integer.
8913 * _g_file_attribute_value_set_object:
8914 * @attr: a #GFileAttributeValue.
8917 * Sets the attribute to contain the value @obj.
8918 * The @attr references the GObject internally.
8923 * _g_file_attribute_value_set_string:
8924 * @attr: a #GFileAttributeValue.
8925 * @string: a UTF-8 string to set within the type.
8927 * Sets the attribute value to a given UTF-8 string.
8932 * _g_file_attribute_value_set_uint32:
8933 * @attr: a #GFileAttributeValue.
8934 * @value: a #guint32 to set within the type.
8936 * Sets the attribute value to the given unsigned 32-bit integer.
8941 * _g_file_attribute_value_set_uint64:
8942 * @attr: a #GFileAttributeValue.
8943 * @value: a #guint64 to set within the type.
8945 * Sets the attribute value to a given unsigned 64-bit integer.
8950 * _g_freedesktop_dbus_call_add_match:
8951 * @proxy: A #_GFreedesktopDBusProxy.
8952 * @arg_rule: Argument to pass with the method invocation.
8953 * @cancellable: (allow-none): A #GCancellable or %NULL.
8954 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
8955 * @user_data: User data to pass to @callback.
8957 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.AddMatch">AddMatch()</link> D-Bus method on @proxy.
8958 * 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.
8959 * You can then call _g_freedesktop_dbus_call_add_match_finish() to get the result of the operation.
8961 * See _g_freedesktop_dbus_call_add_match_sync() for the synchronous, blocking version of this method.
8966 * _g_freedesktop_dbus_call_add_match_finish:
8967 * @proxy: A #_GFreedesktopDBusProxy.
8968 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_add_match().
8969 * @error: Return location for error or %NULL.
8971 * Finishes an operation started with _g_freedesktop_dbus_call_add_match().
8973 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
8978 * _g_freedesktop_dbus_call_add_match_sync:
8979 * @proxy: A #_GFreedesktopDBusProxy.
8980 * @arg_rule: Argument to pass with the method invocation.
8981 * @cancellable: (allow-none): A #GCancellable or %NULL.
8982 * @error: Return location for error or %NULL.
8984 * 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.
8986 * See _g_freedesktop_dbus_call_add_match() for the asynchronous version of this method.
8988 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
8993 * _g_freedesktop_dbus_call_get_connection_selinux_security_context:
8994 * @proxy: A #_GFreedesktopDBusProxy.
8995 * @arg_name: Argument to pass with the method invocation.
8996 * @cancellable: (allow-none): A #GCancellable or %NULL.
8997 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
8998 * @user_data: User data to pass to @callback.
9000 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionSELinuxSecurityContext">GetConnectionSELinuxSecurityContext()</link> D-Bus method on @proxy.
9001 * 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.
9002 * You can then call _g_freedesktop_dbus_call_get_connection_selinux_security_context_finish() to get the result of the operation.
9004 * See _g_freedesktop_dbus_call_get_connection_selinux_security_context_sync() for the synchronous, blocking version of this method.
9009 * _g_freedesktop_dbus_call_get_connection_selinux_security_context_finish:
9010 * @proxy: A #_GFreedesktopDBusProxy.
9011 * @out_security_context: (out): Return location for return parameter or %NULL to ignore.
9012 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_get_connection_selinux_security_context().
9013 * @error: Return location for error or %NULL.
9015 * Finishes an operation started with _g_freedesktop_dbus_call_get_connection_selinux_security_context().
9017 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9022 * _g_freedesktop_dbus_call_get_connection_selinux_security_context_sync:
9023 * @proxy: A #_GFreedesktopDBusProxy.
9024 * @arg_name: Argument to pass with the method invocation.
9025 * @out_security_context: (out): Return location for return parameter or %NULL to ignore.
9026 * @cancellable: (allow-none): A #GCancellable or %NULL.
9027 * @error: Return location for error or %NULL.
9029 * 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.
9031 * See _g_freedesktop_dbus_call_get_connection_selinux_security_context() for the asynchronous version of this method.
9033 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9038 * _g_freedesktop_dbus_call_get_connection_unix_process_id:
9039 * @proxy: A #_GFreedesktopDBusProxy.
9040 * @arg_name: Argument to pass with the method invocation.
9041 * @cancellable: (allow-none): A #GCancellable or %NULL.
9042 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
9043 * @user_data: User data to pass to @callback.
9045 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionUnixProcessID">GetConnectionUnixProcessID()</link> D-Bus method on @proxy.
9046 * 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.
9047 * You can then call _g_freedesktop_dbus_call_get_connection_unix_process_id_finish() to get the result of the operation.
9049 * See _g_freedesktop_dbus_call_get_connection_unix_process_id_sync() for the synchronous, blocking version of this method.
9054 * _g_freedesktop_dbus_call_get_connection_unix_process_id_finish:
9055 * @proxy: A #_GFreedesktopDBusProxy.
9056 * @out_pid: (out): Return location for return parameter or %NULL to ignore.
9057 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_get_connection_unix_process_id().
9058 * @error: Return location for error or %NULL.
9060 * Finishes an operation started with _g_freedesktop_dbus_call_get_connection_unix_process_id().
9062 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9067 * _g_freedesktop_dbus_call_get_connection_unix_process_id_sync:
9068 * @proxy: A #_GFreedesktopDBusProxy.
9069 * @arg_name: Argument to pass with the method invocation.
9070 * @out_pid: (out): Return location for return parameter or %NULL to ignore.
9071 * @cancellable: (allow-none): A #GCancellable or %NULL.
9072 * @error: Return location for error or %NULL.
9074 * 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.
9076 * See _g_freedesktop_dbus_call_get_connection_unix_process_id() for the asynchronous version of this method.
9078 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9083 * _g_freedesktop_dbus_call_get_connection_unix_user:
9084 * @proxy: A #_GFreedesktopDBusProxy.
9085 * @arg_name: Argument to pass with the method invocation.
9086 * @cancellable: (allow-none): A #GCancellable or %NULL.
9087 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
9088 * @user_data: User data to pass to @callback.
9090 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionUnixUser">GetConnectionUnixUser()</link> D-Bus method on @proxy.
9091 * 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.
9092 * You can then call _g_freedesktop_dbus_call_get_connection_unix_user_finish() to get the result of the operation.
9094 * See _g_freedesktop_dbus_call_get_connection_unix_user_sync() for the synchronous, blocking version of this method.
9099 * _g_freedesktop_dbus_call_get_connection_unix_user_finish:
9100 * @proxy: A #_GFreedesktopDBusProxy.
9101 * @out_uid: (out): Return location for return parameter or %NULL to ignore.
9102 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_get_connection_unix_user().
9103 * @error: Return location for error or %NULL.
9105 * Finishes an operation started with _g_freedesktop_dbus_call_get_connection_unix_user().
9107 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9112 * _g_freedesktop_dbus_call_get_connection_unix_user_sync:
9113 * @proxy: A #_GFreedesktopDBusProxy.
9114 * @arg_name: Argument to pass with the method invocation.
9115 * @out_uid: (out): Return location for return parameter or %NULL to ignore.
9116 * @cancellable: (allow-none): A #GCancellable or %NULL.
9117 * @error: Return location for error or %NULL.
9119 * 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.
9121 * See _g_freedesktop_dbus_call_get_connection_unix_user() for the asynchronous version of this method.
9123 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9128 * _g_freedesktop_dbus_call_get_id:
9129 * @proxy: A #_GFreedesktopDBusProxy.
9130 * @cancellable: (allow-none): A #GCancellable or %NULL.
9131 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
9132 * @user_data: User data to pass to @callback.
9134 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.GetId">GetId()</link> D-Bus method on @proxy.
9135 * 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.
9136 * You can then call _g_freedesktop_dbus_call_get_id_finish() to get the result of the operation.
9138 * See _g_freedesktop_dbus_call_get_id_sync() for the synchronous, blocking version of this method.
9143 * _g_freedesktop_dbus_call_get_id_finish:
9144 * @proxy: A #_GFreedesktopDBusProxy.
9145 * @out_unique_id: (out): Return location for return parameter or %NULL to ignore.
9146 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_get_id().
9147 * @error: Return location for error or %NULL.
9149 * Finishes an operation started with _g_freedesktop_dbus_call_get_id().
9151 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9156 * _g_freedesktop_dbus_call_get_id_sync:
9157 * @proxy: A #_GFreedesktopDBusProxy.
9158 * @out_unique_id: (out): Return location for return parameter or %NULL to ignore.
9159 * @cancellable: (allow-none): A #GCancellable or %NULL.
9160 * @error: Return location for error or %NULL.
9162 * 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.
9164 * See _g_freedesktop_dbus_call_get_id() for the asynchronous version of this method.
9166 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9171 * _g_freedesktop_dbus_call_get_name_owner:
9172 * @proxy: A #_GFreedesktopDBusProxy.
9173 * @arg_name: Argument to pass with the method invocation.
9174 * @cancellable: (allow-none): A #GCancellable or %NULL.
9175 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
9176 * @user_data: User data to pass to @callback.
9178 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.GetNameOwner">GetNameOwner()</link> D-Bus method on @proxy.
9179 * 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.
9180 * You can then call _g_freedesktop_dbus_call_get_name_owner_finish() to get the result of the operation.
9182 * See _g_freedesktop_dbus_call_get_name_owner_sync() for the synchronous, blocking version of this method.
9187 * _g_freedesktop_dbus_call_get_name_owner_finish:
9188 * @proxy: A #_GFreedesktopDBusProxy.
9189 * @out_unique_name: (out): Return location for return parameter or %NULL to ignore.
9190 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_get_name_owner().
9191 * @error: Return location for error or %NULL.
9193 * Finishes an operation started with _g_freedesktop_dbus_call_get_name_owner().
9195 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9200 * _g_freedesktop_dbus_call_get_name_owner_sync:
9201 * @proxy: A #_GFreedesktopDBusProxy.
9202 * @arg_name: Argument to pass with the method invocation.
9203 * @out_unique_name: (out): Return location for return parameter or %NULL to ignore.
9204 * @cancellable: (allow-none): A #GCancellable or %NULL.
9205 * @error: Return location for error or %NULL.
9207 * 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.
9209 * See _g_freedesktop_dbus_call_get_name_owner() for the asynchronous version of this method.
9211 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9216 * _g_freedesktop_dbus_call_hello:
9217 * @proxy: A #_GFreedesktopDBusProxy.
9218 * @cancellable: (allow-none): A #GCancellable or %NULL.
9219 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
9220 * @user_data: User data to pass to @callback.
9222 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.Hello">Hello()</link> D-Bus method on @proxy.
9223 * 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.
9224 * You can then call _g_freedesktop_dbus_call_hello_finish() to get the result of the operation.
9226 * See _g_freedesktop_dbus_call_hello_sync() for the synchronous, blocking version of this method.
9231 * _g_freedesktop_dbus_call_hello_finish:
9232 * @proxy: A #_GFreedesktopDBusProxy.
9233 * @out_assigned_name: (out): Return location for return parameter or %NULL to ignore.
9234 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_hello().
9235 * @error: Return location for error or %NULL.
9237 * Finishes an operation started with _g_freedesktop_dbus_call_hello().
9239 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9244 * _g_freedesktop_dbus_call_hello_sync:
9245 * @proxy: A #_GFreedesktopDBusProxy.
9246 * @out_assigned_name: (out): Return location for return parameter or %NULL to ignore.
9247 * @cancellable: (allow-none): A #GCancellable or %NULL.
9248 * @error: Return location for error or %NULL.
9250 * 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.
9252 * See _g_freedesktop_dbus_call_hello() for the asynchronous version of this method.
9254 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9259 * _g_freedesktop_dbus_call_list_activatable_names:
9260 * @proxy: A #_GFreedesktopDBusProxy.
9261 * @cancellable: (allow-none): A #GCancellable or %NULL.
9262 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
9263 * @user_data: User data to pass to @callback.
9265 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.ListActivatableNames">ListActivatableNames()</link> D-Bus method on @proxy.
9266 * 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.
9267 * You can then call _g_freedesktop_dbus_call_list_activatable_names_finish() to get the result of the operation.
9269 * See _g_freedesktop_dbus_call_list_activatable_names_sync() for the synchronous, blocking version of this method.
9274 * _g_freedesktop_dbus_call_list_activatable_names_finish:
9275 * @proxy: A #_GFreedesktopDBusProxy.
9276 * @out_activatable_names: (out): Return location for return parameter or %NULL to ignore.
9277 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_list_activatable_names().
9278 * @error: Return location for error or %NULL.
9280 * Finishes an operation started with _g_freedesktop_dbus_call_list_activatable_names().
9282 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9287 * _g_freedesktop_dbus_call_list_activatable_names_sync:
9288 * @proxy: A #_GFreedesktopDBusProxy.
9289 * @out_activatable_names: (out): Return location for return parameter or %NULL to ignore.
9290 * @cancellable: (allow-none): A #GCancellable or %NULL.
9291 * @error: Return location for error or %NULL.
9293 * 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.
9295 * See _g_freedesktop_dbus_call_list_activatable_names() for the asynchronous version of this method.
9297 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9302 * _g_freedesktop_dbus_call_list_names:
9303 * @proxy: A #_GFreedesktopDBusProxy.
9304 * @cancellable: (allow-none): A #GCancellable or %NULL.
9305 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
9306 * @user_data: User data to pass to @callback.
9308 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.ListNames">ListNames()</link> D-Bus method on @proxy.
9309 * 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.
9310 * You can then call _g_freedesktop_dbus_call_list_names_finish() to get the result of the operation.
9312 * See _g_freedesktop_dbus_call_list_names_sync() for the synchronous, blocking version of this method.
9317 * _g_freedesktop_dbus_call_list_names_finish:
9318 * @proxy: A #_GFreedesktopDBusProxy.
9319 * @out_names: (out): Return location for return parameter or %NULL to ignore.
9320 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_list_names().
9321 * @error: Return location for error or %NULL.
9323 * Finishes an operation started with _g_freedesktop_dbus_call_list_names().
9325 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9330 * _g_freedesktop_dbus_call_list_names_sync:
9331 * @proxy: A #_GFreedesktopDBusProxy.
9332 * @out_names: (out): Return location for return parameter or %NULL to ignore.
9333 * @cancellable: (allow-none): A #GCancellable or %NULL.
9334 * @error: Return location for error or %NULL.
9336 * 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.
9338 * See _g_freedesktop_dbus_call_list_names() for the asynchronous version of this method.
9340 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9345 * _g_freedesktop_dbus_call_list_queued_owners:
9346 * @proxy: A #_GFreedesktopDBusProxy.
9347 * @arg_name: Argument to pass with the method invocation.
9348 * @cancellable: (allow-none): A #GCancellable or %NULL.
9349 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
9350 * @user_data: User data to pass to @callback.
9352 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.ListQueuedOwners">ListQueuedOwners()</link> D-Bus method on @proxy.
9353 * 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.
9354 * You can then call _g_freedesktop_dbus_call_list_queued_owners_finish() to get the result of the operation.
9356 * See _g_freedesktop_dbus_call_list_queued_owners_sync() for the synchronous, blocking version of this method.
9361 * _g_freedesktop_dbus_call_list_queued_owners_finish:
9362 * @proxy: A #_GFreedesktopDBusProxy.
9363 * @out_queued_owners: (out): Return location for return parameter or %NULL to ignore.
9364 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_list_queued_owners().
9365 * @error: Return location for error or %NULL.
9367 * Finishes an operation started with _g_freedesktop_dbus_call_list_queued_owners().
9369 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9374 * _g_freedesktop_dbus_call_list_queued_owners_sync:
9375 * @proxy: A #_GFreedesktopDBusProxy.
9376 * @arg_name: Argument to pass with the method invocation.
9377 * @out_queued_owners: (out): Return location for return parameter or %NULL to ignore.
9378 * @cancellable: (allow-none): A #GCancellable or %NULL.
9379 * @error: Return location for error or %NULL.
9381 * 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.
9383 * See _g_freedesktop_dbus_call_list_queued_owners() for the asynchronous version of this method.
9385 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9390 * _g_freedesktop_dbus_call_name_has_owner:
9391 * @proxy: A #_GFreedesktopDBusProxy.
9392 * @arg_name: Argument to pass with the method invocation.
9393 * @cancellable: (allow-none): A #GCancellable or %NULL.
9394 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
9395 * @user_data: User data to pass to @callback.
9397 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.NameHasOwner">NameHasOwner()</link> D-Bus method on @proxy.
9398 * 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.
9399 * You can then call _g_freedesktop_dbus_call_name_has_owner_finish() to get the result of the operation.
9401 * See _g_freedesktop_dbus_call_name_has_owner_sync() for the synchronous, blocking version of this method.
9406 * _g_freedesktop_dbus_call_name_has_owner_finish:
9407 * @proxy: A #_GFreedesktopDBusProxy.
9408 * @out_has_owner: (out): Return location for return parameter or %NULL to ignore.
9409 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_name_has_owner().
9410 * @error: Return location for error or %NULL.
9412 * Finishes an operation started with _g_freedesktop_dbus_call_name_has_owner().
9414 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9419 * _g_freedesktop_dbus_call_name_has_owner_sync:
9420 * @proxy: A #_GFreedesktopDBusProxy.
9421 * @arg_name: Argument to pass with the method invocation.
9422 * @out_has_owner: (out): Return location for return parameter or %NULL to ignore.
9423 * @cancellable: (allow-none): A #GCancellable or %NULL.
9424 * @error: Return location for error or %NULL.
9426 * 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.
9428 * See _g_freedesktop_dbus_call_name_has_owner() for the asynchronous version of this method.
9430 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9435 * _g_freedesktop_dbus_call_release_name:
9436 * @proxy: A #_GFreedesktopDBusProxy.
9437 * @arg_name: Argument to pass with the method invocation.
9438 * @cancellable: (allow-none): A #GCancellable or %NULL.
9439 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
9440 * @user_data: User data to pass to @callback.
9442 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.ReleaseName">ReleaseName()</link> D-Bus method on @proxy.
9443 * 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.
9444 * You can then call _g_freedesktop_dbus_call_release_name_finish() to get the result of the operation.
9446 * See _g_freedesktop_dbus_call_release_name_sync() for the synchronous, blocking version of this method.
9451 * _g_freedesktop_dbus_call_release_name_finish:
9452 * @proxy: A #_GFreedesktopDBusProxy.
9453 * @out_value: (out): Return location for return parameter or %NULL to ignore.
9454 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_release_name().
9455 * @error: Return location for error or %NULL.
9457 * Finishes an operation started with _g_freedesktop_dbus_call_release_name().
9459 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9464 * _g_freedesktop_dbus_call_release_name_sync:
9465 * @proxy: A #_GFreedesktopDBusProxy.
9466 * @arg_name: Argument to pass with the method invocation.
9467 * @out_value: (out): Return location for return parameter or %NULL to ignore.
9468 * @cancellable: (allow-none): A #GCancellable or %NULL.
9469 * @error: Return location for error or %NULL.
9471 * 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.
9473 * See _g_freedesktop_dbus_call_release_name() for the asynchronous version of this method.
9475 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9480 * _g_freedesktop_dbus_call_reload_config:
9481 * @proxy: A #_GFreedesktopDBusProxy.
9482 * @cancellable: (allow-none): A #GCancellable or %NULL.
9483 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
9484 * @user_data: User data to pass to @callback.
9486 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.ReloadConfig">ReloadConfig()</link> D-Bus method on @proxy.
9487 * 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.
9488 * You can then call _g_freedesktop_dbus_call_reload_config_finish() to get the result of the operation.
9490 * See _g_freedesktop_dbus_call_reload_config_sync() for the synchronous, blocking version of this method.
9495 * _g_freedesktop_dbus_call_reload_config_finish:
9496 * @proxy: A #_GFreedesktopDBusProxy.
9497 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_reload_config().
9498 * @error: Return location for error or %NULL.
9500 * Finishes an operation started with _g_freedesktop_dbus_call_reload_config().
9502 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9507 * _g_freedesktop_dbus_call_reload_config_sync:
9508 * @proxy: A #_GFreedesktopDBusProxy.
9509 * @cancellable: (allow-none): A #GCancellable or %NULL.
9510 * @error: Return location for error or %NULL.
9512 * 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.
9514 * See _g_freedesktop_dbus_call_reload_config() for the asynchronous version of this method.
9516 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9521 * _g_freedesktop_dbus_call_remove_match:
9522 * @proxy: A #_GFreedesktopDBusProxy.
9523 * @arg_rule: Argument to pass with the method invocation.
9524 * @cancellable: (allow-none): A #GCancellable or %NULL.
9525 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
9526 * @user_data: User data to pass to @callback.
9528 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.RemoveMatch">RemoveMatch()</link> D-Bus method on @proxy.
9529 * 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.
9530 * You can then call _g_freedesktop_dbus_call_remove_match_finish() to get the result of the operation.
9532 * See _g_freedesktop_dbus_call_remove_match_sync() for the synchronous, blocking version of this method.
9537 * _g_freedesktop_dbus_call_remove_match_finish:
9538 * @proxy: A #_GFreedesktopDBusProxy.
9539 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_remove_match().
9540 * @error: Return location for error or %NULL.
9542 * Finishes an operation started with _g_freedesktop_dbus_call_remove_match().
9544 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9549 * _g_freedesktop_dbus_call_remove_match_sync:
9550 * @proxy: A #_GFreedesktopDBusProxy.
9551 * @arg_rule: Argument to pass with the method invocation.
9552 * @cancellable: (allow-none): A #GCancellable or %NULL.
9553 * @error: Return location for error or %NULL.
9555 * 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.
9557 * See _g_freedesktop_dbus_call_remove_match() for the asynchronous version of this method.
9559 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9564 * _g_freedesktop_dbus_call_request_name:
9565 * @proxy: A #_GFreedesktopDBusProxy.
9566 * @arg_name: Argument to pass with the method invocation.
9567 * @arg_flags: Argument to pass with the method invocation.
9568 * @cancellable: (allow-none): A #GCancellable or %NULL.
9569 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
9570 * @user_data: User data to pass to @callback.
9572 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.RequestName">RequestName()</link> D-Bus method on @proxy.
9573 * 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.
9574 * You can then call _g_freedesktop_dbus_call_request_name_finish() to get the result of the operation.
9576 * See _g_freedesktop_dbus_call_request_name_sync() for the synchronous, blocking version of this method.
9581 * _g_freedesktop_dbus_call_request_name_finish:
9582 * @proxy: A #_GFreedesktopDBusProxy.
9583 * @out_value: (out): Return location for return parameter or %NULL to ignore.
9584 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_request_name().
9585 * @error: Return location for error or %NULL.
9587 * Finishes an operation started with _g_freedesktop_dbus_call_request_name().
9589 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9594 * _g_freedesktop_dbus_call_request_name_sync:
9595 * @proxy: A #_GFreedesktopDBusProxy.
9596 * @arg_name: Argument to pass with the method invocation.
9597 * @arg_flags: Argument to pass with the method invocation.
9598 * @out_value: (out): Return location for return parameter or %NULL to ignore.
9599 * @cancellable: (allow-none): A #GCancellable or %NULL.
9600 * @error: Return location for error or %NULL.
9602 * 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.
9604 * See _g_freedesktop_dbus_call_request_name() for the asynchronous version of this method.
9606 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9611 * _g_freedesktop_dbus_call_start_service_by_name:
9612 * @proxy: A #_GFreedesktopDBusProxy.
9613 * @arg_name: Argument to pass with the method invocation.
9614 * @arg_flags: Argument to pass with the method invocation.
9615 * @cancellable: (allow-none): A #GCancellable or %NULL.
9616 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
9617 * @user_data: User data to pass to @callback.
9619 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.StartServiceByName">StartServiceByName()</link> D-Bus method on @proxy.
9620 * 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.
9621 * You can then call _g_freedesktop_dbus_call_start_service_by_name_finish() to get the result of the operation.
9623 * See _g_freedesktop_dbus_call_start_service_by_name_sync() for the synchronous, blocking version of this method.
9628 * _g_freedesktop_dbus_call_start_service_by_name_finish:
9629 * @proxy: A #_GFreedesktopDBusProxy.
9630 * @out_value: (out): Return location for return parameter or %NULL to ignore.
9631 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_start_service_by_name().
9632 * @error: Return location for error or %NULL.
9634 * Finishes an operation started with _g_freedesktop_dbus_call_start_service_by_name().
9636 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9641 * _g_freedesktop_dbus_call_start_service_by_name_sync:
9642 * @proxy: A #_GFreedesktopDBusProxy.
9643 * @arg_name: Argument to pass with the method invocation.
9644 * @arg_flags: Argument to pass with the method invocation.
9645 * @out_value: (out): Return location for return parameter or %NULL to ignore.
9646 * @cancellable: (allow-none): A #GCancellable or %NULL.
9647 * @error: Return location for error or %NULL.
9649 * 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.
9651 * See _g_freedesktop_dbus_call_start_service_by_name() for the asynchronous version of this method.
9653 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9658 * _g_freedesktop_dbus_call_update_activation_environment:
9659 * @proxy: A #_GFreedesktopDBusProxy.
9660 * @arg_environment: Argument to pass with the method invocation.
9661 * @cancellable: (allow-none): A #GCancellable or %NULL.
9662 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
9663 * @user_data: User data to pass to @callback.
9665 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.UpdateActivationEnvironment">UpdateActivationEnvironment()</link> D-Bus method on @proxy.
9666 * 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.
9667 * You can then call _g_freedesktop_dbus_call_update_activation_environment_finish() to get the result of the operation.
9669 * See _g_freedesktop_dbus_call_update_activation_environment_sync() for the synchronous, blocking version of this method.
9674 * _g_freedesktop_dbus_call_update_activation_environment_finish:
9675 * @proxy: A #_GFreedesktopDBusProxy.
9676 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_update_activation_environment().
9677 * @error: Return location for error or %NULL.
9679 * Finishes an operation started with _g_freedesktop_dbus_call_update_activation_environment().
9681 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9686 * _g_freedesktop_dbus_call_update_activation_environment_sync:
9687 * @proxy: A #_GFreedesktopDBusProxy.
9688 * @arg_environment: Argument to pass with the method invocation.
9689 * @cancellable: (allow-none): A #GCancellable or %NULL.
9690 * @error: Return location for error or %NULL.
9692 * 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.
9694 * See _g_freedesktop_dbus_call_update_activation_environment() for the asynchronous version of this method.
9696 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9701 * _g_freedesktop_dbus_complete_add_match:
9702 * @object: A #_GFreedesktopDBus.
9703 * @invocation: (transfer full): A #GDBusMethodInvocation.
9705 * 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.
9707 * This method will free @invocation, you cannot use it afterwards.
9712 * _g_freedesktop_dbus_complete_get_connection_selinux_security_context:
9713 * @object: A #_GFreedesktopDBus.
9714 * @invocation: (transfer full): A #GDBusMethodInvocation.
9715 * @security_context: Parameter to return.
9717 * 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.
9719 * This method will free @invocation, you cannot use it afterwards.
9724 * _g_freedesktop_dbus_complete_get_connection_unix_process_id:
9725 * @object: A #_GFreedesktopDBus.
9726 * @invocation: (transfer full): A #GDBusMethodInvocation.
9727 * @pid: Parameter to return.
9729 * 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.
9731 * This method will free @invocation, you cannot use it afterwards.
9736 * _g_freedesktop_dbus_complete_get_connection_unix_user:
9737 * @object: A #_GFreedesktopDBus.
9738 * @invocation: (transfer full): A #GDBusMethodInvocation.
9739 * @uid: Parameter to return.
9741 * 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.
9743 * This method will free @invocation, you cannot use it afterwards.
9748 * _g_freedesktop_dbus_complete_get_id:
9749 * @object: A #_GFreedesktopDBus.
9750 * @invocation: (transfer full): A #GDBusMethodInvocation.
9751 * @unique_id: Parameter to return.
9753 * 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.
9755 * This method will free @invocation, you cannot use it afterwards.
9760 * _g_freedesktop_dbus_complete_get_name_owner:
9761 * @object: A #_GFreedesktopDBus.
9762 * @invocation: (transfer full): A #GDBusMethodInvocation.
9763 * @unique_name: Parameter to return.
9765 * 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.
9767 * This method will free @invocation, you cannot use it afterwards.
9772 * _g_freedesktop_dbus_complete_hello:
9773 * @object: A #_GFreedesktopDBus.
9774 * @invocation: (transfer full): A #GDBusMethodInvocation.
9775 * @assigned_name: Parameter to return.
9777 * 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.
9779 * This method will free @invocation, you cannot use it afterwards.
9784 * _g_freedesktop_dbus_complete_list_activatable_names:
9785 * @object: A #_GFreedesktopDBus.
9786 * @invocation: (transfer full): A #GDBusMethodInvocation.
9787 * @activatable_names: Parameter to return.
9789 * 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.
9791 * This method will free @invocation, you cannot use it afterwards.
9796 * _g_freedesktop_dbus_complete_list_names:
9797 * @object: A #_GFreedesktopDBus.
9798 * @invocation: (transfer full): A #GDBusMethodInvocation.
9799 * @names: Parameter to return.
9801 * 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.
9803 * This method will free @invocation, you cannot use it afterwards.
9808 * _g_freedesktop_dbus_complete_list_queued_owners:
9809 * @object: A #_GFreedesktopDBus.
9810 * @invocation: (transfer full): A #GDBusMethodInvocation.
9811 * @queued_owners: Parameter to return.
9813 * 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.
9815 * This method will free @invocation, you cannot use it afterwards.
9820 * _g_freedesktop_dbus_complete_name_has_owner:
9821 * @object: A #_GFreedesktopDBus.
9822 * @invocation: (transfer full): A #GDBusMethodInvocation.
9823 * @has_owner: Parameter to return.
9825 * 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.
9827 * This method will free @invocation, you cannot use it afterwards.
9832 * _g_freedesktop_dbus_complete_release_name:
9833 * @object: A #_GFreedesktopDBus.
9834 * @invocation: (transfer full): A #GDBusMethodInvocation.
9835 * @value: Parameter to return.
9837 * 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.
9839 * This method will free @invocation, you cannot use it afterwards.
9844 * _g_freedesktop_dbus_complete_reload_config:
9845 * @object: A #_GFreedesktopDBus.
9846 * @invocation: (transfer full): A #GDBusMethodInvocation.
9848 * 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.
9850 * This method will free @invocation, you cannot use it afterwards.
9855 * _g_freedesktop_dbus_complete_remove_match:
9856 * @object: A #_GFreedesktopDBus.
9857 * @invocation: (transfer full): A #GDBusMethodInvocation.
9859 * 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.
9861 * This method will free @invocation, you cannot use it afterwards.
9866 * _g_freedesktop_dbus_complete_request_name:
9867 * @object: A #_GFreedesktopDBus.
9868 * @invocation: (transfer full): A #GDBusMethodInvocation.
9869 * @value: Parameter to return.
9871 * 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.
9873 * This method will free @invocation, you cannot use it afterwards.
9878 * _g_freedesktop_dbus_complete_start_service_by_name:
9879 * @object: A #_GFreedesktopDBus.
9880 * @invocation: (transfer full): A #GDBusMethodInvocation.
9881 * @value: Parameter to return.
9883 * 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.
9885 * This method will free @invocation, you cannot use it afterwards.
9890 * _g_freedesktop_dbus_complete_update_activation_environment:
9891 * @object: A #_GFreedesktopDBus.
9892 * @invocation: (transfer full): A #GDBusMethodInvocation.
9894 * 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.
9896 * This method will free @invocation, you cannot use it afterwards.
9901 * _g_freedesktop_dbus_emit_name_acquired:
9902 * @object: A #_GFreedesktopDBus.
9903 * @arg_name: Argument to pass with the signal.
9905 * Emits the <link linkend="gdbus-signal-org-freedesktop-DBus.NameAcquired">"NameAcquired"</link> D-Bus signal.
9910 * _g_freedesktop_dbus_emit_name_lost:
9911 * @object: A #_GFreedesktopDBus.
9912 * @arg_name: Argument to pass with the signal.
9914 * Emits the <link linkend="gdbus-signal-org-freedesktop-DBus.NameLost">"NameLost"</link> D-Bus signal.
9919 * _g_freedesktop_dbus_emit_name_owner_changed:
9920 * @object: A #_GFreedesktopDBus.
9921 * @arg_name: Argument to pass with the signal.
9922 * @arg_old_owner: Argument to pass with the signal.
9923 * @arg_new_owner: Argument to pass with the signal.
9925 * Emits the <link linkend="gdbus-signal-org-freedesktop-DBus.NameOwnerChanged">"NameOwnerChanged"</link> D-Bus signal.
9930 * _g_freedesktop_dbus_interface_info:
9932 * Gets a machine-readable description of the <link linkend="gdbus-interface-org-freedesktop-DBus.top_of_page">org.freedesktop.DBus</link> D-Bus interface.
9934 * Returns: (transfer none): A #GDBusInterfaceInfo. Do not free.
9939 * _g_freedesktop_dbus_override_properties:
9940 * @klass: The class structure for a #GObject<!-- -->-derived class.
9941 * @property_id_begin: The property id to assign to the first overridden property.
9943 * Overrides all #GObject properties in the #_GFreedesktopDBus interface for a concrete class.
9944 * The properties are overridden in the order they are defined.
9946 * Returns: The last property id.
9951 * _g_freedesktop_dbus_proxy_new:
9952 * @connection: A #GDBusConnection.
9953 * @flags: Flags from the #GDBusProxyFlags enumeration.
9954 * @name: (allow-none): A bus name (well-known or unique) or %NULL if @connection is not a message bus connection.
9955 * @object_path: An object path.
9956 * @cancellable: (allow-none): A #GCancellable or %NULL.
9957 * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
9958 * @user_data: User data to pass to @callback.
9960 * 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.
9962 * 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.
9963 * You can then call _g_freedesktop_dbus_proxy_new_finish() to get the result of the operation.
9965 * See _g_freedesktop_dbus_proxy_new_sync() for the synchronous, blocking version of this constructor.
9970 * _g_freedesktop_dbus_proxy_new_finish:
9971 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_proxy_new().
9972 * @error: Return location for error or %NULL
9974 * Finishes an operation started with _g_freedesktop_dbus_proxy_new().
9976 * Returns: (transfer full) (type _GFreedesktopDBusProxy): The constructed proxy object or %NULL if @error is set.
9981 * _g_freedesktop_dbus_proxy_new_for_bus:
9982 * @bus_type: A #GBusType.
9983 * @flags: Flags from the #GDBusProxyFlags enumeration.
9984 * @name: A bus name (well-known or unique).
9985 * @object_path: An object path.
9986 * @cancellable: (allow-none): A #GCancellable or %NULL.
9987 * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
9988 * @user_data: User data to pass to @callback.
9990 * Like _g_freedesktop_dbus_proxy_new() but takes a #GBusType instead of a #GDBusConnection.
9992 * 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.
9993 * You can then call _g_freedesktop_dbus_proxy_new_for_bus_finish() to get the result of the operation.
9995 * See _g_freedesktop_dbus_proxy_new_for_bus_sync() for the synchronous, blocking version of this constructor.
10000 * _g_freedesktop_dbus_proxy_new_for_bus_finish:
10001 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_proxy_new_for_bus().
10002 * @error: Return location for error or %NULL
10004 * Finishes an operation started with _g_freedesktop_dbus_proxy_new_for_bus().
10006 * Returns: (transfer full) (type _GFreedesktopDBusProxy): The constructed proxy object or %NULL if @error is set.
10011 * _g_freedesktop_dbus_proxy_new_for_bus_sync:
10012 * @bus_type: A #GBusType.
10013 * @flags: Flags from the #GDBusProxyFlags enumeration.
10014 * @name: A bus name (well-known or unique).
10015 * @object_path: An object path.
10016 * @cancellable: (allow-none): A #GCancellable or %NULL.
10017 * @error: Return location for error or %NULL
10019 * Like _g_freedesktop_dbus_proxy_new_sync() but takes a #GBusType instead of a #GDBusConnection.
10021 * The calling thread is blocked until a reply is received.
10023 * See _g_freedesktop_dbus_proxy_new_for_bus() for the asynchronous version of this constructor.
10025 * Returns: (transfer full) (type _GFreedesktopDBusProxy): The constructed proxy object or %NULL if @error is set.
10030 * _g_freedesktop_dbus_proxy_new_sync:
10031 * @connection: A #GDBusConnection.
10032 * @flags: Flags from the #GDBusProxyFlags enumeration.
10033 * @name: (allow-none): A bus name (well-known or unique) or %NULL if @connection is not a message bus connection.
10034 * @object_path: An object path.
10035 * @cancellable: (allow-none): A #GCancellable or %NULL.
10036 * @error: Return location for error or %NULL
10038 * 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.
10040 * The calling thread is blocked until a reply is received.
10042 * See _g_freedesktop_dbus_proxy_new() for the asynchronous version of this constructor.
10044 * Returns: (transfer full) (type _GFreedesktopDBusProxy): The constructed proxy object or %NULL if @error is set.
10049 * _g_freedesktop_dbus_skeleton_new:
10051 * Creates a skeleton object for the D-Bus interface <link linkend="gdbus-interface-org-freedesktop-DBus.top_of_page">org.freedesktop.DBus</link>.
10053 * Returns: (transfer full) (type _GFreedesktopDBusSkeleton): The skeleton object.
10058 * _g_io_module_get_default:
10059 * @extension_point: the name of an extension point
10060 * @envvar: (allow-none): the name of an environment variable to
10061 * override the default implementation.
10062 * @verify_func: (allow-none): a function to call to verify that
10063 * a given implementation is usable in the current environment.
10065 * Retrieves the default object implementing @extension_point.
10067 * If @envvar is not %NULL, and the environment variable with that
10068 * name is set, then the implementation it specifies will be tried
10069 * first. After that, or if @envvar is not set, all other
10070 * implementations will be tried in order of decreasing priority.
10072 * If an extension point implementation implements #GInitable, then
10073 * that implementation will only be used if it initializes
10074 * successfully. Otherwise, if @verify_func is not %NULL, then it will
10075 * be called on each candidate implementation after construction, to
10076 * check if it is actually usable or not.
10078 * The result is cached after it is generated the first time, and
10079 * the function is thread-safe.
10081 * Returns: (transfer none): an object implementing
10082 * @extension_point, or %NULL if there are no usable
10088 * _g_io_module_get_default_type:
10089 * @extension_point: the name of an extension point
10090 * @envvar: (allow-none): the name of an environment variable to
10091 * override the default implementation.
10092 * @is_supported_offset: a vtable offset, or zero
10094 * Retrieves the default class implementing @extension_point.
10096 * If @envvar is not %NULL, and the environment variable with that
10097 * name is set, then the implementation it specifies will be tried
10098 * first. After that, or if @envvar is not set, all other
10099 * implementations will be tried in order of decreasing priority.
10101 * If @is_supported_offset is non-zero, then it is the offset into the
10102 * class vtable at which there is a function that takes no arguments and
10103 * returns a boolean. This function will be called on each candidate
10104 * implementation to check if it is actually usable or not.
10106 * The result is cached after it is generated the first time, and
10107 * the function is thread-safe.
10109 * Returns: (transfer none): an object implementing
10110 * @extension_point, or %NULL if there are no usable
10116 * _g_win32_mount_new:
10117 * @volume_monitor: a #GVolumeMonitor.
10118 * @path: a win32 path.
10119 * @volume: usually NULL
10121 * Returns: a #GWin32Mount for the given win32 path.
10126 * g_action_activate:
10127 * @action: a #GAction
10128 * @parameter: (allow-none): the parameter to the activation
10130 * Activates the action.
10132 * @parameter must be the correct type of parameter for the action (ie:
10133 * the parameter type given at construction time). If the parameter
10134 * type was %NULL then @parameter must also be %NULL.
10136 * If the @parameter GVariant is floating, it is consumed.
10143 * g_action_change_state:
10144 * @action: a #GAction
10145 * @value: the new state
10147 * Request for the state of @action to be changed to @value.
10149 * The action must be stateful and @value must be of the correct type.
10150 * See g_action_get_state_type().
10152 * This call merely requests a change. The action may refuse to change
10153 * its state or may change its state to something other than @value.
10154 * See g_action_get_state_hint().
10156 * If the @value GVariant is floating, it is consumed.
10163 * g_action_get_enabled:
10164 * @action: a #GAction
10166 * Checks if @action is currently enabled.
10168 * An action must be enabled in order to be activated or in order to
10169 * have its state changed from outside callers.
10171 * Returns: whether the action is enabled
10177 * g_action_get_name:
10178 * @action: a #GAction
10180 * Queries the name of @action.
10182 * Returns: the name of the action
10188 * g_action_get_parameter_type:
10189 * @action: a #GAction
10191 * Queries the type of the parameter that must be given when activating
10194 * When activating the action using g_action_activate(), the #GVariant
10195 * given to that function must be of the type returned by this function.
10197 * In the case that this function returns %NULL, you must not give any
10198 * #GVariant, but %NULL instead.
10200 * Returns: (allow-none): the parameter type
10206 * g_action_get_state:
10207 * @action: a #GAction
10209 * Queries the current state of @action.
10211 * If the action is not stateful then %NULL will be returned. If the
10212 * action is stateful then the type of the return value is the type
10213 * given by g_action_get_state_type().
10215 * The return value (if non-%NULL) should be freed with
10216 * g_variant_unref() when it is no longer required.
10218 * Returns: (transfer full): the current state of the action
10224 * g_action_get_state_hint:
10225 * @action: a #GAction
10227 * Requests a hint about the valid range of values for the state of
10230 * If %NULL is returned it either means that the action is not stateful
10231 * or that there is no hint about the valid range of values for the
10232 * state of the action.
10234 * If a #GVariant array is returned then each item in the array is a
10235 * possible value for the state. If a #GVariant pair (ie: two-tuple) is
10236 * returned then the tuple specifies the inclusive lower and upper bound
10237 * of valid values for the state.
10239 * In any case, the information is merely a hint. It may be possible to
10240 * have a state value outside of the hinted range and setting a value
10241 * within the range may fail.
10243 * The return value (if non-%NULL) should be freed with
10244 * g_variant_unref() when it is no longer required.
10246 * Returns: (nullable) (transfer full): the state range hint
10252 * g_action_get_state_type:
10253 * @action: a #GAction
10255 * Queries the type of the state of @action.
10257 * If the action is stateful (e.g. created with
10258 * g_simple_action_new_stateful()) then this function returns the
10259 * #GVariantType of the state. This is the type of the initial value
10260 * given as the state. All calls to g_action_change_state() must give a
10261 * #GVariant of this type and g_action_get_state() will return a
10262 * #GVariant of the same type.
10264 * If the action is not stateful (e.g. created with g_simple_action_new())
10265 * then this function will return %NULL. In that case, g_action_get_state()
10266 * will return %NULL and you must not call g_action_change_state().
10268 * Returns: (allow-none): the state type, if the action is stateful
10274 * g_action_group_action_added:
10275 * @action_group: a #GActionGroup
10276 * @action_name: the name of an action in the group
10278 * Emits the #GActionGroup::action-added signal on @action_group.
10280 * This function should only be called by #GActionGroup implementations.
10287 * g_action_group_action_enabled_changed:
10288 * @action_group: a #GActionGroup
10289 * @action_name: the name of an action in the group
10290 * @enabled: whether or not the action is now enabled
10292 * Emits the #GActionGroup::action-enabled-changed signal on @action_group.
10294 * This function should only be called by #GActionGroup implementations.
10301 * g_action_group_action_removed:
10302 * @action_group: a #GActionGroup
10303 * @action_name: the name of an action in the group
10305 * Emits the #GActionGroup::action-removed signal on @action_group.
10307 * This function should only be called by #GActionGroup implementations.
10314 * g_action_group_action_state_changed:
10315 * @action_group: a #GActionGroup
10316 * @action_name: the name of an action in the group
10317 * @state: the new state of the named action
10319 * Emits the #GActionGroup::action-state-changed signal on @action_group.
10321 * This function should only be called by #GActionGroup implementations.
10328 * g_action_group_activate_action:
10329 * @action_group: a #GActionGroup
10330 * @action_name: the name of the action to activate
10331 * @parameter: (allow-none): parameters to the activation
10333 * Activate the named action within @action_group.
10335 * If the action is expecting a parameter, then the correct type of
10336 * parameter must be given as @parameter. If the action is expecting no
10337 * parameters then @parameter must be %NULL. See
10338 * g_action_group_get_action_parameter_type().
10345 * g_action_group_change_action_state:
10346 * @action_group: a #GActionGroup
10347 * @action_name: the name of the action to request the change on
10348 * @value: the new state
10350 * Request for the state of the named action within @action_group to be
10351 * changed to @value.
10353 * The action must be stateful and @value must be of the correct type.
10354 * See g_action_group_get_action_state_type().
10356 * This call merely requests a change. The action may refuse to change
10357 * its state or may change its state to something other than @value.
10358 * See g_action_group_get_action_state_hint().
10360 * If the @value GVariant is floating, it is consumed.
10367 * g_action_group_get_action_enabled:
10368 * @action_group: a #GActionGroup
10369 * @action_name: the name of the action to query
10371 * Checks if the named action within @action_group is currently enabled.
10373 * An action must be enabled in order to be activated or in order to
10374 * have its state changed from outside callers.
10376 * Returns: whether or not the action is currently enabled
10382 * g_action_group_get_action_parameter_type:
10383 * @action_group: a #GActionGroup
10384 * @action_name: the name of the action to query
10386 * Queries the type of the parameter that must be given when activating
10387 * the named action within @action_group.
10389 * When activating the action using g_action_group_activate_action(),
10390 * the #GVariant given to that function must be of the type returned
10391 * by this function.
10393 * In the case that this function returns %NULL, you must not give any
10394 * #GVariant, but %NULL instead.
10396 * The parameter type of a particular action will never change but it is
10397 * possible for an action to be removed and for a new action to be added
10398 * with the same name but a different parameter type.
10400 * Returns: (nullable): the parameter type
10406 * g_action_group_get_action_state:
10407 * @action_group: a #GActionGroup
10408 * @action_name: the name of the action to query
10410 * Queries the current state of the named action within @action_group.
10412 * If the action is not stateful then %NULL will be returned. If the
10413 * action is stateful then the type of the return value is the type
10414 * given by g_action_group_get_action_state_type().
10416 * The return value (if non-%NULL) should be freed with
10417 * g_variant_unref() when it is no longer required.
10419 * Returns: (nullable): the current state of the action
10425 * g_action_group_get_action_state_hint:
10426 * @action_group: a #GActionGroup
10427 * @action_name: the name of the action to query
10429 * Requests a hint about the valid range of values for the state of the
10430 * named action within @action_group.
10432 * If %NULL is returned it either means that the action is not stateful
10433 * or that there is no hint about the valid range of values for the
10434 * state of the action.
10436 * If a #GVariant array is returned then each item in the array is a
10437 * possible value for the state. If a #GVariant pair (ie: two-tuple) is
10438 * returned then the tuple specifies the inclusive lower and upper bound
10439 * of valid values for the state.
10441 * In any case, the information is merely a hint. It may be possible to
10442 * have a state value outside of the hinted range and setting a value
10443 * within the range may fail.
10445 * The return value (if non-%NULL) should be freed with
10446 * g_variant_unref() when it is no longer required.
10448 * Returns: (nullable) (transfer full): the state range hint
10454 * g_action_group_get_action_state_type:
10455 * @action_group: a #GActionGroup
10456 * @action_name: the name of the action to query
10458 * Queries the type of the state of the named action within
10461 * If the action is stateful then this function returns the
10462 * #GVariantType of the state. All calls to
10463 * g_action_group_change_action_state() must give a #GVariant of this
10464 * type and g_action_group_get_action_state() will return a #GVariant
10465 * of the same type.
10467 * If the action is not stateful then this function will return %NULL.
10468 * In that case, g_action_group_get_action_state() will return %NULL
10469 * and you must not call g_action_group_change_action_state().
10471 * The state type of a particular action will never change but it is
10472 * possible for an action to be removed and for a new action to be added
10473 * with the same name but a different state type.
10475 * Returns: (nullable) (transfer full): the state type, if the action
10482 * g_action_group_has_action:
10483 * @action_group: a #GActionGroup
10484 * @action_name: the name of the action to check for
10486 * Checks if the named action exists within @action_group.
10488 * Returns: whether the named action exists
10494 * g_action_group_list_actions:
10495 * @action_group: a #GActionGroup
10497 * Lists the actions contained within @action_group.
10499 * The caller is responsible for freeing the list with g_strfreev() when
10500 * it is no longer required.
10502 * Returns: (transfer full): a %NULL-terminated array of the names of the
10503 * actions in the groupb
10509 * g_action_group_query_action:
10510 * @action_group: a #GActionGroup
10511 * @action_name: the name of an action in the group
10512 * @enabled: (out): if the action is presently enabled
10513 * @parameter_type: (out) (allow-none): the parameter type, or %NULL if none needed
10514 * @state_type: (out) (allow-none): the state type, or %NULL if stateless
10515 * @state_hint: (out) (allow-none): the state hint, or %NULL if none
10516 * @state: (out) (allow-none): the current state, or %NULL if stateless
10518 * Queries all aspects of the named action within an @action_group.
10520 * This function acquires the information available from
10521 * g_action_group_has_action(), g_action_group_get_action_enabled(),
10522 * g_action_group_get_action_parameter_type(),
10523 * g_action_group_get_action_state_type(),
10524 * g_action_group_get_action_state_hint() and
10525 * g_action_group_get_action_state() with a single function call.
10527 * This provides two main benefits.
10529 * The first is the improvement in efficiency that comes with not having
10530 * to perform repeated lookups of the action in order to discover
10531 * different things about it. The second is that implementing
10532 * #GActionGroup can now be done by only overriding this one virtual
10535 * The interface provides a default implementation of this function that
10536 * calls the individual functions, as required, to fetch the
10537 * information. The interface also provides default implementations of
10538 * those functions that call this function. All implementations,
10539 * therefore, must override either this function or all of the others.
10541 * If the action exists, %TRUE is returned and any of the requested
10542 * fields (as indicated by having a non-%NULL reference passed in) are
10543 * filled. If the action doesn't exist, %FALSE is returned and the
10544 * fields may or may not have been modified.
10546 * Returns: %TRUE if the action exists, else %FALSE
10552 * g_action_map_add_action:
10553 * @action_map: a #GActionMap
10554 * @action: a #GAction
10556 * Adds an action to the @action_map.
10558 * If the action map already contains an action with the same name
10559 * as @action then the old action is dropped from the action map.
10561 * The action map takes its own reference on @action.
10568 * g_action_map_add_action_entries:
10569 * @action_map: a #GActionMap
10570 * @entries: (array length=n_entries) (element-type GActionEntry): a pointer to
10571 * the first item in an array of #GActionEntry structs
10572 * @n_entries: the length of @entries, or -1 if @entries is %NULL-terminated
10573 * @user_data: the user data for signal connections
10575 * A convenience function for creating multiple #GSimpleAction instances
10576 * and adding them to a #GActionMap.
10578 * Each action is constructed as per one #GActionEntry.
10580 * |[<!-- language="C" -->
10582 * activate_quit (GSimpleAction *simple,
10583 * GVariant *parameter,
10584 * gpointer user_data)
10590 * activate_print_string (GSimpleAction *simple,
10591 * GVariant *parameter,
10592 * gpointer user_data)
10594 * g_print ("%s\n", g_variant_get_string (parameter, NULL));
10597 * static GActionGroup *
10598 * create_action_group (void)
10600 * const GActionEntry entries[] = {
10601 * { "quit", activate_quit },
10602 * { "print-string", activate_print_string, "s" }
10604 * GSimpleActionGroup *group;
10606 * group = g_simple_action_group_new ();
10607 * g_action_map_add_action_entries (G_ACTION_MAP (group), entries, G_N_ELEMENTS (entries), NULL);
10609 * return G_ACTION_GROUP (group);
10618 * g_action_map_lookup_action:
10619 * @action_map: a #GActionMap
10620 * @action_name: the name of an action
10622 * Looks up the action with the name @action_name in @action_map.
10624 * If no such action exists, returns %NULL.
10626 * Returns: (transfer none): a #GAction, or %NULL
10632 * g_action_map_remove_action:
10633 * @action_map: a #GActionMap
10634 * @action_name: the name of the action
10636 * Removes the named action from the action map.
10638 * If no action of this name is in the map then nothing happens.
10645 * g_action_name_is_valid:
10646 * @action_name: an potential action name
10648 * Checks if @action_name is valid.
10650 * @action_name is valid if it consists only of alphanumeric characters,
10651 * plus '-' and '.'. The empty string is not a valid action name.
10653 * It is an error to call this function with a non-utf8 @action_name.
10654 * @action_name must not be %NULL.
10656 * Returns: %TRUE if @action_name is valid
10662 * g_action_parse_detailed_name:
10663 * @detailed_name: a detailed action name
10664 * @action_name: (out): the action name
10665 * @target_value: (out): the target value, or %NULL for no target
10666 * @error: a pointer to a %NULL #GError, or %NULL
10668 * Parses a detailed action name into its separate name and target
10671 * Detailed action names can have three formats.
10673 * The first format is used to represent an action name with no target
10674 * value and consists of just an action name containing no whitespace
10675 * nor the characters ':', '(' or ')'. For example: "app.action".
10677 * The second format is used to represent an action with a target value
10678 * that is a non-empty string consisting only of alphanumerics, plus '-'
10679 * and '.'. In that case, the action name and target value are
10680 * separated by a double colon ("::"). For example:
10681 * "app.action::target".
10683 * The third format is used to represent an action with any type of
10684 * target value, including strings. The target value follows the action
10685 * name, surrounded in parens. For example: "app.action(42)". The
10686 * target value is parsed using g_variant_parse(). If a tuple-typed
10687 * value is desired, it must be specified in the same way, resulting in
10688 * two sets of parens, for example: "app.action((1,2,3))". A string
10689 * target can be specified this way as well: "app.action('target')".
10690 * For strings, this third format must be used if * target value is
10691 * empty or contains characters other than alphanumerics, '-' and '.'.
10693 * Returns: %TRUE if successful, else %FALSE with @error set
10699 * g_action_print_detailed_name:
10700 * @action_name: a valid action name
10701 * @target_value: (allow-none): a #GVariant target value, or %NULL
10703 * Formats a detailed action name from @action_name and @target_value.
10705 * It is an error to call this function with an invalid action name.
10707 * This function is the opposite of
10708 * g_action_parse_detailed_action_name(). It will produce a string that
10709 * can be parsed back to the @action_name and @target_value by that
10712 * See that function for the types of strings that will be printed by
10715 * Returns: a detailed format string
10721 * g_app_info_add_supports_type:
10722 * @appinfo: a #GAppInfo.
10723 * @content_type: a string.
10724 * @error: a #GError.
10726 * Adds a content type to the application information to indicate the
10727 * application is capable of opening files with the given content type.
10729 * Returns: %TRUE on success, %FALSE on error.
10734 * g_app_info_can_delete:
10735 * @appinfo: a #GAppInfo
10737 * Obtains the information whether the #GAppInfo can be deleted.
10738 * See g_app_info_delete().
10740 * Returns: %TRUE if @appinfo can be deleted
10746 * g_app_info_can_remove_supports_type:
10747 * @appinfo: a #GAppInfo.
10749 * Checks if a supported content type can be removed from an application.
10751 * Returns: %TRUE if it is possible to remove supported
10752 * content types from a given @appinfo, %FALSE if not.
10757 * g_app_info_create_from_commandline:
10758 * @commandline: the commandline to use
10759 * @application_name: (allow-none): the application name, or %NULL to use @commandline
10760 * @flags: flags that can specify details of the created #GAppInfo
10761 * @error: a #GError location to store the error occurring, %NULL to ignore.
10763 * Creates a new #GAppInfo from the given information.
10765 * Note that for @commandline, the quoting rules of the Exec key of the
10766 * [freedesktop.org Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec)
10767 * are applied. For example, if the @commandline contains
10768 * percent-encoded URIs, the percent-character must be doubled in order to prevent it from
10769 * being swallowed by Exec key unquoting. See the specification for exact quoting rules.
10771 * Returns: (transfer full): new #GAppInfo for given command.
10776 * g_app_info_delete: (virtual do_delete)
10777 * @appinfo: a #GAppInfo
10779 * Tries to delete a #GAppInfo.
10781 * On some platforms, there may be a difference between user-defined
10782 * #GAppInfos which can be deleted, and system-wide ones which cannot.
10783 * See g_app_info_can_delete().
10785 * Returns: %TRUE if @appinfo has been deleted
10792 * @appinfo: a #GAppInfo.
10794 * Creates a duplicate of a #GAppInfo.
10796 * Returns: (transfer full): a duplicate of @appinfo.
10801 * g_app_info_equal:
10802 * @appinfo1: the first #GAppInfo.
10803 * @appinfo2: the second #GAppInfo.
10805 * Checks if two #GAppInfos are equal.
10807 * Returns: %TRUE if @appinfo1 is equal to @appinfo2. %FALSE otherwise.
10812 * g_app_info_get_all:
10814 * Gets a list of all of the applications currently registered
10817 * For desktop files, this includes applications that have
10818 * `NoDisplay=true` set or are excluded from display by means
10819 * of `OnlyShowIn` or `NotShowIn`. See g_app_info_should_show().
10820 * The returned list does not include applications which have
10821 * the `Hidden` key set.
10823 * Returns: (element-type GAppInfo) (transfer full): a newly allocated #GList of references to #GAppInfos.
10828 * g_app_info_get_all_for_type:
10829 * @content_type: the content type to find a #GAppInfo for
10831 * Gets a list of all #GAppInfos for a given content type,
10832 * including the recommended and fallback #GAppInfos. See
10833 * g_app_info_get_recommended_for_type() and
10834 * g_app_info_get_fallback_for_type().
10836 * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos
10837 * for given @content_type or %NULL on error.
10842 * g_app_info_get_commandline:
10843 * @appinfo: a #GAppInfo
10845 * Gets the commandline with which the application will be
10848 * Returns: a string containing the @appinfo's commandline,
10849 * or %NULL if this information is not available
10855 * g_app_info_get_default_for_type:
10856 * @content_type: the content type to find a #GAppInfo for
10857 * @must_support_uris: if %TRUE, the #GAppInfo is expected to
10860 * Gets the default #GAppInfo for a given content type.
10862 * Returns: (transfer full): #GAppInfo for given @content_type or
10868 * g_app_info_get_default_for_uri_scheme:
10869 * @uri_scheme: a string containing a URI scheme.
10871 * Gets the default application for handling URIs with
10872 * the given URI scheme. A URI scheme is the initial part
10873 * of the URI, up to but not including the ':', e.g. "http",
10876 * Returns: (transfer full): #GAppInfo for given @uri_scheme or %NULL on error.
10881 * g_app_info_get_description:
10882 * @appinfo: a #GAppInfo.
10884 * Gets a human-readable description of an installed application.
10886 * Returns: a string containing a description of the
10887 * application @appinfo, or %NULL if none.
10892 * g_app_info_get_display_name:
10893 * @appinfo: a #GAppInfo.
10895 * Gets the display name of the application. The display name is often more
10896 * descriptive to the user than the name itself.
10898 * Returns: the display name of the application for @appinfo, or the name if
10899 * no display name is available.
10905 * g_app_info_get_executable:
10906 * @appinfo: a #GAppInfo
10908 * Gets the executable's name for the installed application.
10910 * Returns: a string containing the @appinfo's application
10916 * g_app_info_get_fallback_for_type:
10917 * @content_type: the content type to find a #GAppInfo for
10919 * Gets a list of fallback #GAppInfos for a given content type, i.e.
10920 * those applications which claim to support the given content type
10921 * by MIME type subclassing and not directly.
10923 * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos
10924 * for given @content_type or %NULL on error.
10930 * g_app_info_get_icon:
10931 * @appinfo: a #GAppInfo.
10933 * Gets the icon for the application.
10935 * Returns: (transfer none): the default #GIcon for @appinfo or %NULL
10936 * if there is no default icon.
10941 * g_app_info_get_id:
10942 * @appinfo: a #GAppInfo.
10944 * Gets the ID of an application. An id is a string that
10945 * identifies the application. The exact format of the id is
10946 * platform dependent. For instance, on Unix this is the
10947 * desktop file id from the xdg menu specification.
10949 * Note that the returned ID may be %NULL, depending on how
10950 * the @appinfo has been constructed.
10952 * Returns: a string containing the application's ID.
10957 * g_app_info_get_name:
10958 * @appinfo: a #GAppInfo.
10960 * Gets the installed name of the application.
10962 * Returns: the name of the application for @appinfo.
10967 * g_app_info_get_recommended_for_type:
10968 * @content_type: the content type to find a #GAppInfo for
10970 * Gets a list of recommended #GAppInfos for a given content type, i.e.
10971 * those applications which claim to support the given content type exactly,
10972 * and not by MIME type subclassing.
10973 * Note that the first application of the list is the last used one, i.e.
10974 * the last one for which g_app_info_set_as_last_used_for_type() has been
10977 * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos
10978 * for given @content_type or %NULL on error.
10984 * g_app_info_get_supported_types:
10985 * @appinfo: a #GAppInfo that can handle files
10987 * Retrieves the list of content types that @app_info claims to support.
10988 * If this information is not provided by the environment, this function
10989 * will return %NULL.
10990 * This function does not take in consideration associations added with
10991 * g_app_info_add_supports_type(), but only those exported directly by
10994 * Returns: (transfer none) (array zero-terminated=1) (element-type utf8):
10995 * a list of content types.
11001 * g_app_info_launch:
11002 * @appinfo: a #GAppInfo
11003 * @files: (allow-none) (element-type GFile): a #GList of #GFile objects
11004 * @launch_context: (allow-none): a #GAppLaunchContext or %NULL
11005 * @error: a #GError
11007 * Launches the application. Passes @files to the launched application
11008 * as arguments, using the optional @launch_context to get information
11009 * about the details of the launcher (like what screen it is on).
11010 * On error, @error will be set accordingly.
11012 * To launch the application without arguments pass a %NULL @files list.
11014 * Note that even if the launch is successful the application launched
11015 * can fail to start if it runs into problems during startup. There is
11016 * no way to detect this.
11018 * Some URIs can be changed when passed through a GFile (for instance
11019 * unsupported URIs with strange formats like mailto:), so if you have
11020 * a textual URI you want to pass in as argument, consider using
11021 * g_app_info_launch_uris() instead.
11023 * The launched application inherits the environment of the launching
11024 * process, but it can be modified with g_app_launch_context_setenv()
11025 * and g_app_launch_context_unsetenv().
11027 * On UNIX, this function sets the `GIO_LAUNCHED_DESKTOP_FILE`
11028 * environment variable with the path of the launched desktop file and
11029 * `GIO_LAUNCHED_DESKTOP_FILE_PID` to the process id of the launched
11030 * process. This can be used to ignore `GIO_LAUNCHED_DESKTOP_FILE`,
11031 * should it be inherited by further processes. The `DISPLAY` and
11032 * `DESKTOP_STARTUP_ID` environment variables are also set, based
11033 * on information provided in @launch_context.
11035 * Returns: %TRUE on successful launch, %FALSE otherwise.
11040 * g_app_info_launch_default_for_uri:
11041 * @uri: the uri to show
11042 * @launch_context: (allow-none): an optional #GAppLaunchContext.
11043 * @error: a #GError.
11045 * Utility function that launches the default application
11046 * registered to handle the specified uri. Synchronous I/O
11047 * is done on the uri to detect the type of the file if
11050 * Returns: %TRUE on success, %FALSE on error.
11055 * g_app_info_launch_uris:
11056 * @appinfo: a #GAppInfo
11057 * @uris: (allow-none) (element-type utf8): a #GList containing URIs to launch.
11058 * @launch_context: (allow-none): a #GAppLaunchContext or %NULL
11059 * @error: a #GError
11061 * Launches the application. This passes the @uris to the launched application
11062 * as arguments, using the optional @launch_context to get information
11063 * about the details of the launcher (like what screen it is on).
11064 * On error, @error will be set accordingly.
11066 * To launch the application without arguments pass a %NULL @uris list.
11068 * Note that even if the launch is successful the application launched
11069 * can fail to start if it runs into problems during startup. There is
11070 * no way to detect this.
11072 * Returns: %TRUE on successful launch, %FALSE otherwise.
11077 * g_app_info_monitor_get:
11079 * Gets the #GAppInfoMonitor for the current thread-default main
11082 * The #GAppInfoMonitor will emit a "changed" signal in the
11083 * thread-default main context whenever the list of installed
11084 * applications (as reported by g_app_info_get_all()) may have changed.
11086 * You must only call g_object_unref() on the return value from under
11087 * the same main context as you created it.
11089 * Returns: (transfer full): a reference to a #GAppInfoMonitor
11095 * g_app_info_remove_supports_type:
11096 * @appinfo: a #GAppInfo.
11097 * @content_type: a string.
11098 * @error: a #GError.
11100 * Removes a supported type from an application, if possible.
11102 * Returns: %TRUE on success, %FALSE on error.
11107 * g_app_info_reset_type_associations:
11108 * @content_type: a content type
11110 * Removes all changes to the type associations done by
11111 * g_app_info_set_as_default_for_type(),
11112 * g_app_info_set_as_default_for_extension(),
11113 * g_app_info_add_supports_type() or
11114 * g_app_info_remove_supports_type().
11121 * g_app_info_set_as_default_for_extension:
11122 * @appinfo: a #GAppInfo.
11123 * @extension: a string containing the file extension (without the dot).
11124 * @error: a #GError.
11126 * Sets the application as the default handler for the given file extension.
11128 * Returns: %TRUE on success, %FALSE on error.
11133 * g_app_info_set_as_default_for_type:
11134 * @appinfo: a #GAppInfo.
11135 * @content_type: the content type.
11136 * @error: a #GError.
11138 * Sets the application as the default handler for a given type.
11140 * Returns: %TRUE on success, %FALSE on error.
11145 * g_app_info_set_as_last_used_for_type:
11146 * @appinfo: a #GAppInfo.
11147 * @content_type: the content type.
11148 * @error: a #GError.
11150 * Sets the application as the last used application for a given type.
11151 * This will make the application appear as first in the list returned
11152 * by g_app_info_get_recommended_for_type(), regardless of the default
11153 * application for that content type.
11155 * Returns: %TRUE on success, %FALSE on error.
11160 * g_app_info_should_show:
11161 * @appinfo: a #GAppInfo.
11163 * Checks if the application info should be shown in menus that
11164 * list available applications.
11166 * Returns: %TRUE if the @appinfo should be shown, %FALSE otherwise.
11171 * g_app_info_supports_files:
11172 * @appinfo: a #GAppInfo.
11174 * Checks if the application accepts files as arguments.
11176 * Returns: %TRUE if the @appinfo supports files.
11181 * g_app_info_supports_uris:
11182 * @appinfo: a #GAppInfo.
11184 * Checks if the application supports reading files and directories from URIs.
11186 * Returns: %TRUE if the @appinfo supports URIs.
11191 * g_app_launch_context_get_display:
11192 * @context: a #GAppLaunchContext
11193 * @info: a #GAppInfo
11194 * @files: (element-type GFile): a #GList of #GFile objects
11196 * Gets the display string for the @context. This is used to ensure new
11197 * applications are started on the same display as the launching
11198 * application, by setting the `DISPLAY` environment variable.
11200 * Returns: a display string for the display.
11205 * g_app_launch_context_get_environment:
11206 * @context: a #GAppLaunchContext
11208 * Gets the complete environment variable list to be passed to
11209 * the child process when @context is used to launch an application.
11210 * This is a %NULL-terminated array of strings, where each string has
11211 * the form `KEY=VALUE`.
11213 * Returns: (array zero-terminated=1) (transfer full): the
11214 * child's environment
11220 * g_app_launch_context_get_startup_notify_id:
11221 * @context: a #GAppLaunchContext
11222 * @info: a #GAppInfo
11223 * @files: (element-type GFile): a #GList of of #GFile objects
11225 * Initiates startup notification for the application and returns the
11226 * `DESKTOP_STARTUP_ID` for the launched operation, if supported.
11228 * Startup notification IDs are defined in the
11229 * [FreeDesktop.Org Startup Notifications standard](http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt").
11231 * Returns: a startup notification ID for the application, or %NULL if
11237 * g_app_launch_context_launch_failed:
11238 * @context: a #GAppLaunchContext.
11239 * @startup_notify_id: the startup notification id that was returned by g_app_launch_context_get_startup_notify_id().
11241 * Called when an application has failed to launch, so that it can cancel
11242 * the application startup notification started in g_app_launch_context_get_startup_notify_id().
11247 * g_app_launch_context_new:
11249 * Creates a new application launch context. This is not normally used,
11250 * instead you instantiate a subclass of this, such as #GdkAppLaunchContext.
11252 * Returns: a #GAppLaunchContext.
11257 * g_app_launch_context_setenv:
11258 * @context: a #GAppLaunchContext
11259 * @variable: the environment variable to set
11260 * @value: the value for to set the variable to.
11262 * Arranges for @variable to be set to @value in the child's
11263 * environment when @context is used to launch an application.
11270 * g_app_launch_context_unsetenv:
11271 * @context: a #GAppLaunchContext
11272 * @variable: the environment variable to remove
11274 * Arranges for @variable to be unset in the child's environment
11275 * when @context is used to launch an application.
11282 * g_application_activate:
11283 * @application: a #GApplication
11285 * Activates the application.
11287 * In essence, this results in the #GApplication::activate signal being
11288 * emitted in the primary instance.
11290 * The application must be registered before calling this function.
11297 * g_application_add_main_option:
11298 * @application: the #GApplication
11299 * @long_name: the long name of an option used to specify it in a commandline
11300 * @short_name: the short name of an option
11301 * @flags: flags from #GOptionFlags
11302 * @arg: the type of the option, as a #GOptionArg
11303 * @description: the description for the option in `--help` output
11304 * @arg_description: (nullable): the placeholder to use for the extra argument
11305 * parsed by the option in `--help` output
11307 * Add an option to be handled by @application.
11309 * Calling this function is the equivalent of calling
11310 * g_application_add_main_option_entries() with a single #GOptionEntry
11311 * that has its arg_data member set to %NULL.
11313 * The parsed arguments will be packed into a #GVariantDict which
11314 * is passed to #GApplication::handle-local-options. If
11315 * %G_APPLICATION_HANDLES_COMMAND_LINE is set, then it will also
11316 * be sent to the primary instance. See
11317 * g_application_add_main_option_entries() for more details.
11319 * See #GOptionEntry for more documentation of the arguments.
11326 * g_application_add_main_option_entries:
11327 * @application: a #GApplication
11328 * @entries: (array zero-terminated=1) (element-type GOptionEntry): a
11329 * %NULL-terminated list of #GOptionEntrys
11331 * Adds main option entries to be handled by @application.
11333 * This function is comparable to g_option_context_add_main_entries().
11335 * After the commandline arguments are parsed, the
11336 * #GApplication::handle-local-options signal will be emitted. At this
11337 * point, the application can inspect the values pointed to by @arg_data
11338 * in the given #GOptionEntrys.
11340 * Unlike #GOptionContext, #GApplication supports giving a %NULL
11341 * @arg_data for a non-callback #GOptionEntry. This results in the
11342 * argument in question being packed into a #GVariantDict which is also
11343 * passed to #GApplication::handle-local-options, where it can be
11344 * inspected and modified. If %G_APPLICATION_HANDLES_COMMAND_LINE is
11345 * set, then the resulting dictionary is sent to the primary instance,
11346 * where g_application_command_line_get_options_dict() will return it.
11347 * This "packing" is done according to the type of the argument --
11348 * booleans for normal flags, strings for strings, bytestrings for
11349 * filenames, etc. The packing only occurs if the flag is given (ie: we
11350 * do not pack a "false" #GVariant in the case that a flag is missing).
11352 * In general, it is recommended that all commandline arguments are
11353 * parsed locally. The options dictionary should then be used to
11354 * transmit the result of the parsing to the primary instance, where
11355 * g_variant_dict_lookup() can be used. For local options, it is
11356 * possible to either use @arg_data in the usual way, or to consult (and
11357 * potentially remove) the option from the options dictionary.
11359 * This function is new in GLib 2.40. Before then, the only real choice
11360 * was to send all of the commandline arguments (options and all) to the
11361 * primary instance for handling. #GApplication ignored them completely
11362 * on the local side. Calling this function "opts in" to the new
11363 * behaviour, and in particular, means that unrecognised options will be
11364 * treated as errors. Unrecognised options have never been ignored when
11365 * %G_APPLICATION_HANDLES_COMMAND_LINE is unset.
11367 * If #GApplication::handle-local-options needs to see the list of
11368 * filenames, then the use of %G_OPTION_REMAINING is recommended. If
11369 * @arg_data is %NULL then %G_OPTION_REMAINING can be used as a key into
11370 * the options dictionary. If you do use %G_OPTION_REMAINING then you
11371 * need to handle these arguments for yourself because once they are
11372 * consumed, they will no longer be visible to the default handling
11373 * (which treats them as filenames to be opened).
11380 * g_application_add_option_group:
11381 * @application: the #GApplication
11382 * @group: a #GOptionGroup
11384 * Adds a #GOptionGroup to the commandline handling of @application.
11386 * This function is comparable to g_option_context_add_group().
11388 * Unlike g_application_add_main_option_entries(), this function does
11389 * not deal with %NULL @arg_data and never transmits options to the
11390 * primary instance.
11392 * The reason for that is because, by the time the options arrive at the
11393 * primary instance, it is typically too late to do anything with them.
11394 * Taking the GTK option group as an example: GTK will already have been
11395 * initialised by the time the #GApplication::command-line handler runs.
11396 * In the case that this is not the first-running instance of the
11397 * application, the existing instance may already have been running for
11398 * a very long time.
11400 * This means that the options from #GOptionGroup are only really usable
11401 * in the case that the instance of the application being run is the
11402 * first instance. Passing options like `--display=` or `--gdk-debug=`
11403 * on future runs will have no effect on the existing primary instance.
11405 * Calling this function will cause the options in the supplied option
11406 * group to be parsed, but it does not cause you to be "opted in" to the
11407 * new functionality whereby unrecognised options are rejected even if
11408 * %G_APPLICATION_HANDLES_COMMAND_LINE was given.
11415 * g_application_command_line_create_file_for_arg:
11416 * @cmdline: a #GApplicationCommandLine
11417 * @arg: an argument from @cmdline
11419 * Creates a #GFile corresponding to a filename that was given as part
11420 * of the invocation of @cmdline.
11422 * This differs from g_file_new_for_commandline_arg() in that it
11423 * resolves relative pathnames using the current working directory of
11424 * the invoking process rather than the local process.
11426 * Returns: (transfer full): a new #GFile
11432 * g_application_command_line_get_arguments:
11433 * @cmdline: a #GApplicationCommandLine
11434 * @argc: (out) (allow-none): the length of the arguments array, or %NULL
11436 * Gets the list of arguments that was passed on the command line.
11438 * The strings in the array may contain non-UTF-8 data on UNIX (such as
11439 * filenames or arguments given in the system locale) but are always in
11440 * UTF-8 on Windows.
11442 * If you wish to use the return value with #GOptionContext, you must
11443 * use g_option_context_parse_strv().
11445 * The return value is %NULL-terminated and should be freed using
11448 * Returns: (array length=argc) (transfer full): the string array
11449 * containing the arguments (the argv)
11455 * g_application_command_line_get_cwd:
11456 * @cmdline: a #GApplicationCommandLine
11458 * Gets the working directory of the command line invocation.
11459 * The string may contain non-utf8 data.
11461 * It is possible that the remote application did not send a working
11462 * directory, so this may be %NULL.
11464 * The return value should not be modified or freed and is valid for as
11465 * long as @cmdline exists.
11467 * Returns: the current directory, or %NULL
11473 * g_application_command_line_get_environ:
11474 * @cmdline: a #GApplicationCommandLine
11476 * Gets the contents of the 'environ' variable of the command line
11477 * invocation, as would be returned by g_get_environ(), ie as a
11478 * %NULL-terminated list of strings in the form 'NAME=VALUE'.
11479 * The strings may contain non-utf8 data.
11481 * The remote application usually does not send an environment. Use
11482 * %G_APPLICATION_SEND_ENVIRONMENT to affect that. Even with this flag
11483 * set it is possible that the environment is still not available (due
11484 * to invocation messages from other applications).
11486 * The return value should not be modified or freed and is valid for as
11487 * long as @cmdline exists.
11489 * See g_application_command_line_getenv() if you are only interested
11490 * in the value of a single environment variable.
11492 * Returns: (array zero-terminated=1) (transfer none): the environment
11493 * strings, or %NULL if they were not sent
11499 * g_application_command_line_get_exit_status:
11500 * @cmdline: a #GApplicationCommandLine
11502 * Gets the exit status of @cmdline. See
11503 * g_application_command_line_set_exit_status() for more information.
11505 * Returns: the exit status
11511 * g_application_command_line_get_is_remote:
11512 * @cmdline: a #GApplicationCommandLine
11514 * Determines if @cmdline represents a remote invocation.
11516 * Returns: %TRUE if the invocation was remote
11522 * g_application_command_line_get_options_dict:
11523 * @cmdline: a #GApplicationCommandLine
11525 * Gets the options there were passed to g_application_command_line().
11527 * If you did not override local_command_line() then these are the same
11528 * options that were parsed according to the #GOptionEntrys added to the
11529 * application with g_application_add_main_option_entries() and possibly
11530 * modified from your GApplication::handle-local-options handler.
11532 * If no options were sent then an empty dictionary is returned so that
11533 * you don't need to check for %NULL.
11535 * Returns: (transfer none): a #GVariantDict with the options
11541 * g_application_command_line_get_platform_data:
11542 * @cmdline: #GApplicationCommandLine
11544 * Gets the platform data associated with the invocation of @cmdline.
11546 * This is a #GVariant dictionary containing information about the
11547 * context in which the invocation occurred. It typically contains
11548 * information like the current working directory and the startup
11551 * For local invocation, it will be %NULL.
11553 * Returns: (nullable): the platform data, or %NULL
11559 * g_application_command_line_get_stdin:
11560 * @cmdline: a #GApplicationCommandLine
11562 * Gets the stdin of the invoking process.
11564 * The #GInputStream can be used to read data passed to the standard
11565 * input of the invoking process.
11566 * This doesn't work on all platforms. Presently, it is only available
11567 * on UNIX when using a DBus daemon capable of passing file descriptors.
11568 * If stdin is not available then %NULL will be returned. In the
11569 * future, support may be expanded to other platforms.
11571 * You must only call this function once per commandline invocation.
11573 * Returns: (transfer full): a #GInputStream for stdin
11579 * g_application_command_line_getenv:
11580 * @cmdline: a #GApplicationCommandLine
11581 * @name: the environment variable to get
11583 * Gets the value of a particular environment variable of the command
11584 * line invocation, as would be returned by g_getenv(). The strings may
11585 * contain non-utf8 data.
11587 * The remote application usually does not send an environment. Use
11588 * %G_APPLICATION_SEND_ENVIRONMENT to affect that. Even with this flag
11589 * set it is possible that the environment is still not available (due
11590 * to invocation messages from other applications).
11592 * The return value should not be modified or freed and is valid for as
11593 * long as @cmdline exists.
11595 * Returns: the value of the variable, or %NULL if unset or unsent
11601 * g_application_command_line_print:
11602 * @cmdline: a #GApplicationCommandLine
11603 * @format: a printf-style format string
11604 * @...: arguments, as per @format
11606 * Formats a message and prints it using the stdout print handler in the
11607 * invoking process.
11609 * If @cmdline is a local invocation then this is exactly equivalent to
11610 * g_print(). If @cmdline is remote then this is equivalent to calling
11611 * g_print() in the invoking process.
11618 * g_application_command_line_printerr:
11619 * @cmdline: a #GApplicationCommandLine
11620 * @format: a printf-style format string
11621 * @...: arguments, as per @format
11623 * Formats a message and prints it using the stderr print handler in the
11624 * invoking process.
11626 * If @cmdline is a local invocation then this is exactly equivalent to
11627 * g_printerr(). If @cmdline is remote then this is equivalent to
11628 * calling g_printerr() in the invoking process.
11635 * g_application_command_line_set_exit_status:
11636 * @cmdline: a #GApplicationCommandLine
11637 * @exit_status: the exit status
11639 * Sets the exit status that will be used when the invoking process
11642 * The return value of the #GApplication::command-line signal is
11643 * passed to this function when the handler returns. This is the usual
11644 * way of setting the exit status.
11646 * In the event that you want the remote invocation to continue running
11647 * and want to decide on the exit status in the future, you can use this
11648 * call. For the case of a remote invocation, the remote process will
11649 * typically exit when the last reference is dropped on @cmdline. The
11650 * exit status of the remote process will be equal to the last value
11651 * that was set with this function.
11653 * In the case that the commandline invocation is local, the situation
11654 * is slightly more complicated. If the commandline invocation results
11655 * in the mainloop running (ie: because the use-count of the application
11656 * increased to a non-zero value) then the application is considered to
11657 * have been 'successful' in a certain sense, and the exit status is
11658 * always zero. If the application use count is zero, though, the exit
11659 * status of the local #GApplicationCommandLine is used.
11666 * g_application_get_application_id:
11667 * @application: a #GApplication
11669 * Gets the unique identifier for @application.
11671 * Returns: the identifier for @application, owned by @application
11677 * g_application_get_dbus_connection:
11678 * @application: a #GApplication
11680 * Gets the #GDBusConnection being used by the application, or %NULL.
11682 * If #GApplication is using its D-Bus backend then this function will
11683 * return the #GDBusConnection being used for uniqueness and
11684 * communication with the desktop environment and other instances of the
11687 * If #GApplication is not using D-Bus then this function will return
11688 * %NULL. This includes the situation where the D-Bus backend would
11689 * normally be in use but we were unable to connect to the bus.
11691 * This function must not be called before the application has been
11692 * registered. See g_application_get_is_registered().
11694 * Returns: (transfer none): a #GDBusConnection, or %NULL
11700 * g_application_get_dbus_object_path:
11701 * @application: a #GApplication
11703 * Gets the D-Bus object path being used by the application, or %NULL.
11705 * If #GApplication is using its D-Bus backend then this function will
11706 * return the D-Bus object path that #GApplication is using. If the
11707 * application is the primary instance then there is an object published
11708 * at this path. If the application is not the primary instance then
11709 * the result of this function is undefined.
11711 * If #GApplication is not using D-Bus then this function will return
11712 * %NULL. This includes the situation where the D-Bus backend would
11713 * normally be in use but we were unable to connect to the bus.
11715 * This function must not be called before the application has been
11716 * registered. See g_application_get_is_registered().
11718 * Returns: the object path, or %NULL
11724 * g_application_get_default:
11726 * Returns the default #GApplication instance for this process.
11728 * Normally there is only one #GApplication per process and it becomes
11729 * the default when it is created. You can exercise more control over
11730 * this by using g_application_set_default().
11732 * If there is no default application then %NULL is returned.
11734 * Returns: (transfer none): the default application for this process, or %NULL
11740 * g_application_get_flags:
11741 * @application: a #GApplication
11743 * Gets the flags for @application.
11745 * See #GApplicationFlags.
11747 * Returns: the flags for @application
11753 * g_application_get_inactivity_timeout:
11754 * @application: a #GApplication
11756 * Gets the current inactivity timeout for the application.
11758 * This is the amount of time (in milliseconds) after the last call to
11759 * g_application_release() before the application stops running.
11761 * Returns: the timeout, in milliseconds
11767 * g_application_get_is_registered:
11768 * @application: a #GApplication
11770 * Checks if @application is registered.
11772 * An application is registered if g_application_register() has been
11773 * successfully called.
11775 * Returns: %TRUE if @application is registered
11781 * g_application_get_is_remote:
11782 * @application: a #GApplication
11784 * Checks if @application is remote.
11786 * If @application is remote then it means that another instance of
11787 * application already exists (the 'primary' instance). Calls to
11788 * perform actions on @application will result in the actions being
11789 * performed by the primary instance.
11791 * The value of this property cannot be accessed before
11792 * g_application_register() has been called. See
11793 * g_application_get_is_registered().
11795 * Returns: %TRUE if @application is remote
11801 * g_application_get_resource_base_path:
11802 * @application: a #GApplication
11804 * Gets the resource base path of @application.
11806 * See g_application_set_resource_base_path() for more information.
11808 * Returns: (nullable): the base resource path, if one is set
11814 * g_application_hold:
11815 * @application: a #GApplication
11817 * Increases the use count of @application.
11819 * Use this function to indicate that the application has a reason to
11820 * continue to run. For example, g_application_hold() is called by GTK+
11821 * when a toplevel window is on the screen.
11823 * To cancel the hold, call g_application_release().
11828 * g_application_id_is_valid:
11829 * @application_id: a potential application identifier
11831 * Checks if @application_id is a valid application identifier.
11833 * A valid ID is required for calls to g_application_new() and
11834 * g_application_set_application_id().
11836 * For convenience, the restrictions on application identifiers are
11839 * - Application identifiers must contain only the ASCII characters
11840 * "[A-Z][a-z][0-9]_-." and must not begin with a digit.
11842 * - Application identifiers must contain at least one '.' (period)
11843 * character (and thus at least three elements).
11845 * - Application identifiers must not begin or end with a '.' (period)
11848 * - Application identifiers must not contain consecutive '.' (period)
11851 * - Application identifiers must not exceed 255 characters.
11853 * Returns: %TRUE if @application_id is valid
11858 * g_application_mark_busy:
11859 * @application: a #GApplication
11861 * Increases the busy count of @application.
11863 * Use this function to indicate that the application is busy, for instance
11864 * while a long running operation is pending.
11866 * The busy state will be exposed to other processes, so a session shell will
11867 * use that information to indicate the state to the user (e.g. with a
11870 * To cancel the busy indication, use g_application_unmark_busy().
11877 * g_application_new:
11878 * @application_id: (allow-none): the application id
11879 * @flags: the application flags
11881 * Creates a new #GApplication instance.
11883 * If non-%NULL, the application id must be valid. See
11884 * g_application_id_is_valid().
11886 * If no application ID is given then some features of #GApplication
11887 * (most notably application uniqueness) will be disabled.
11889 * Returns: a new #GApplication instance
11894 * g_application_open:
11895 * @application: a #GApplication
11896 * @files: (array length=n_files): an array of #GFiles to open
11897 * @n_files: the length of the @files array
11898 * @hint: a hint (or ""), but never %NULL
11900 * Opens the given files.
11902 * In essence, this results in the #GApplication::open signal being emitted
11903 * in the primary instance.
11905 * @n_files must be greater than zero.
11907 * @hint is simply passed through to the ::open signal. It is
11908 * intended to be used by applications that have multiple modes for
11909 * opening files (eg: "view" vs "edit", etc). Unless you have a need
11910 * for this functionality, you should use "".
11912 * The application must be registered before calling this function
11913 * and it must have the %G_APPLICATION_HANDLES_OPEN flag set.
11920 * g_application_quit:
11921 * @application: a #GApplication
11923 * Immediately quits the application.
11925 * Upon return to the mainloop, g_application_run() will return,
11926 * calling only the 'shutdown' function before doing so.
11928 * The hold count is ignored.
11930 * The result of calling g_application_run() again after it returns is
11938 * g_application_register:
11939 * @application: a #GApplication
11940 * @cancellable: (allow-none): a #GCancellable, or %NULL
11941 * @error: a pointer to a NULL #GError, or %NULL
11943 * Attempts registration of the application.
11945 * This is the point at which the application discovers if it is the
11946 * primary instance or merely acting as a remote for an already-existing
11947 * primary instance. This is implemented by attempting to acquire the
11948 * application identifier as a unique bus name on the session bus using
11951 * If there is no application ID or if %G_APPLICATION_NON_UNIQUE was
11952 * given, then this process will always become the primary instance.
11954 * Due to the internal architecture of GDBus, method calls can be
11955 * dispatched at any time (even if a main loop is not running). For
11956 * this reason, you must ensure that any object paths that you wish to
11957 * register are registered before calling this function.
11959 * If the application has already been registered then %TRUE is
11960 * returned with no work performed.
11962 * The #GApplication::startup signal is emitted if registration succeeds
11963 * and @application is the primary instance (including the non-unique
11966 * In the event of an error (such as @cancellable being cancelled, or a
11967 * failure to connect to the session bus), %FALSE is returned and @error
11968 * is set appropriately.
11970 * Note: the return value of this function is not an indicator that this
11971 * instance is or is not the primary instance of the application. See
11972 * g_application_get_is_remote() for that.
11974 * Returns: %TRUE if registration succeeded
11980 * g_application_release:
11981 * @application: a #GApplication
11983 * Decrease the use count of @application.
11985 * When the use count reaches zero, the application will stop running.
11987 * Never call this function except to cancel the effect of a previous
11988 * call to g_application_hold().
11993 * g_application_run:
11994 * @application: a #GApplication
11995 * @argc: the argc from main() (or 0 if @argv is %NULL)
11996 * @argv: (array length=argc) (allow-none): the argv from main(), or %NULL
11998 * Runs the application.
12000 * This function is intended to be run from main() and its return value
12001 * is intended to be returned by main(). Although you are expected to pass
12002 * the @argc, @argv parameters from main() to this function, it is possible
12003 * to pass %NULL if @argv is not available or commandline handling is not
12004 * required. Note that on Windows, @argc and @argv are ignored, and
12005 * g_win32_get_command_line() is called internally (for proper support
12006 * of Unicode commandline arguments).
12008 * #GApplication will attempt to parse the commandline arguments. You
12009 * can add commandline flags to the list of recognised options by way of
12010 * g_application_add_main_option_entries(). After this, the
12011 * #GApplication::handle-local-options signal is emitted, from which the
12012 * application can inspect the values of its #GOptionEntrys.
12014 * #GApplication::handle-local-options is a good place to handle options
12015 * such as `--version`, where an immediate reply from the local process is
12016 * desired (instead of communicating with an already-running instance).
12017 * A #GApplication::handle-local-options handler can stop further processing
12018 * by returning a non-negative value, which then becomes the exit status of
12021 * What happens next depends on the flags: if
12022 * %G_APPLICATION_HANDLES_COMMAND_LINE was specified then the remaining
12023 * commandline arguments are sent to the primary instance, where a
12024 * #GApplication::command-line signal is emitted. Otherwise, the
12025 * remaining commandline arguments are assumed to be a list of files.
12026 * If there are no files listed, the application is activated via the
12027 * #GApplication::activate signal. If there are one or more files, and
12028 * %G_APPLICATION_HANDLES_OPEN was specified then the files are opened
12029 * via the #GApplication::open signal.
12031 * If you are interested in doing more complicated local handling of the
12032 * commandline then you should implement your own #GApplication subclass
12033 * and override local_command_line(). In this case, you most likely want
12034 * to return %TRUE from your local_command_line() implementation to
12035 * suppress the default handling. See
12036 * [gapplication-example-cmdline2.c][gapplication-example-cmdline2]
12039 * If, after the above is done, the use count of the application is zero
12040 * then the exit status is returned immediately. If the use count is
12041 * non-zero then the default main context is iterated until the use count
12042 * falls to zero, at which point 0 is returned.
12044 * If the %G_APPLICATION_IS_SERVICE flag is set, then the service will
12045 * run for as much as 10 seconds with a use count of zero while waiting
12046 * for the message that caused the activation to arrive. After that,
12047 * if the use count falls to zero the application will exit immediately,
12048 * except in the case that g_application_set_inactivity_timeout() is in
12051 * This function sets the prgname (g_set_prgname()), if not already set,
12052 * to the basename of argv[0]. Since 2.38, if %G_APPLICATION_IS_SERVICE
12053 * is specified, the prgname is set to the application ID. The main
12054 * impact of this is is that the wmclass of windows created by Gtk+ will
12055 * be set accordingly, which helps the window manager determine which
12056 * application is showing the window.
12058 * Since 2.40, applications that are not explicitly flagged as services
12059 * or launchers (ie: neither %G_APPLICATION_IS_SERVICE or
12060 * %G_APPLICATION_IS_LAUNCHER are given as flags) will check (from the
12061 * default handler for local_command_line) if "--gapplication-service"
12062 * was given in the command line. If this flag is present then normal
12063 * commandline processing is interrupted and the
12064 * %G_APPLICATION_IS_SERVICE flag is set. This provides a "compromise"
12065 * solution whereby running an application directly from the commandline
12066 * will invoke it in the normal way (which can be useful for debugging)
12067 * while still allowing applications to be D-Bus activated in service
12068 * mode. The D-Bus service file should invoke the executable with
12069 * "--gapplication-service" as the sole commandline argument. This
12070 * approach is suitable for use by most graphical applications but
12071 * should not be used from applications like editors that need precise
12072 * control over when processes invoked via the commandline will exit and
12073 * what their exit status will be.
12075 * Returns: the exit status
12081 * g_application_send_notification:
12082 * @application: a #GApplication
12083 * @id: (allow-none): id of the notification, or %NULL
12084 * @notification: the #GNotification to send
12086 * Sends a notification on behalf of @application to the desktop shell.
12087 * There is no guarantee that the notification is displayed immediately,
12090 * Notifications may persist after the application exits. It will be
12091 * D-Bus-activated when the notification or one of its actions is
12094 * Modifying @notification after this call has no effect. However, the
12095 * object can be reused for a later call to this function.
12097 * @id may be any string that uniquely identifies the event for the
12098 * application. It does not need to be in any special format. For
12099 * example, "new-message" might be appropriate for a notification about
12102 * If a previous notification was sent with the same @id, it will be
12103 * replaced with @notification and shown again as if it was a new
12104 * notification. This works even for notifications sent from a previous
12105 * execution of the application, as long as @id is the same string.
12107 * @id may be %NULL, but it is impossible to replace or withdraw
12108 * notifications without an id.
12110 * If @notification is no longer relevant, it can be withdrawn with
12111 * g_application_withdraw_notification().
12118 * g_application_set_action_group:
12119 * @application: a #GApplication
12120 * @action_group: (allow-none): a #GActionGroup, or %NULL
12122 * This used to be how actions were associated with a #GApplication.
12123 * Now there is #GActionMap for that.
12126 * Deprecated: 2.32: Use the #GActionMap interface instead. Never ever
12127 * mix use of this API with use of #GActionMap on the same @application
12128 * or things will go very badly wrong. This function is known to
12129 * introduce buggy behaviour (ie: signals not emitted on changes to the
12130 * action group), so you should really use #GActionMap instead.
12135 * g_application_set_application_id:
12136 * @application: a #GApplication
12137 * @application_id: (allow-none): the identifier for @application
12139 * Sets the unique identifier for @application.
12141 * The application id can only be modified if @application has not yet
12144 * If non-%NULL, the application id must be valid. See
12145 * g_application_id_is_valid().
12152 * g_application_set_default:
12153 * @application: (allow-none): the application to set as default, or %NULL
12155 * Sets or unsets the default application for the process, as returned
12156 * by g_application_get_default().
12158 * This function does not take its own reference on @application. If
12159 * @application is destroyed then the default application will revert
12167 * g_application_set_flags:
12168 * @application: a #GApplication
12169 * @flags: the flags for @application
12171 * Sets the flags for @application.
12173 * The flags can only be modified if @application has not yet been
12176 * See #GApplicationFlags.
12183 * g_application_set_inactivity_timeout:
12184 * @application: a #GApplication
12185 * @inactivity_timeout: the timeout, in milliseconds
12187 * Sets the current inactivity timeout for the application.
12189 * This is the amount of time (in milliseconds) after the last call to
12190 * g_application_release() before the application stops running.
12192 * This call has no side effects of its own. The value set here is only
12193 * used for next time g_application_release() drops the use count to
12194 * zero. Any timeouts currently in progress are not impacted.
12201 * g_application_set_resource_base_path:
12202 * @application: a #GApplication
12203 * @resource_path: (nullable): the resource path to use
12205 * Sets (or unsets) the base resource path of @application.
12207 * The path is used to automatically load various [application
12208 * resources][gresource] such as menu layouts and action descriptions.
12209 * The various types of resources will be found at fixed names relative
12210 * to the given base path.
12212 * By default, the resource base path is determined from the application
12213 * ID by prefixing '/' and replacing each '.' with '/'. This is done at
12214 * the time that the #GApplication object is constructed. Changes to
12215 * the application ID after that point will not have an impact on the
12216 * resource base path.
12218 * As an example, if the application has an ID of "org.example.app" then
12219 * the default resource base path will be "/org/example/app". If this
12220 * is a #GtkApplication (and you have not manually changed the path)
12221 * then Gtk will then search for the menus of the application at
12222 * "/org/example/app/gtk/menus.ui".
12224 * See #GResource for more information about adding resources to your
12227 * You can disable automatic resource loading functionality by setting
12228 * the path to %NULL.
12230 * Changing the resource base path once the application is running is
12231 * not recommended. The point at which the resource path is consulted
12232 * for forming paths for various purposes is unspecified.
12239 * g_application_unmark_busy:
12240 * @application: a #GApplication
12242 * Decreases the busy count of @application.
12244 * When the busy count reaches zero, the new state will be propagated
12245 * to other processes.
12247 * This function must only be called to cancel the effect of a previous
12248 * call to g_application_mark_busy().
12255 * g_application_withdraw_notification:
12256 * @application: a #GApplication
12257 * @id: id of a previously sent notification
12259 * Withdraws a notification that was sent with
12260 * g_application_send_notification().
12262 * This call does nothing if a notification with @id doesn't exist or
12263 * the notification was never sent.
12265 * This function works even for notifications sent in previous
12266 * executions of this application, as long @id is the same as it was for
12267 * the sent notification.
12269 * Note that notifications are dismissed when the user clicks on one
12270 * of the buttons in a notification or triggers its default action, so
12271 * there is no need to explicitly withdraw the notification in that case.
12278 * g_async_initable_init_async:
12279 * @initable: a #GAsyncInitable.
12280 * @io_priority: the [I/O priority][io-priority] of the operation
12281 * @cancellable: optional #GCancellable object, %NULL to ignore.
12282 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
12283 * @user_data: the data to pass to callback function
12285 * Starts asynchronous initialization of the object implementing the
12286 * interface. This must be done before any real use of the object after
12287 * initial construction. If the object also implements #GInitable you can
12288 * optionally call g_initable_init() instead.
12290 * When the initialization is finished, @callback will be called. You can
12291 * then call g_async_initable_init_finish() to get the result of the
12294 * Implementations may also support cancellation. If @cancellable is not
12295 * %NULL, then initialization can be cancelled by triggering the cancellable
12296 * object from another thread. If the operation was cancelled, the error
12297 * %G_IO_ERROR_CANCELLED will be returned. If @cancellable is not %NULL, and
12298 * the object doesn't support cancellable initialization, the error
12299 * %G_IO_ERROR_NOT_SUPPORTED will be returned.
12301 * As with #GInitable, if the object is not initialized, or initialization
12302 * returns with an error, then all operations on the object except
12303 * g_object_ref() and g_object_unref() are considered to be invalid, and
12304 * have undefined behaviour. They will often fail with g_critical() or
12305 * g_warning(), but this must not be relied on.
12307 * Implementations of this method must be idempotent: i.e. multiple calls
12308 * to this function with the same argument should return the same results.
12309 * Only the first call initializes the object; further calls return the result
12310 * of the first call. This is so that it's safe to implement the singleton
12311 * pattern in the GObject constructor function.
12313 * For classes that also support the #GInitable interface, the default
12314 * implementation of this method will run the g_initable_init() function
12315 * in a thread, so if you want to support asynchronous initialization via
12316 * threads, just implement the #GAsyncInitable interface without overriding
12317 * any interface methods.
12324 * g_async_initable_init_finish:
12325 * @initable: a #GAsyncInitable.
12326 * @res: a #GAsyncResult.
12327 * @error: a #GError location to store the error occurring, or %NULL to
12330 * Finishes asynchronous initialization and returns the result.
12331 * See g_async_initable_init_async().
12333 * Returns: %TRUE if successful. If an error has occurred, this function
12334 * will return %FALSE and set @error appropriately if present.
12340 * g_async_initable_new_async:
12341 * @object_type: a #GType supporting #GAsyncInitable.
12342 * @io_priority: the [I/O priority][io-priority] of the operation
12343 * @cancellable: optional #GCancellable object, %NULL to ignore.
12344 * @callback: a #GAsyncReadyCallback to call when the initialization is
12346 * @user_data: the data to pass to callback function
12347 * @first_property_name: (allow-none): the name of the first property, or %NULL if no
12349 * @...: the value of the first property, followed by other property
12350 * value pairs, and ended by %NULL.
12352 * Helper function for constructing #GAsyncInitable object. This is
12353 * similar to g_object_new() but also initializes the object asynchronously.
12355 * When the initialization is finished, @callback will be called. You can
12356 * then call g_async_initable_new_finish() to get the new object and check
12364 * g_async_initable_new_finish:
12365 * @initable: the #GAsyncInitable from the callback
12366 * @res: the #GAsyncResult from the callback
12367 * @error: return location for errors, or %NULL to ignore
12369 * Finishes the async construction for the various g_async_initable_new
12370 * calls, returning the created object or %NULL on error.
12372 * Returns: (type GObject.Object) (transfer full): a newly created #GObject,
12373 * or %NULL on error. Free with g_object_unref().
12379 * g_async_initable_new_valist_async:
12380 * @object_type: a #GType supporting #GAsyncInitable.
12381 * @first_property_name: the name of the first property, followed by
12382 * the value, and other property value pairs, and ended by %NULL.
12383 * @var_args: The var args list generated from @first_property_name.
12384 * @io_priority: the [I/O priority][io-priority] of the operation
12385 * @cancellable: optional #GCancellable object, %NULL to ignore.
12386 * @callback: a #GAsyncReadyCallback to call when the initialization is
12388 * @user_data: the data to pass to callback function
12390 * Helper function for constructing #GAsyncInitable object. This is
12391 * similar to g_object_new_valist() but also initializes the object
12394 * When the initialization is finished, @callback will be called. You can
12395 * then call g_async_initable_new_finish() to get the new object and check
12403 * g_async_initable_newv_async:
12404 * @object_type: a #GType supporting #GAsyncInitable.
12405 * @n_parameters: the number of parameters in @parameters
12406 * @parameters: the parameters to use to construct the object
12407 * @io_priority: the [I/O priority][io-priority] of the operation
12408 * @cancellable: optional #GCancellable object, %NULL to ignore.
12409 * @callback: a #GAsyncReadyCallback to call when the initialization is
12411 * @user_data: the data to pass to callback function
12413 * Helper function for constructing #GAsyncInitable object. This is
12414 * similar to g_object_newv() but also initializes the object asynchronously.
12416 * When the initialization is finished, @callback will be called. You can
12417 * then call g_async_initable_new_finish() to get the new object and check
12425 * g_async_result_get_source_object:
12426 * @res: a #GAsyncResult
12428 * Gets the source object from a #GAsyncResult.
12430 * Returns: (transfer full): a new reference to the source object for the @res,
12431 * or %NULL if there is none.
12436 * g_async_result_get_user_data:
12437 * @res: a #GAsyncResult.
12439 * Gets the user data from a #GAsyncResult.
12441 * Returns: (transfer full): the user data for @res.
12446 * g_async_result_is_tagged:
12447 * @res: a #GAsyncResult
12448 * @source_tag: an application-defined tag
12450 * Checks if @res has the given @source_tag (generally a function
12451 * pointer indicating the function @res was created by).
12453 * Returns: %TRUE if @res has the indicated @source_tag, %FALSE if
12460 * g_async_result_legacy_propagate_error:
12461 * @res: a #GAsyncResult
12462 * @error: (out): a location to propagate the error to.
12464 * If @res is a #GSimpleAsyncResult, this is equivalent to
12465 * g_simple_async_result_propagate_error(). Otherwise it returns
12468 * This can be used for legacy error handling in async *_finish()
12469 * wrapper functions that traditionally handled #GSimpleAsyncResult
12470 * error returns themselves rather than calling into the virtual method.
12471 * This should not be used in new code; #GAsyncResult errors that are
12472 * set by virtual methods should also be extracted by virtual methods,
12473 * to enable subclasses to chain up correctly.
12475 * Returns: %TRUE if @error is has been filled in with an error from
12476 * @res, %FALSE if not.
12482 * g_buffered_input_stream_fill:
12483 * @stream: a #GBufferedInputStream
12484 * @count: the number of bytes that will be read from the stream
12485 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
12486 * @error: location to store the error occurring, or %NULL to ignore
12488 * Tries to read @count bytes from the stream into the buffer.
12489 * Will block during this read.
12491 * If @count is zero, returns zero and does nothing. A value of @count
12492 * larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
12494 * On success, the number of bytes read into the buffer is returned.
12495 * It is not an error if this is not the same as the requested size, as it
12496 * can happen e.g. near the end of a file. Zero is returned on end of file
12497 * (or if @count is zero), but never otherwise.
12499 * If @count is -1 then the attempted read size is equal to the number of
12500 * bytes that are required to fill the buffer.
12502 * If @cancellable is not %NULL, then the operation can be cancelled by
12503 * triggering the cancellable object from another thread. If the operation
12504 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
12505 * operation was partially finished when the operation was cancelled the
12506 * partial result will be returned, without an error.
12508 * On error -1 is returned and @error is set accordingly.
12510 * For the asynchronous, non-blocking, version of this function, see
12511 * g_buffered_input_stream_fill_async().
12513 * Returns: the number of bytes read into @stream's buffer, up to @count,
12519 * g_buffered_input_stream_fill_async:
12520 * @stream: a #GBufferedInputStream
12521 * @count: the number of bytes that will be read from the stream
12522 * @io_priority: the [I/O priority][io-priority] of the request
12523 * @cancellable: (allow-none): optional #GCancellable object
12524 * @callback: (scope async): a #GAsyncReadyCallback
12525 * @user_data: (closure): a #gpointer
12527 * Reads data into @stream's buffer asynchronously, up to @count size.
12528 * @io_priority can be used to prioritize reads. For the synchronous
12529 * version of this function, see g_buffered_input_stream_fill().
12531 * If @count is -1 then the attempted read size is equal to the number
12532 * of bytes that are required to fill the buffer.
12537 * g_buffered_input_stream_fill_finish:
12538 * @stream: a #GBufferedInputStream
12539 * @result: a #GAsyncResult
12540 * @error: a #GError
12542 * Finishes an asynchronous read.
12544 * Returns: a #gssize of the read stream, or %-1 on an error.
12549 * g_buffered_input_stream_get_available:
12550 * @stream: #GBufferedInputStream
12552 * Gets the size of the available data within the stream.
12554 * Returns: size of the available stream.
12559 * g_buffered_input_stream_get_buffer_size:
12560 * @stream: a #GBufferedInputStream
12562 * Gets the size of the input buffer.
12564 * Returns: the current buffer size.
12569 * g_buffered_input_stream_new:
12570 * @base_stream: a #GInputStream
12572 * Creates a new #GInputStream from the given @base_stream, with
12573 * a buffer set to the default size (4 kilobytes).
12575 * Returns: a #GInputStream for the given @base_stream.
12580 * g_buffered_input_stream_new_sized:
12581 * @base_stream: a #GInputStream
12584 * Creates a new #GBufferedInputStream from the given @base_stream,
12585 * with a buffer set to @size.
12587 * Returns: a #GInputStream.
12592 * g_buffered_input_stream_peek:
12593 * @stream: a #GBufferedInputStream
12594 * @buffer: (array length=count) (element-type guint8): a pointer to
12595 * an allocated chunk of memory
12596 * @offset: a #gsize
12599 * Peeks in the buffer, copying data of size @count into @buffer,
12600 * offset @offset bytes.
12602 * Returns: a #gsize of the number of bytes peeked, or -1 on error.
12607 * g_buffered_input_stream_peek_buffer:
12608 * @stream: a #GBufferedInputStream
12609 * @count: (out): a #gsize to get the number of bytes available in the buffer
12611 * Returns the buffer with the currently available bytes. The returned
12612 * buffer must not be modified and will become invalid when reading from
12613 * the stream or filling the buffer.
12615 * Returns: (array length=count) (element-type guint8) (transfer none):
12621 * g_buffered_input_stream_read_byte:
12622 * @stream: a #GBufferedInputStream
12623 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
12624 * @error: location to store the error occurring, or %NULL to ignore
12626 * Tries to read a single byte from the stream or the buffer. Will block
12627 * during this read.
12629 * On success, the byte read from the stream is returned. On end of stream
12630 * -1 is returned but it's not an exceptional error and @error is not set.
12632 * If @cancellable is not %NULL, then the operation can be cancelled by
12633 * triggering the cancellable object from another thread. If the operation
12634 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
12635 * operation was partially finished when the operation was cancelled the
12636 * partial result will be returned, without an error.
12638 * On error -1 is returned and @error is set accordingly.
12640 * Returns: the byte read from the @stream, or -1 on end of stream or error.
12645 * g_buffered_input_stream_set_buffer_size:
12646 * @stream: a #GBufferedInputStream
12649 * Sets the size of the internal buffer of @stream to @size, or to the
12650 * size of the contents of the buffer. The buffer can never be resized
12651 * smaller than its current contents.
12656 * g_buffered_output_stream_get_auto_grow:
12657 * @stream: a #GBufferedOutputStream.
12659 * Checks if the buffer automatically grows as data is added.
12661 * Returns: %TRUE if the @stream's buffer automatically grows,
12662 * %FALSE otherwise.
12667 * g_buffered_output_stream_get_buffer_size:
12668 * @stream: a #GBufferedOutputStream.
12670 * Gets the size of the buffer in the @stream.
12672 * Returns: the current size of the buffer.
12677 * g_buffered_output_stream_new:
12678 * @base_stream: a #GOutputStream.
12680 * Creates a new buffered output stream for a base stream.
12682 * Returns: a #GOutputStream for the given @base_stream.
12687 * g_buffered_output_stream_new_sized:
12688 * @base_stream: a #GOutputStream.
12691 * Creates a new buffered output stream with a given buffer size.
12693 * Returns: a #GOutputStream with an internal buffer set to @size.
12698 * g_buffered_output_stream_set_auto_grow:
12699 * @stream: a #GBufferedOutputStream.
12700 * @auto_grow: a #gboolean.
12702 * Sets whether or not the @stream's buffer should automatically grow.
12703 * If @auto_grow is true, then each write will just make the buffer
12704 * larger, and you must manually flush the buffer to actually write out
12705 * the data to the underlying stream.
12710 * g_buffered_output_stream_set_buffer_size:
12711 * @stream: a #GBufferedOutputStream.
12714 * Sets the size of the internal buffer to @size.
12720 * @bus_type: a #GBusType
12721 * @cancellable: (allow-none): a #GCancellable or %NULL
12722 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
12723 * @user_data: the data to pass to @callback
12725 * Asynchronously connects to the message bus specified by @bus_type.
12727 * When the operation is finished, @callback will be invoked. You can
12728 * then call g_bus_get_finish() to get the result of the operation.
12730 * This is a asynchronous failable function. See g_bus_get_sync() for
12731 * the synchronous version.
12738 * g_bus_get_finish:
12739 * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed
12741 * @error: return location for error or %NULL
12743 * Finishes an operation started with g_bus_get().
12745 * The returned object is a singleton, that is, shared with other
12746 * callers of g_bus_get() and g_bus_get_sync() for @bus_type. In the
12747 * event that you need a private message bus connection, use
12748 * g_dbus_address_get_for_bus_sync() and
12749 * g_dbus_connection_new_for_address().
12751 * Note that the returned #GDBusConnection object will (usually) have
12752 * the #GDBusConnection:exit-on-close property set to %TRUE.
12754 * Returns: (transfer full): a #GDBusConnection or %NULL if @error is set.
12755 * Free with g_object_unref().
12762 * @bus_type: a #GBusType
12763 * @cancellable: (allow-none): a #GCancellable or %NULL
12764 * @error: return location for error or %NULL
12766 * Synchronously connects to the message bus specified by @bus_type.
12767 * Note that the returned object may shared with other callers,
12768 * e.g. if two separate parts of a process calls this function with
12769 * the same @bus_type, they will share the same object.
12771 * This is a synchronous failable function. See g_bus_get() and
12772 * g_bus_get_finish() for the asynchronous version.
12774 * The returned object is a singleton, that is, shared with other
12775 * callers of g_bus_get() and g_bus_get_sync() for @bus_type. In the
12776 * event that you need a private message bus connection, use
12777 * g_dbus_address_get_for_bus_sync() and
12778 * g_dbus_connection_new_for_address().
12780 * Note that the returned #GDBusConnection object will (usually) have
12781 * the #GDBusConnection:exit-on-close property set to %TRUE.
12783 * Returns: (transfer full): a #GDBusConnection or %NULL if @error is set.
12784 * Free with g_object_unref().
12791 * @bus_type: the type of bus to own a name on
12792 * @name: the well-known name to own
12793 * @flags: a set of flags from the #GBusNameOwnerFlags enumeration
12794 * @bus_acquired_handler: (allow-none): handler to invoke when connected to the bus of type @bus_type or %NULL
12795 * @name_acquired_handler: (allow-none): handler to invoke when @name is acquired or %NULL
12796 * @name_lost_handler: (allow-none): handler to invoke when @name is lost or %NULL
12797 * @user_data: user data to pass to handlers
12798 * @user_data_free_func: (allow-none): function for freeing @user_data or %NULL
12800 * Starts acquiring @name on the bus specified by @bus_type and calls
12801 * @name_acquired_handler and @name_lost_handler when the name is
12802 * acquired respectively lost. Callbacks will be invoked in the
12803 * [thread-default main context][g-main-context-push-thread-default]
12804 * of the thread you are calling this function from.
12806 * You are guaranteed that one of the @name_acquired_handler and @name_lost_handler
12807 * callbacks will be invoked after calling this function - there are three
12810 * - @name_lost_handler with a %NULL connection (if a connection to the bus
12813 * - @bus_acquired_handler then @name_lost_handler (if the name can't be
12816 * - @bus_acquired_handler then @name_acquired_handler (if the name was
12819 * When you are done owning the name, just call g_bus_unown_name()
12820 * with the owner id this function returns.
12822 * If the name is acquired or lost (for example another application
12823 * could acquire the name if you allow replacement or the application
12824 * currently owning the name exits), the handlers are also invoked.
12825 * If the #GDBusConnection that is used for attempting to own the name
12826 * closes, then @name_lost_handler is invoked since it is no longer
12827 * possible for other processes to access the process.
12829 * You cannot use g_bus_own_name() several times for the same name (unless
12830 * interleaved with calls to g_bus_unown_name()) - only the first call
12833 * Another guarantee is that invocations of @name_acquired_handler
12834 * and @name_lost_handler are guaranteed to alternate; that
12835 * is, if @name_acquired_handler is invoked then you are
12836 * guaranteed that the next time one of the handlers is invoked, it
12837 * will be @name_lost_handler. The reverse is also true.
12839 * If you plan on exporting objects (using e.g.
12840 * g_dbus_connection_register_object()), note that it is generally too late
12841 * to export the objects in @name_acquired_handler. Instead, you can do this
12842 * in @bus_acquired_handler since you are guaranteed that this will run
12843 * before @name is requested from the bus.
12845 * This behavior makes it very simple to write applications that wants
12846 * to [own names][gdbus-owning-names] and export objects.
12847 * Simply register objects to be exported in @bus_acquired_handler and
12848 * unregister the objects (if any) in @name_lost_handler.
12850 * Returns: an identifier (never 0) that an be used with
12851 * g_bus_unown_name() to stop owning the name.
12857 * g_bus_own_name_on_connection:
12858 * @connection: a #GDBusConnection
12859 * @name: the well-known name to own
12860 * @flags: a set of flags from the #GBusNameOwnerFlags enumeration
12861 * @name_acquired_handler: (allow-none): handler to invoke when @name is acquired or %NULL
12862 * @name_lost_handler: (allow-none): handler to invoke when @name is lost or %NULL
12863 * @user_data: user data to pass to handlers
12864 * @user_data_free_func: (allow-none): function for freeing @user_data or %NULL
12866 * Like g_bus_own_name() but takes a #GDBusConnection instead of a
12869 * Returns: an identifier (never 0) that an be used with
12870 * g_bus_unown_name() to stop owning the name
12876 * g_bus_own_name_on_connection_with_closures: (rename-to g_bus_own_name_on_connection)
12877 * @connection: a #GDBusConnection
12878 * @name: the well-known name to own
12879 * @flags: a set of flags from the #GBusNameOwnerFlags enumeration
12880 * @name_acquired_closure: (allow-none): #GClosure to invoke when @name is
12881 * acquired or %NULL
12882 * @name_lost_closure: (allow-none): #GClosure to invoke when @name is lost
12885 * Version of g_bus_own_name_on_connection() using closures instead of
12886 * callbacks for easier binding in other languages.
12888 * Returns: an identifier (never 0) that an be used with
12889 * g_bus_unown_name() to stop owning the name.
12895 * g_bus_own_name_with_closures: (rename-to g_bus_own_name)
12896 * @bus_type: the type of bus to own a name on
12897 * @name: the well-known name to own
12898 * @flags: a set of flags from the #GBusNameOwnerFlags enumeration
12899 * @bus_acquired_closure: (allow-none): #GClosure to invoke when connected to
12900 * the bus of type @bus_type or %NULL
12901 * @name_acquired_closure: (allow-none): #GClosure to invoke when @name is
12902 * acquired or %NULL
12903 * @name_lost_closure: (allow-none): #GClosure to invoke when @name is lost or
12906 * Version of g_bus_own_name() using closures instead of callbacks for
12907 * easier binding in other languages.
12909 * Returns: an identifier (never 0) that an be used with
12910 * g_bus_unown_name() to stop owning the name.
12916 * g_bus_unown_name:
12917 * @owner_id: an identifier obtained from g_bus_own_name()
12919 * Stops owning a name.
12926 * g_bus_unwatch_name:
12927 * @watcher_id: An identifier obtained from g_bus_watch_name()
12929 * Stops watching a name.
12936 * g_bus_watch_name:
12937 * @bus_type: The type of bus to watch a name on.
12938 * @name: The name (well-known or unique) to watch.
12939 * @flags: Flags from the #GBusNameWatcherFlags enumeration.
12940 * @name_appeared_handler: (allow-none): Handler to invoke when @name is known to exist or %NULL.
12941 * @name_vanished_handler: (allow-none): Handler to invoke when @name is known to not exist or %NULL.
12942 * @user_data: User data to pass to handlers.
12943 * @user_data_free_func: (allow-none): Function for freeing @user_data or %NULL.
12945 * Starts watching @name on the bus specified by @bus_type and calls
12946 * @name_appeared_handler and @name_vanished_handler when the name is
12947 * known to have a owner respectively known to lose its
12948 * owner. Callbacks will be invoked in the
12949 * [thread-default main context][g-main-context-push-thread-default]
12950 * of the thread you are calling this function from.
12952 * You are guaranteed that one of the handlers will be invoked after
12953 * calling this function. When you are done watching the name, just
12954 * call g_bus_unwatch_name() with the watcher id this function
12957 * If the name vanishes or appears (for example the application owning
12958 * the name could restart), the handlers are also invoked. If the
12959 * #GDBusConnection that is used for watching the name disconnects, then
12960 * @name_vanished_handler is invoked since it is no longer
12961 * possible to access the name.
12963 * Another guarantee is that invocations of @name_appeared_handler
12964 * and @name_vanished_handler are guaranteed to alternate; that
12965 * is, if @name_appeared_handler is invoked then you are
12966 * guaranteed that the next time one of the handlers is invoked, it
12967 * will be @name_vanished_handler. The reverse is also true.
12969 * This behavior makes it very simple to write applications that want
12970 * to take action when a certain [name exists][gdbus-watching-names].
12971 * Basically, the application should create object proxies in
12972 * @name_appeared_handler and destroy them again (if any) in
12973 * @name_vanished_handler.
12975 * Returns: An identifier (never 0) that an be used with
12976 * g_bus_unwatch_name() to stop watching the name.
12982 * g_bus_watch_name_on_connection:
12983 * @connection: A #GDBusConnection.
12984 * @name: The name (well-known or unique) to watch.
12985 * @flags: Flags from the #GBusNameWatcherFlags enumeration.
12986 * @name_appeared_handler: (allow-none): Handler to invoke when @name is known to exist or %NULL.
12987 * @name_vanished_handler: (allow-none): Handler to invoke when @name is known to not exist or %NULL.
12988 * @user_data: User data to pass to handlers.
12989 * @user_data_free_func: (allow-none): Function for freeing @user_data or %NULL.
12991 * Like g_bus_watch_name() but takes a #GDBusConnection instead of a
12994 * Returns: An identifier (never 0) that an be used with
12995 * g_bus_unwatch_name() to stop watching the name.
13001 * g_bus_watch_name_on_connection_with_closures: (rename-to g_bus_watch_name_on_connection)
13002 * @connection: A #GDBusConnection.
13003 * @name: The name (well-known or unique) to watch.
13004 * @flags: Flags from the #GBusNameWatcherFlags enumeration.
13005 * @name_appeared_closure: (allow-none): #GClosure to invoke when @name is known
13006 * to exist or %NULL.
13007 * @name_vanished_closure: (allow-none): #GClosure to invoke when @name is known
13008 * to not exist or %NULL.
13010 * Version of g_bus_watch_name_on_connection() using closures instead of callbacks for
13011 * easier binding in other languages.
13013 * Returns: An identifier (never 0) that an be used with
13014 * g_bus_unwatch_name() to stop watching the name.
13020 * g_bus_watch_name_with_closures: (rename-to g_bus_watch_name)
13021 * @bus_type: The type of bus to watch a name on.
13022 * @name: The name (well-known or unique) to watch.
13023 * @flags: Flags from the #GBusNameWatcherFlags enumeration.
13024 * @name_appeared_closure: (allow-none): #GClosure to invoke when @name is known
13025 * to exist or %NULL.
13026 * @name_vanished_closure: (allow-none): #GClosure to invoke when @name is known
13027 * to not exist or %NULL.
13029 * Version of g_bus_watch_name() using closures instead of callbacks for
13030 * easier binding in other languages.
13032 * Returns: An identifier (never 0) that an be used with
13033 * g_bus_unwatch_name() to stop watching the name.
13039 * g_bytes_icon_get_bytes:
13042 * Gets the #GBytes associated with the given @icon.
13044 * Returns: (transfer none): a #GBytes, or %NULL.
13050 * g_bytes_icon_new:
13051 * @bytes: a #GBytes.
13053 * Creates a new icon for a bytes.
13055 * Returns: (transfer full) (type GBytesIcon): a #GIcon for the given
13056 * @bytes, or %NULL on error.
13062 * g_cancellable_cancel:
13063 * @cancellable: a #GCancellable object.
13065 * Will set @cancellable to cancelled, and will emit the
13066 * #GCancellable::cancelled signal. (However, see the warning about
13067 * race conditions in the documentation for that signal if you are
13068 * planning to connect to it.)
13070 * This function is thread-safe. In other words, you can safely call
13071 * it from a thread other than the one running the operation that was
13072 * passed the @cancellable.
13074 * The convention within gio is that cancelling an asynchronous
13075 * operation causes it to complete asynchronously. That is, if you
13076 * cancel the operation from the same thread in which it is running,
13077 * then the operation's #GAsyncReadyCallback will not be invoked until
13078 * the application returns to the main loop.
13083 * g_cancellable_connect:
13084 * @cancellable: A #GCancellable.
13085 * @callback: The #GCallback to connect.
13086 * @data: Data to pass to @callback.
13087 * @data_destroy_func: (allow-none): Free function for @data or %NULL.
13089 * Convenience function to connect to the #GCancellable::cancelled
13090 * signal. Also handles the race condition that may happen
13091 * if the cancellable is cancelled right before connecting.
13093 * @callback is called at most once, either directly at the
13094 * time of the connect if @cancellable is already cancelled,
13095 * or when @cancellable is cancelled in some thread.
13097 * @data_destroy_func will be called when the handler is
13098 * disconnected, or immediately if the cancellable is already
13101 * See #GCancellable::cancelled for details on how to use this.
13103 * Since GLib 2.40, the lock protecting @cancellable is not held when
13104 * @callback is invoked. This lifts a restriction in place for
13105 * earlier GLib versions which now makes it easier to write cleanup
13106 * code that unconditionally invokes e.g. g_cancellable_cancel().
13108 * Returns: The id of the signal handler or 0 if @cancellable has already
13115 * g_cancellable_disconnect:
13116 * @cancellable: (allow-none): A #GCancellable or %NULL.
13117 * @handler_id: Handler id of the handler to be disconnected, or %0.
13119 * Disconnects a handler from a cancellable instance similar to
13120 * g_signal_handler_disconnect(). Additionally, in the event that a
13121 * signal handler is currently running, this call will block until the
13122 * handler has finished. Calling this function from a
13123 * #GCancellable::cancelled signal handler will therefore result in a
13126 * This avoids a race condition where a thread cancels at the
13127 * same time as the cancellable operation is finished and the
13128 * signal handler is removed. See #GCancellable::cancelled for
13129 * details on how to use this.
13131 * If @cancellable is %NULL or @handler_id is %0 this function does
13139 * g_cancellable_get_current:
13141 * Gets the top cancellable from the stack.
13143 * Returns: (nullable) (transfer none): a #GCancellable from the top
13144 * of the stack, or %NULL if the stack is empty.
13149 * g_cancellable_get_fd:
13150 * @cancellable: a #GCancellable.
13152 * Gets the file descriptor for a cancellable job. This can be used to
13153 * implement cancellable operations on Unix systems. The returned fd will
13154 * turn readable when @cancellable is cancelled.
13156 * You are not supposed to read from the fd yourself, just check for
13157 * readable status. Reading to unset the readable status is done
13158 * with g_cancellable_reset().
13160 * After a successful return from this function, you should use
13161 * g_cancellable_release_fd() to free up resources allocated for
13162 * the returned file descriptor.
13164 * See also g_cancellable_make_pollfd().
13166 * Returns: A valid file descriptor. %-1 if the file descriptor
13167 * is not supported, or on errors.
13172 * g_cancellable_is_cancelled:
13173 * @cancellable: (allow-none): a #GCancellable or %NULL
13175 * Checks if a cancellable job has been cancelled.
13177 * Returns: %TRUE if @cancellable is cancelled,
13178 * FALSE if called with %NULL or if item is not cancelled.
13183 * g_cancellable_make_pollfd:
13184 * @cancellable: (allow-none): a #GCancellable or %NULL
13185 * @pollfd: a pointer to a #GPollFD
13187 * Creates a #GPollFD corresponding to @cancellable; this can be passed
13188 * to g_poll() and used to poll for cancellation. This is useful both
13189 * for unix systems without a native poll and for portability to
13192 * When this function returns %TRUE, you should use
13193 * g_cancellable_release_fd() to free up resources allocated for the
13194 * @pollfd. After a %FALSE return, do not call g_cancellable_release_fd().
13196 * If this function returns %FALSE, either no @cancellable was given or
13197 * resource limits prevent this function from allocating the necessary
13198 * structures for polling. (On Linux, you will likely have reached
13199 * the maximum number of file descriptors.) The suggested way to handle
13200 * these cases is to ignore the @cancellable.
13202 * You are not supposed to read from the fd yourself, just check for
13203 * readable status. Reading to unset the readable status is done
13204 * with g_cancellable_reset().
13206 * Returns: %TRUE if @pollfd was successfully initialized, %FALSE on
13207 * failure to prepare the cancellable.
13213 * g_cancellable_new:
13215 * Creates a new #GCancellable object.
13217 * Applications that want to start one or more operations
13218 * that should be cancellable should create a #GCancellable
13219 * and pass it to the operations.
13221 * One #GCancellable can be used in multiple consecutive
13222 * operations or in multiple concurrent operations.
13224 * Returns: a #GCancellable.
13229 * g_cancellable_pop_current:
13230 * @cancellable: a #GCancellable object
13232 * Pops @cancellable off the cancellable stack (verifying that @cancellable
13233 * is on the top of the stack).
13238 * g_cancellable_push_current:
13239 * @cancellable: a #GCancellable object
13241 * Pushes @cancellable onto the cancellable stack. The current
13242 * cancellable can then be received using g_cancellable_get_current().
13244 * This is useful when implementing cancellable operations in
13245 * code that does not allow you to pass down the cancellable object.
13247 * This is typically called automatically by e.g. #GFile operations,
13248 * so you rarely have to call this yourself.
13253 * g_cancellable_release_fd:
13254 * @cancellable: a #GCancellable
13256 * Releases a resources previously allocated by g_cancellable_get_fd()
13257 * or g_cancellable_make_pollfd().
13259 * For compatibility reasons with older releases, calling this function
13260 * is not strictly required, the resources will be automatically freed
13261 * when the @cancellable is finalized. However, the @cancellable will
13262 * block scarce file descriptors until it is finalized if this function
13263 * is not called. This can cause the application to run out of file
13264 * descriptors when many #GCancellables are used at the same time.
13271 * g_cancellable_reset:
13272 * @cancellable: a #GCancellable object.
13274 * Resets @cancellable to its uncancelled state.
13276 * If cancellable is currently in use by any cancellable operation
13277 * then the behavior of this function is undefined.
13282 * g_cancellable_set_error_if_cancelled:
13283 * @cancellable: (allow-none): a #GCancellable or %NULL
13284 * @error: #GError to append error state to
13286 * If the @cancellable is cancelled, sets the error to notify
13287 * that the operation was cancelled.
13289 * Returns: %TRUE if @cancellable was cancelled, %FALSE if it was not
13294 * g_cancellable_source_new: (skip)
13295 * @cancellable: (allow-none): a #GCancellable, or %NULL
13297 * Creates a source that triggers if @cancellable is cancelled and
13298 * calls its callback of type #GCancellableSourceFunc. This is
13299 * primarily useful for attaching to another (non-cancellable) source
13300 * with g_source_add_child_source() to add cancellability to it.
13302 * For convenience, you can call this with a %NULL #GCancellable,
13303 * in which case the source will never trigger.
13305 * Returns: (transfer full): the new #GSource.
13311 * g_charset_converter_get_num_fallbacks:
13312 * @converter: a #GCharsetConverter
13314 * Gets the number of fallbacks that @converter has applied so far.
13316 * Returns: the number of fallbacks that @converter has applied
13322 * g_charset_converter_get_use_fallback:
13323 * @converter: a #GCharsetConverter
13325 * Gets the #GCharsetConverter:use-fallback property.
13327 * Returns: %TRUE if fallbacks are used by @converter
13333 * g_charset_converter_new:
13334 * @to_charset: destination charset
13335 * @from_charset: source charset
13336 * @error: #GError for error reporting, or %NULL to ignore.
13338 * Creates a new #GCharsetConverter.
13340 * Returns: a new #GCharsetConverter or %NULL on error.
13346 * g_charset_converter_set_use_fallback:
13347 * @converter: a #GCharsetConverter
13348 * @use_fallback: %TRUE to use fallbacks
13350 * Sets the #GCharsetConverter:use-fallback property.
13357 * g_content_type_can_be_executable:
13358 * @type: a content type string
13360 * Checks if a content type can be executable. Note that for instance
13361 * things like text files can be executables (i.e. scripts and batch files).
13363 * Returns: %TRUE if the file type corresponds to a type that
13364 * can be executable, %FALSE otherwise.
13369 * g_content_type_equals:
13370 * @type1: a content type string
13371 * @type2: a content type string
13373 * Compares two content types for equality.
13375 * Returns: %TRUE if the two strings are identical or equivalent,
13376 * %FALSE otherwise.
13381 * g_content_type_from_mime_type:
13382 * @mime_type: a mime type string
13384 * Tries to find a content type based on the mime type name.
13386 * Returns: (nullable): Newly allocated string with content type or
13387 * %NULL. Free with g_free()
13393 * g_content_type_get_description:
13394 * @type: a content type string
13396 * Gets the human readable description of the content type.
13398 * Returns: a short description of the content type @type. Free the
13399 * returned string with g_free()
13404 * g_content_type_get_generic_icon_name:
13405 * @type: a content type string
13407 * Gets the generic icon name for a content type.
13410 * [shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec)
13411 * specification for more on the generic icon name.
13413 * Returns: (allow-none): the registered generic icon name for the given @type,
13414 * or %NULL if unknown. Free with g_free()
13420 * g_content_type_get_icon:
13421 * @type: a content type string
13423 * Gets the icon for a content type.
13425 * Returns: (transfer full): #GIcon corresponding to the content type. Free the returned
13426 * object with g_object_unref()
13431 * g_content_type_get_mime_type:
13432 * @type: a content type string
13434 * Gets the mime type for the content type, if one is registered.
13436 * Returns: (nullable): the registered mime type for the given @type,
13437 * or %NULL if unknown.
13442 * g_content_type_get_symbolic_icon:
13443 * @type: a content type string
13445 * Gets the symbolic icon for a content type.
13447 * Returns: (transfer full): symbolic #GIcon corresponding to the content type.
13448 * Free the returned object with g_object_unref()
13454 * g_content_type_guess:
13455 * @filename: (allow-none): a string, or %NULL
13456 * @data: (allow-none) (array length=data_size): a stream of data, or %NULL
13457 * @data_size: the size of @data
13458 * @result_uncertain: (allow-none) (out): return location for the certainty
13459 * of the result, or %NULL
13461 * Guesses the content type based on example data. If the function is
13462 * uncertain, @result_uncertain will be set to %TRUE. Either @filename
13463 * or @data may be %NULL, in which case the guess will be based solely
13464 * on the other argument.
13466 * Returns: a string indicating a guessed content type for the
13467 * given data. Free with g_free()
13472 * g_content_type_guess_for_tree:
13473 * @root: the root of the tree to guess a type for
13475 * Tries to guess the type of the tree with root @root, by
13476 * looking at the files it contains. The result is an array
13477 * of content types, with the best guess coming first.
13479 * The types returned all have the form x-content/foo, e.g.
13480 * x-content/audio-cdda (for audio CDs) or x-content/image-dcf
13481 * (for a camera memory card). See the
13482 * [shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec)
13483 * specification for more on x-content types.
13485 * This function is useful in the implementation of
13486 * g_mount_guess_content_type().
13488 * Returns: (transfer full) (array zero-terminated=1): an %NULL-terminated
13489 * array of zero or more content types. Free with g_strfreev()
13495 * g_content_type_is_a:
13496 * @type: a content type string
13497 * @supertype: a content type string
13499 * Determines if @type is a subset of @supertype.
13501 * Returns: %TRUE if @type is a kind of @supertype,
13502 * %FALSE otherwise.
13507 * g_content_type_is_unknown:
13508 * @type: a content type string
13510 * Checks if the content type is the generic "unknown" type.
13511 * On UNIX this is the "application/octet-stream" mimetype,
13512 * while on win32 it is "*".
13514 * Returns: %TRUE if the type is the unknown type.
13519 * g_content_types_get_registered:
13521 * Gets a list of strings containing all the registered content types
13522 * known to the system. The list and its data should be freed using
13523 * g_list_free_full (list, g_free).
13525 * Returns: (element-type utf8) (transfer full): list of the registered
13531 * g_converter_convert:
13532 * @converter: a #GConverter.
13533 * @inbuf: (array length=inbuf_size) (element-type guint8): the buffer
13534 * containing the data to convert.
13535 * @inbuf_size: the number of bytes in @inbuf
13536 * @outbuf: a buffer to write converted data in.
13537 * @outbuf_size: the number of bytes in @outbuf, must be at least one
13538 * @flags: a #GConverterFlags controlling the conversion details
13539 * @bytes_read: (out): will be set to the number of bytes read from @inbuf on success
13540 * @bytes_written: (out): will be set to the number of bytes written to @outbuf on success
13541 * @error: location to store the error occurring, or %NULL to ignore
13543 * This is the main operation used when converting data. It is to be called
13544 * multiple times in a loop, and each time it will do some work, i.e.
13545 * producing some output (in @outbuf) or consuming some input (from @inbuf) or
13546 * both. If its not possible to do any work an error is returned.
13548 * Note that a single call may not consume all input (or any input at all).
13549 * Also a call may produce output even if given no input, due to state stored
13550 * in the converter producing output.
13552 * If any data was either produced or consumed, and then an error happens, then
13553 * only the successful conversion is reported and the error is returned on the
13556 * A full conversion loop involves calling this method repeatedly, each time
13557 * giving it new input and space output space. When there is no more input
13558 * data after the data in @inbuf, the flag %G_CONVERTER_INPUT_AT_END must be set.
13559 * The loop will be (unless some error happens) returning %G_CONVERTER_CONVERTED
13560 * each time until all data is consumed and all output is produced, then
13561 * %G_CONVERTER_FINISHED is returned instead. Note, that %G_CONVERTER_FINISHED
13562 * may be returned even if %G_CONVERTER_INPUT_AT_END is not set, for instance
13563 * in a decompression converter where the end of data is detectable from the
13564 * data (and there might even be other data after the end of the compressed data).
13566 * When some data has successfully been converted @bytes_read and is set to
13567 * the number of bytes read from @inbuf, and @bytes_written is set to indicate
13568 * how many bytes was written to @outbuf. If there are more data to output
13569 * or consume (i.e. unless the %G_CONVERTER_INPUT_AT_END is specified) then
13570 * %G_CONVERTER_CONVERTED is returned, and if no more data is to be output
13571 * then %G_CONVERTER_FINISHED is returned.
13573 * On error %G_CONVERTER_ERROR is returned and @error is set accordingly.
13574 * Some errors need special handling:
13576 * %G_IO_ERROR_NO_SPACE is returned if there is not enough space
13577 * to write the resulting converted data, the application should
13578 * call the function again with a larger @outbuf to continue.
13580 * %G_IO_ERROR_PARTIAL_INPUT is returned if there is not enough
13581 * input to fully determine what the conversion should produce,
13582 * and the %G_CONVERTER_INPUT_AT_END flag is not set. This happens for
13583 * example with an incomplete multibyte sequence when converting text,
13584 * or when a regexp matches up to the end of the input (and may match
13585 * further input). It may also happen when @inbuf_size is zero and
13586 * there is no more data to produce.
13588 * When this happens the application should read more input and then
13589 * call the function again. If further input shows that there is no
13590 * more data call the function again with the same data but with
13591 * the %G_CONVERTER_INPUT_AT_END flag set. This may cause the conversion
13592 * to finish as e.g. in the regexp match case (or, to fail again with
13593 * %G_IO_ERROR_PARTIAL_INPUT in e.g. a charset conversion where the
13594 * input is actually partial).
13596 * After g_converter_convert() has returned %G_CONVERTER_FINISHED the
13597 * converter object is in an invalid state where its not allowed
13598 * to call g_converter_convert() anymore. At this time you can only
13599 * free the object or call g_converter_reset() to reset it to the
13602 * If the flag %G_CONVERTER_FLUSH is set then conversion is modified
13603 * to try to write out all internal state to the output. The application
13604 * has to call the function multiple times with the flag set, and when
13605 * the available input has been consumed and all internal state has
13606 * been produced then %G_CONVERTER_FLUSHED (or %G_CONVERTER_FINISHED if
13607 * really at the end) is returned instead of %G_CONVERTER_CONVERTED.
13608 * This is somewhat similar to what happens at the end of the input stream,
13609 * but done in the middle of the data.
13611 * This has different meanings for different conversions. For instance
13612 * in a compression converter it would mean that we flush all the
13613 * compression state into output such that if you uncompress the
13614 * compressed data you get back all the input data. Doing this may
13615 * make the final file larger due to padding though. Another example
13616 * is a regexp conversion, where if you at the end of the flushed data
13617 * have a match, but there is also a potential longer match. In the
13618 * non-flushed case we would ask for more input, but when flushing we
13619 * treat this as the end of input and do the match.
13621 * Flushing is not always possible (like if a charset converter flushes
13622 * at a partial multibyte sequence). Converters are supposed to try
13623 * to produce as much output as possible and then return an error
13624 * (typically %G_IO_ERROR_PARTIAL_INPUT).
13626 * Returns: a #GConverterResult, %G_CONVERTER_ERROR on error.
13632 * g_converter_input_stream_get_converter:
13633 * @converter_stream: a #GConverterInputStream
13635 * Gets the #GConverter that is used by @converter_stream.
13637 * Returns: (transfer none): the converter of the converter input stream
13643 * g_converter_input_stream_new:
13644 * @base_stream: a #GInputStream
13645 * @converter: a #GConverter
13647 * Creates a new converter input stream for the @base_stream.
13649 * Returns: a new #GInputStream.
13654 * g_converter_output_stream_get_converter:
13655 * @converter_stream: a #GConverterOutputStream
13657 * Gets the #GConverter that is used by @converter_stream.
13659 * Returns: (transfer none): the converter of the converter output stream
13665 * g_converter_output_stream_new:
13666 * @base_stream: a #GOutputStream
13667 * @converter: a #GConverter
13669 * Creates a new converter output stream for the @base_stream.
13671 * Returns: a new #GOutputStream.
13676 * g_converter_reset:
13677 * @converter: a #GConverter.
13679 * Resets all internal state in the converter, making it behave
13680 * as if it was just created. If the converter has any internal
13681 * state that would produce output then that output is lost.
13688 * g_credentials_get_native: (skip)
13689 * @credentials: A #GCredentials.
13690 * @native_type: The type of native credentials to get.
13692 * Gets a pointer to native credentials of type @native_type from
13695 * It is a programming error (which will cause an warning to be
13696 * logged) to use this method if there is no #GCredentials support for
13697 * the OS or if @native_type isn't supported by the OS.
13699 * Returns: The pointer to native credentials or %NULL if the
13700 * operation there is no #GCredentials support for the OS or if
13701 * @native_type isn't supported by the OS. Do not free the returned
13702 * data, it is owned by @credentials.
13708 * g_credentials_get_unix_pid:
13709 * @credentials: A #GCredentials
13710 * @error: Return location for error or %NULL.
13712 * Tries to get the UNIX process identifier from @credentials. This
13713 * method is only available on UNIX platforms.
13715 * This operation can fail if #GCredentials is not supported on the
13716 * OS or if the native credentials type does not contain information
13717 * about the UNIX process ID.
13719 * Returns: The UNIX process ID, or -1 if @error is set.
13725 * g_credentials_get_unix_user:
13726 * @credentials: A #GCredentials
13727 * @error: Return location for error or %NULL.
13729 * Tries to get the UNIX user identifier from @credentials. This
13730 * method is only available on UNIX platforms.
13732 * This operation can fail if #GCredentials is not supported on the
13733 * OS or if the native credentials type does not contain information
13734 * about the UNIX user.
13736 * Returns: The UNIX user identifier or -1 if @error is set.
13742 * g_credentials_is_same_user:
13743 * @credentials: A #GCredentials.
13744 * @other_credentials: A #GCredentials.
13745 * @error: Return location for error or %NULL.
13747 * Checks if @credentials and @other_credentials is the same user.
13749 * This operation can fail if #GCredentials is not supported on the
13752 * Returns: %TRUE if @credentials and @other_credentials has the same
13753 * user, %FALSE otherwise or if @error is set.
13759 * g_credentials_new:
13761 * Creates a new #GCredentials object with credentials matching the
13762 * the current process.
13764 * Returns: A #GCredentials. Free with g_object_unref().
13770 * g_credentials_set_native:
13771 * @credentials: A #GCredentials.
13772 * @native_type: The type of native credentials to set.
13773 * @native: A pointer to native credentials.
13775 * Copies the native credentials of type @native_type from @native
13776 * into @credentials.
13778 * It is a programming error (which will cause an warning to be
13779 * logged) to use this method if there is no #GCredentials support for
13780 * the OS or if @native_type isn't supported by the OS.
13787 * g_credentials_set_unix_user:
13788 * @credentials: A #GCredentials.
13789 * @uid: The UNIX user identifier to set.
13790 * @error: Return location for error or %NULL.
13792 * Tries to set the UNIX user identifier on @credentials. This method
13793 * is only available on UNIX platforms.
13795 * This operation can fail if #GCredentials is not supported on the
13796 * OS or if the native credentials type does not contain information
13797 * about the UNIX user. It can also fail if the OS does not allow the
13798 * use of "spoofed" credentials.
13800 * Returns: %TRUE if @uid was set, %FALSE if error is set.
13806 * g_credentials_to_string:
13807 * @credentials: A #GCredentials object.
13809 * Creates a human-readable textual representation of @credentials
13810 * that can be used in logging and debug messages. The format of the
13811 * returned string may change in future GLib release.
13813 * Returns: A string that should be freed with g_free().
13819 * g_data_input_stream_get_byte_order:
13820 * @stream: a given #GDataInputStream.
13822 * Gets the byte order for the data input stream.
13824 * Returns: the @stream's current #GDataStreamByteOrder.
13829 * g_data_input_stream_get_newline_type:
13830 * @stream: a given #GDataInputStream.
13832 * Gets the current newline type for the @stream.
13834 * Returns: #GDataStreamNewlineType for the given @stream.
13839 * g_data_input_stream_new:
13840 * @base_stream: a #GInputStream.
13842 * Creates a new data input stream for the @base_stream.
13844 * Returns: a new #GDataInputStream.
13849 * g_data_input_stream_read_byte:
13850 * @stream: a given #GDataInputStream.
13851 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
13852 * @error: #GError for error reporting.
13854 * Reads an unsigned 8-bit/1-byte value from @stream.
13856 * Returns: an unsigned 8-bit/1-byte value read from the @stream or %0
13857 * if an error occurred.
13862 * g_data_input_stream_read_int16:
13863 * @stream: a given #GDataInputStream.
13864 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
13865 * @error: #GError for error reporting.
13867 * Reads a 16-bit/2-byte value from @stream.
13869 * In order to get the correct byte order for this read operation,
13870 * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().
13872 * Returns: a signed 16-bit/2-byte value read from @stream or %0 if
13873 * an error occurred.
13878 * g_data_input_stream_read_int32:
13879 * @stream: a given #GDataInputStream.
13880 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
13881 * @error: #GError for error reporting.
13883 * Reads a signed 32-bit/4-byte value from @stream.
13885 * In order to get the correct byte order for this read operation,
13886 * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().
13888 * If @cancellable is not %NULL, then the operation can be cancelled by
13889 * triggering the cancellable object from another thread. If the operation
13890 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
13892 * Returns: a signed 32-bit/4-byte value read from the @stream or %0 if
13893 * an error occurred.
13898 * g_data_input_stream_read_int64:
13899 * @stream: a given #GDataInputStream.
13900 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
13901 * @error: #GError for error reporting.
13903 * Reads a 64-bit/8-byte value from @stream.
13905 * In order to get the correct byte order for this read operation,
13906 * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().
13908 * If @cancellable is not %NULL, then the operation can be cancelled by
13909 * triggering the cancellable object from another thread. If the operation
13910 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
13912 * Returns: a signed 64-bit/8-byte value read from @stream or %0 if
13913 * an error occurred.
13918 * g_data_input_stream_read_line:
13919 * @stream: a given #GDataInputStream.
13920 * @length: (out): a #gsize to get the length of the data read in.
13921 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
13922 * @error: #GError for error reporting.
13924 * Reads a line from the data input stream. Note that no encoding
13925 * checks or conversion is performed; the input is not guaranteed to
13926 * be UTF-8, and may in fact have embedded NUL characters.
13928 * If @cancellable is not %NULL, then the operation can be cancelled by
13929 * triggering the cancellable object from another thread. If the operation
13930 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
13932 * Returns: (nullable) (transfer full) (array zero-terminated=1) (element-type guint8):
13933 * a NUL terminated byte array with the line that was read in
13934 * (without the newlines). Set @length to a #gsize to get the length
13935 * of the read line. On an error, it will return %NULL and @error
13936 * will be set. If there's no content to read, it will still return
13937 * %NULL, but @error won't be set.
13942 * g_data_input_stream_read_line_async:
13943 * @stream: a given #GDataInputStream.
13944 * @io_priority: the [I/O priority][io-priority] of the request
13945 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
13946 * @callback: (scope async): callback to call when the request is satisfied.
13947 * @user_data: (closure): the data to pass to callback function.
13949 * The asynchronous version of g_data_input_stream_read_line(). It is
13950 * an error to have two outstanding calls to this function.
13952 * When the operation is finished, @callback will be called. You
13953 * can then call g_data_input_stream_read_line_finish() to get
13954 * the result of the operation.
13961 * g_data_input_stream_read_line_finish:
13962 * @stream: a given #GDataInputStream.
13963 * @result: the #GAsyncResult that was provided to the callback.
13964 * @length: (out): a #gsize to get the length of the data read in.
13965 * @error: #GError for error reporting.
13967 * Finish an asynchronous call started by
13968 * g_data_input_stream_read_line_async(). Note the warning about
13969 * string encoding in g_data_input_stream_read_line() applies here as
13972 * Returns: (nullable) (transfer full) (array zero-terminated=1) (element-type guint8):
13973 * a NUL-terminated byte array with the line that was read in
13974 * (without the newlines). Set @length to a #gsize to get the length
13975 * of the read line. On an error, it will return %NULL and @error
13976 * will be set. If there's no content to read, it will still return
13977 * %NULL, but @error won't be set.
13983 * g_data_input_stream_read_line_finish_utf8:
13984 * @stream: a given #GDataInputStream.
13985 * @result: the #GAsyncResult that was provided to the callback.
13986 * @length: (out): a #gsize to get the length of the data read in.
13987 * @error: #GError for error reporting.
13989 * Finish an asynchronous call started by
13990 * g_data_input_stream_read_line_async().
13992 * Returns: (nullable) (transfer full): a string with the line that
13993 * was read in (without the newlines). Set @length to a #gsize to
13994 * get the length of the read line. On an error, it will return
13995 * %NULL and @error will be set. For UTF-8 conversion errors, the set
13996 * error domain is %G_CONVERT_ERROR. If there's no content to read,
13997 * it will still return %NULL, but @error won't be set.
14003 * g_data_input_stream_read_line_utf8:
14004 * @stream: a given #GDataInputStream.
14005 * @length: (out): a #gsize to get the length of the data read in.
14006 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
14007 * @error: #GError for error reporting.
14009 * Reads a UTF-8 encoded line from the data input stream.
14011 * If @cancellable is not %NULL, then the operation can be cancelled by
14012 * triggering the cancellable object from another thread. If the operation
14013 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
14015 * Returns: (nullable) (transfer full): a NUL terminated UTF-8 string
14016 * with the line that was read in (without the newlines). Set
14017 * @length to a #gsize to get the length of the read line. On an
14018 * error, it will return %NULL and @error will be set. For UTF-8
14019 * conversion errors, the set error domain is %G_CONVERT_ERROR. If
14020 * there's no content to read, it will still return %NULL, but @error
14027 * g_data_input_stream_read_uint16:
14028 * @stream: a given #GDataInputStream.
14029 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
14030 * @error: #GError for error reporting.
14032 * Reads an unsigned 16-bit/2-byte value from @stream.
14034 * In order to get the correct byte order for this read operation,
14035 * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().
14037 * Returns: an unsigned 16-bit/2-byte value read from the @stream or %0 if
14038 * an error occurred.
14043 * g_data_input_stream_read_uint32:
14044 * @stream: a given #GDataInputStream.
14045 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
14046 * @error: #GError for error reporting.
14048 * Reads an unsigned 32-bit/4-byte value from @stream.
14050 * In order to get the correct byte order for this read operation,
14051 * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().
14053 * If @cancellable is not %NULL, then the operation can be cancelled by
14054 * triggering the cancellable object from another thread. If the operation
14055 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
14057 * Returns: an unsigned 32-bit/4-byte value read from the @stream or %0 if
14058 * an error occurred.
14063 * g_data_input_stream_read_uint64:
14064 * @stream: a given #GDataInputStream.
14065 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
14066 * @error: #GError for error reporting.
14068 * Reads an unsigned 64-bit/8-byte value from @stream.
14070 * In order to get the correct byte order for this read operation,
14071 * see g_data_input_stream_get_byte_order().
14073 * If @cancellable is not %NULL, then the operation can be cancelled by
14074 * triggering the cancellable object from another thread. If the operation
14075 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
14077 * Returns: an unsigned 64-bit/8-byte read from @stream or %0 if
14078 * an error occurred.
14083 * g_data_input_stream_read_until:
14084 * @stream: a given #GDataInputStream.
14085 * @stop_chars: characters to terminate the read.
14086 * @length: (out): a #gsize to get the length of the data read in.
14087 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
14088 * @error: #GError for error reporting.
14090 * Reads a string from the data input stream, up to the first
14091 * occurrence of any of the stop characters.
14093 * Note that, in contrast to g_data_input_stream_read_until_async(),
14094 * this function consumes the stop character that it finds.
14096 * Don't use this function in new code. Its functionality is
14097 * inconsistent with g_data_input_stream_read_until_async(). Both
14098 * functions will be marked as deprecated in a future release. Use
14099 * g_data_input_stream_read_upto() instead, but note that that function
14100 * does not consume the stop character.
14102 * Returns: (transfer full): a string with the data that was read
14103 * before encountering any of the stop characters. Set @length to
14104 * a #gsize to get the length of the string. This function will
14105 * return %NULL on an error.
14110 * g_data_input_stream_read_until_async:
14111 * @stream: a given #GDataInputStream.
14112 * @stop_chars: characters to terminate the read.
14113 * @io_priority: the [I/O priority][io-priority] of the request
14114 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
14115 * @callback: (scope async): callback to call when the request is satisfied.
14116 * @user_data: (closure): the data to pass to callback function.
14118 * The asynchronous version of g_data_input_stream_read_until().
14119 * It is an error to have two outstanding calls to this function.
14121 * Note that, in contrast to g_data_input_stream_read_until(),
14122 * this function does not consume the stop character that it finds. You
14123 * must read it for yourself.
14125 * When the operation is finished, @callback will be called. You
14126 * can then call g_data_input_stream_read_until_finish() to get
14127 * the result of the operation.
14129 * Don't use this function in new code. Its functionality is
14130 * inconsistent with g_data_input_stream_read_until(). Both functions
14131 * will be marked as deprecated in a future release. Use
14132 * g_data_input_stream_read_upto_async() instead.
14139 * g_data_input_stream_read_until_finish:
14140 * @stream: a given #GDataInputStream.
14141 * @result: the #GAsyncResult that was provided to the callback.
14142 * @length: (out): a #gsize to get the length of the data read in.
14143 * @error: #GError for error reporting.
14145 * Finish an asynchronous call started by
14146 * g_data_input_stream_read_until_async().
14149 * Returns: (transfer full): a string with the data that was read
14150 * before encountering any of the stop characters. Set @length to
14151 * a #gsize to get the length of the string. This function will
14152 * return %NULL on an error.
14157 * g_data_input_stream_read_upto:
14158 * @stream: a #GDataInputStream
14159 * @stop_chars: characters to terminate the read
14160 * @stop_chars_len: length of @stop_chars. May be -1 if @stop_chars is
14162 * @length: (out): a #gsize to get the length of the data read in
14163 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
14164 * @error: #GError for error reporting
14166 * Reads a string from the data input stream, up to the first
14167 * occurrence of any of the stop characters.
14169 * In contrast to g_data_input_stream_read_until(), this function
14170 * does not consume the stop character. You have to use
14171 * g_data_input_stream_read_byte() to get it before calling
14172 * g_data_input_stream_read_upto() again.
14174 * Note that @stop_chars may contain '\0' if @stop_chars_len is
14177 * Returns: (transfer full): a string with the data that was read
14178 * before encountering any of the stop characters. Set @length to
14179 * a #gsize to get the length of the string. This function will
14180 * return %NULL on an error
14186 * g_data_input_stream_read_upto_async:
14187 * @stream: a #GDataInputStream
14188 * @stop_chars: characters to terminate the read
14189 * @stop_chars_len: length of @stop_chars. May be -1 if @stop_chars is
14191 * @io_priority: the [I/O priority][io-priority] of the request
14192 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
14193 * @callback: (scope async): callback to call when the request is satisfied
14194 * @user_data: (closure): the data to pass to callback function
14196 * The asynchronous version of g_data_input_stream_read_upto().
14197 * It is an error to have two outstanding calls to this function.
14199 * In contrast to g_data_input_stream_read_until(), this function
14200 * does not consume the stop character. You have to use
14201 * g_data_input_stream_read_byte() to get it before calling
14202 * g_data_input_stream_read_upto() again.
14204 * Note that @stop_chars may contain '\0' if @stop_chars_len is
14207 * When the operation is finished, @callback will be called. You
14208 * can then call g_data_input_stream_read_upto_finish() to get
14209 * the result of the operation.
14216 * g_data_input_stream_read_upto_finish:
14217 * @stream: a #GDataInputStream
14218 * @result: the #GAsyncResult that was provided to the callback
14219 * @length: (out): a #gsize to get the length of the data read in
14220 * @error: #GError for error reporting
14222 * Finish an asynchronous call started by
14223 * g_data_input_stream_read_upto_async().
14225 * Note that this function does not consume the stop character. You
14226 * have to use g_data_input_stream_read_byte() to get it before calling
14227 * g_data_input_stream_read_upto_async() again.
14229 * Returns: (transfer full): a string with the data that was read
14230 * before encountering any of the stop characters. Set @length to
14231 * a #gsize to get the length of the string. This function will
14232 * return %NULL on an error.
14238 * g_data_input_stream_set_byte_order:
14239 * @stream: a given #GDataInputStream.
14240 * @order: a #GDataStreamByteOrder to set.
14242 * This function sets the byte order for the given @stream. All subsequent
14243 * reads from the @stream will be read in the given @order.
14248 * g_data_input_stream_set_newline_type:
14249 * @stream: a #GDataInputStream.
14250 * @type: the type of new line return as #GDataStreamNewlineType.
14252 * Sets the newline type for the @stream.
14254 * Note that using G_DATA_STREAM_NEWLINE_TYPE_ANY is slightly unsafe. If a read
14255 * chunk ends in "CR" we must read an additional byte to know if this is "CR" or
14256 * "CR LF", and this might block if there is no more data available.
14261 * g_data_output_stream_get_byte_order:
14262 * @stream: a #GDataOutputStream.
14264 * Gets the byte order for the stream.
14266 * Returns: the #GDataStreamByteOrder for the @stream.
14271 * g_data_output_stream_new:
14272 * @base_stream: a #GOutputStream.
14274 * Creates a new data output stream for @base_stream.
14276 * Returns: #GDataOutputStream.
14281 * g_data_output_stream_put_byte:
14282 * @stream: a #GDataOutputStream.
14283 * @data: a #guchar.
14284 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
14285 * @error: a #GError, %NULL to ignore.
14287 * Puts a byte into the output stream.
14289 * Returns: %TRUE if @data was successfully added to the @stream.
14294 * g_data_output_stream_put_int16:
14295 * @stream: a #GDataOutputStream.
14296 * @data: a #gint16.
14297 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
14298 * @error: a #GError, %NULL to ignore.
14300 * Puts a signed 16-bit integer into the output stream.
14302 * Returns: %TRUE if @data was successfully added to the @stream.
14307 * g_data_output_stream_put_int32:
14308 * @stream: a #GDataOutputStream.
14309 * @data: a #gint32.
14310 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
14311 * @error: a #GError, %NULL to ignore.
14313 * Puts a signed 32-bit integer into the output stream.
14315 * Returns: %TRUE if @data was successfully added to the @stream.
14320 * g_data_output_stream_put_int64:
14321 * @stream: a #GDataOutputStream.
14322 * @data: a #gint64.
14323 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
14324 * @error: a #GError, %NULL to ignore.
14326 * Puts a signed 64-bit integer into the stream.
14328 * Returns: %TRUE if @data was successfully added to the @stream.
14333 * g_data_output_stream_put_string:
14334 * @stream: a #GDataOutputStream.
14336 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
14337 * @error: a #GError, %NULL to ignore.
14339 * Puts a string into the output stream.
14341 * Returns: %TRUE if @string was successfully added to the @stream.
14346 * g_data_output_stream_put_uint16:
14347 * @stream: a #GDataOutputStream.
14348 * @data: a #guint16.
14349 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
14350 * @error: a #GError, %NULL to ignore.
14352 * Puts an unsigned 16-bit integer into the output stream.
14354 * Returns: %TRUE if @data was successfully added to the @stream.
14359 * g_data_output_stream_put_uint32:
14360 * @stream: a #GDataOutputStream.
14361 * @data: a #guint32.
14362 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
14363 * @error: a #GError, %NULL to ignore.
14365 * Puts an unsigned 32-bit integer into the stream.
14367 * Returns: %TRUE if @data was successfully added to the @stream.
14372 * g_data_output_stream_put_uint64:
14373 * @stream: a #GDataOutputStream.
14374 * @data: a #guint64.
14375 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
14376 * @error: a #GError, %NULL to ignore.
14378 * Puts an unsigned 64-bit integer into the stream.
14380 * Returns: %TRUE if @data was successfully added to the @stream.
14385 * g_data_output_stream_set_byte_order:
14386 * @stream: a #GDataOutputStream.
14387 * @order: a %GDataStreamByteOrder.
14389 * Sets the byte order of the data output stream to @order.
14394 * g_dbus_action_group_get:
14395 * @connection: A #GDBusConnection
14396 * @bus_name: the bus name which exports the action group
14397 * @object_path: the object path at which the action group is exported
14399 * Obtains a #GDBusActionGroup for the action group which is exported at
14400 * the given @bus_name and @object_path.
14402 * The thread default main context is taken at the time of this call.
14403 * All signals on the menu model (and any linked models) are reported
14404 * with respect to this context. All calls on the returned menu model
14405 * (and linked models) must also originate from this same context, with
14406 * the thread default main context unchanged.
14408 * This call is non-blocking. The returned action group may or may not
14409 * already be filled in. The correct thing to do is connect the signals
14410 * for the action group to monitor for changes and then to call
14411 * g_action_group_list_actions() to get the initial list.
14413 * Returns: (transfer full): a #GDBusActionGroup
14419 * g_dbus_address_escape_value:
14420 * @string: an unescaped string to be included in a D-Bus address
14421 * as the value in a key-value pair
14423 * Escape @string so it can appear in a D-Bus address as the value
14424 * part of a key-value pair.
14426 * For instance, if @string is "/run/bus-for-:0",
14427 * this function would return "/run/bus-for-%3A0",
14428 * which could be used in a D-Bus address like
14429 * "unix:nonce-tcp:host=127.0.0.1,port=42,noncefile=/run/bus-for-%3A0".
14431 * Returns: (transfer full): a copy of @string with all
14432 * non-optionally-escaped bytes escaped
14438 * g_dbus_address_get_for_bus_sync:
14439 * @bus_type: a #GBusType
14440 * @cancellable: (allow-none): a #GCancellable or %NULL
14441 * @error: return location for error or %NULL
14443 * Synchronously looks up the D-Bus address for the well-known message
14444 * bus instance specified by @bus_type. This may involve using various
14445 * platform specific mechanisms.
14447 * Returns: a valid D-Bus address string for @bus_type or %NULL if
14454 * g_dbus_address_get_stream:
14455 * @address: A valid D-Bus address.
14456 * @cancellable: (allow-none): A #GCancellable or %NULL.
14457 * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
14458 * @user_data: Data to pass to @callback.
14460 * Asynchronously connects to an endpoint specified by @address and
14461 * sets up the connection so it is in a state to run the client-side
14462 * of the D-Bus authentication conversation.
14464 * When the operation is finished, @callback will be invoked. You can
14465 * then call g_dbus_address_get_stream_finish() to get the result of
14468 * This is an asynchronous failable function. See
14469 * g_dbus_address_get_stream_sync() for the synchronous version.
14476 * g_dbus_address_get_stream_finish:
14477 * @res: A #GAsyncResult obtained from the GAsyncReadyCallback passed to g_dbus_address_get_stream().
14478 * @out_guid: %NULL or return location to store the GUID extracted from @address, if any.
14479 * @error: Return location for error or %NULL.
14481 * Finishes an operation started with g_dbus_address_get_stream().
14483 * Returns: (transfer full): A #GIOStream or %NULL if @error is set.
14489 * g_dbus_address_get_stream_sync:
14490 * @address: A valid D-Bus address.
14491 * @out_guid: %NULL or return location to store the GUID extracted from @address, if any.
14492 * @cancellable: (allow-none): A #GCancellable or %NULL.
14493 * @error: Return location for error or %NULL.
14495 * Synchronously connects to an endpoint specified by @address and
14496 * sets up the connection so it is in a state to run the client-side
14497 * of the D-Bus authentication conversation.
14499 * This is a synchronous failable function. See
14500 * g_dbus_address_get_stream() for the asynchronous version.
14502 * Returns: (transfer full): A #GIOStream or %NULL if @error is set.
14508 * g_dbus_annotation_info_lookup:
14509 * @annotations: (array zero-terminated=1) (allow-none): A %NULL-terminated array of annotations or %NULL.
14510 * @name: The name of the annotation to look up.
14512 * Looks up the value of an annotation.
14514 * The cost of this function is O(n) in number of annotations.
14516 * Returns: The value or %NULL if not found. Do not free, it is owned by @annotations.
14522 * g_dbus_annotation_info_ref:
14523 * @info: A #GDBusNodeInfo
14525 * If @info is statically allocated does nothing. Otherwise increases
14526 * the reference count.
14528 * Returns: The same @info.
14534 * g_dbus_annotation_info_unref:
14535 * @info: A #GDBusAnnotationInfo.
14537 * If @info is statically allocated, does nothing. Otherwise decreases
14538 * the reference count of @info. When its reference count drops to 0,
14539 * the memory used is freed.
14546 * g_dbus_arg_info_ref:
14547 * @info: A #GDBusArgInfo
14549 * If @info is statically allocated does nothing. Otherwise increases
14550 * the reference count.
14552 * Returns: The same @info.
14558 * g_dbus_arg_info_unref:
14559 * @info: A #GDBusArgInfo.
14561 * If @info is statically allocated, does nothing. Otherwise decreases
14562 * the reference count of @info. When its reference count drops to 0,
14563 * the memory used is freed.
14570 * g_dbus_auth_observer_allow_mechanism:
14571 * @observer: A #GDBusAuthObserver.
14572 * @mechanism: The name of the mechanism, e.g. `DBUS_COOKIE_SHA1`.
14574 * Emits the #GDBusAuthObserver::allow-mechanism signal on @observer.
14576 * Returns: %TRUE if @mechanism can be used to authenticate the other peer, %FALSE if not.
14582 * g_dbus_auth_observer_authorize_authenticated_peer:
14583 * @observer: A #GDBusAuthObserver.
14584 * @stream: A #GIOStream for the #GDBusConnection.
14585 * @credentials: (allow-none): Credentials received from the peer or %NULL.
14587 * Emits the #GDBusAuthObserver::authorize-authenticated-peer signal on @observer.
14589 * Returns: %TRUE if the peer is authorized, %FALSE if not.
14595 * g_dbus_auth_observer_new:
14597 * Creates a new #GDBusAuthObserver object.
14599 * Returns: A #GDBusAuthObserver. Free with g_object_unref().
14605 * g_dbus_connection_add_filter:
14606 * @connection: a #GDBusConnection
14607 * @filter_function: a filter function
14608 * @user_data: user data to pass to @filter_function
14609 * @user_data_free_func: function to free @user_data with when filter
14610 * is removed or %NULL
14612 * Adds a message filter. Filters are handlers that are run on all
14613 * incoming and outgoing messages, prior to standard dispatch. Filters
14614 * are run in the order that they were added. The same handler can be
14615 * added as a filter more than once, in which case it will be run more
14616 * than once. Filters added during a filter callback won't be run on
14617 * the message being processed. Filter functions are allowed to modify
14618 * and even drop messages.
14620 * Note that filters are run in a dedicated message handling thread so
14621 * they can't block and, generally, can't do anything but signal a
14622 * worker thread. Also note that filters are rarely needed - use API
14623 * such as g_dbus_connection_send_message_with_reply(),
14624 * g_dbus_connection_signal_subscribe() or g_dbus_connection_call() instead.
14626 * If a filter consumes an incoming message the message is not
14627 * dispatched anywhere else - not even the standard dispatch machinery
14628 * (that API such as g_dbus_connection_signal_subscribe() and
14629 * g_dbus_connection_send_message_with_reply() relies on) will see the
14630 * message. Similary, if a filter consumes an outgoing message, the
14631 * message will not be sent to the other peer.
14633 * Returns: a filter identifier that can be used with
14634 * g_dbus_connection_remove_filter()
14640 * g_dbus_connection_call:
14641 * @connection: a #GDBusConnection
14642 * @bus_name: (allow-none): a unique or well-known bus name or %NULL if
14643 * @connection is not a message bus connection
14644 * @object_path: path of remote object
14645 * @interface_name: D-Bus interface to invoke method on
14646 * @method_name: the name of the method to invoke
14647 * @parameters: (allow-none): a #GVariant tuple with parameters for the method
14648 * or %NULL if not passing parameters
14649 * @reply_type: (allow-none): the expected type of the reply, or %NULL
14650 * @flags: flags from the #GDBusCallFlags enumeration
14651 * @timeout_msec: the timeout in milliseconds, -1 to use the default
14652 * timeout or %G_MAXINT for no timeout
14653 * @cancellable: (allow-none): a #GCancellable or %NULL
14654 * @callback: (allow-none): a #GAsyncReadyCallback to call when the request
14655 * is satisfied or %NULL if you don't care about the result of the
14656 * method invocation
14657 * @user_data: the data to pass to @callback
14659 * Asynchronously invokes the @method_name method on the
14660 * @interface_name D-Bus interface on the remote object at
14661 * @object_path owned by @bus_name.
14663 * If @connection is closed then the operation will fail with
14664 * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will
14665 * fail with %G_IO_ERROR_CANCELLED. If @parameters contains a value
14666 * not compatible with the D-Bus protocol, the operation fails with
14667 * %G_IO_ERROR_INVALID_ARGUMENT.
14669 * If @reply_type is non-%NULL then the reply will be checked for having this type and an
14670 * error will be raised if it does not match. Said another way, if you give a @reply_type
14671 * then any non-%NULL return value will be of this type.
14673 * If the @parameters #GVariant is floating, it is consumed. This allows
14674 * convenient 'inline' use of g_variant_new(), e.g.:
14675 * |[<!-- language="C" -->
14676 * g_dbus_connection_call (connection,
14677 * "org.freedesktop.StringThings",
14678 * "/org/freedesktop/StringThings",
14679 * "org.freedesktop.StringThings",
14681 * g_variant_new ("(ss)",
14685 * G_DBUS_CALL_FLAGS_NONE,
14688 * (GAsyncReadyCallback) two_strings_done,
14692 * This is an asynchronous method. When the operation is finished,
14693 * @callback will be invoked in the
14694 * [thread-default main context][g-main-context-push-thread-default]
14695 * of the thread you are calling this method from. You can then call
14696 * g_dbus_connection_call_finish() to get the result of the operation.
14697 * See g_dbus_connection_call_sync() for the synchronous version of this
14700 * If @callback is %NULL then the D-Bus method call message will be sent with
14701 * the %G_DBUS_MESSAGE_FLAGS_NO_REPLY_EXPECTED flag set.
14708 * g_dbus_connection_call_finish:
14709 * @connection: a #GDBusConnection
14710 * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_call()
14711 * @error: return location for error or %NULL
14713 * Finishes an operation started with g_dbus_connection_call().
14715 * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
14716 * return values. Free with g_variant_unref().
14722 * g_dbus_connection_call_sync:
14723 * @connection: a #GDBusConnection
14724 * @bus_name: (allow-none): a unique or well-known bus name or %NULL if
14725 * @connection is not a message bus connection
14726 * @object_path: path of remote object
14727 * @interface_name: D-Bus interface to invoke method on
14728 * @method_name: the name of the method to invoke
14729 * @parameters: (allow-none): a #GVariant tuple with parameters for the method
14730 * or %NULL if not passing parameters
14731 * @reply_type: (allow-none): the expected type of the reply, or %NULL
14732 * @flags: flags from the #GDBusCallFlags enumeration
14733 * @timeout_msec: the timeout in milliseconds, -1 to use the default
14734 * timeout or %G_MAXINT for no timeout
14735 * @cancellable: (allow-none): a #GCancellable or %NULL
14736 * @error: return location for error or %NULL
14738 * Synchronously invokes the @method_name method on the
14739 * @interface_name D-Bus interface on the remote object at
14740 * @object_path owned by @bus_name.
14742 * If @connection is closed then the operation will fail with
14743 * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the
14744 * operation will fail with %G_IO_ERROR_CANCELLED. If @parameters
14745 * contains a value not compatible with the D-Bus protocol, the operation
14746 * fails with %G_IO_ERROR_INVALID_ARGUMENT.
14748 * If @reply_type is non-%NULL then the reply will be checked for having
14749 * this type and an error will be raised if it does not match. Said
14750 * another way, if you give a @reply_type then any non-%NULL return
14751 * value will be of this type.
14753 * If the @parameters #GVariant is floating, it is consumed.
14754 * This allows convenient 'inline' use of g_variant_new(), e.g.:
14755 * |[<!-- language="C" -->
14756 * g_dbus_connection_call_sync (connection,
14757 * "org.freedesktop.StringThings",
14758 * "/org/freedesktop/StringThings",
14759 * "org.freedesktop.StringThings",
14761 * g_variant_new ("(ss)",
14765 * G_DBUS_CALL_FLAGS_NONE,
14771 * The calling thread is blocked until a reply is received. See
14772 * g_dbus_connection_call() for the asynchronous version of
14775 * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
14776 * return values. Free with g_variant_unref().
14782 * g_dbus_connection_call_with_unix_fd_list:
14783 * @connection: a #GDBusConnection
14784 * @bus_name: (allow-none): a unique or well-known bus name or %NULL if
14785 * @connection is not a message bus connection
14786 * @object_path: path of remote object
14787 * @interface_name: D-Bus interface to invoke method on
14788 * @method_name: the name of the method to invoke
14789 * @parameters: (allow-none): a #GVariant tuple with parameters for the method
14790 * or %NULL if not passing parameters
14791 * @reply_type: (allow-none): the expected type of the reply, or %NULL
14792 * @flags: flags from the #GDBusCallFlags enumeration
14793 * @timeout_msec: the timeout in milliseconds, -1 to use the default
14794 * timeout or %G_MAXINT for no timeout
14795 * @fd_list: (allow-none): a #GUnixFDList or %NULL
14796 * @cancellable: (allow-none): a #GCancellable or %NULL
14797 * @callback: (allow-none): a #GAsyncReadyCallback to call when the request is
14798 * satisfied or %NULL if you don't * care about the result of the
14799 * method invocation
14800 * @user_data: The data to pass to @callback.
14802 * Like g_dbus_connection_call() but also takes a #GUnixFDList object.
14804 * This method is only available on UNIX.
14811 * g_dbus_connection_call_with_unix_fd_list_finish:
14812 * @connection: a #GDBusConnection
14813 * @out_fd_list: (out) (allow-none): return location for a #GUnixFDList or %NULL
14814 * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed to
14815 * g_dbus_connection_call_with_unix_fd_list()
14816 * @error: return location for error or %NULL
14818 * Finishes an operation started with g_dbus_connection_call_with_unix_fd_list().
14820 * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
14821 * return values. Free with g_variant_unref().
14827 * g_dbus_connection_call_with_unix_fd_list_sync:
14828 * @connection: a #GDBusConnection
14829 * @bus_name: (allow-none): a unique or well-known bus name or %NULL
14830 * if @connection is not a message bus connection
14831 * @object_path: path of remote object
14832 * @interface_name: D-Bus interface to invoke method on
14833 * @method_name: the name of the method to invoke
14834 * @parameters: (allow-none): a #GVariant tuple with parameters for
14835 * the method or %NULL if not passing parameters
14836 * @reply_type: (allow-none): the expected type of the reply, or %NULL
14837 * @flags: flags from the #GDBusCallFlags enumeration
14838 * @timeout_msec: the timeout in milliseconds, -1 to use the default
14839 * timeout or %G_MAXINT for no timeout
14840 * @fd_list: (allow-none): a #GUnixFDList or %NULL
14841 * @out_fd_list: (out) (allow-none): return location for a #GUnixFDList or %NULL
14842 * @cancellable: (allow-none): a #GCancellable or %NULL
14843 * @error: return location for error or %NULL
14845 * Like g_dbus_connection_call_sync() but also takes and returns #GUnixFDList objects.
14847 * This method is only available on UNIX.
14849 * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
14850 * return values. Free with g_variant_unref().
14856 * g_dbus_connection_close:
14857 * @connection: a #GDBusConnection
14858 * @cancellable: (allow-none): a #GCancellable or %NULL
14859 * @callback: (allow-none): a #GAsyncReadyCallback to call when the request is
14860 * satisfied or %NULL if you don't care about the result
14861 * @user_data: The data to pass to @callback
14863 * Closes @connection. Note that this never causes the process to
14864 * exit (this might only happen if the other end of a shared message
14865 * bus connection disconnects, see #GDBusConnection:exit-on-close).
14867 * Once the connection is closed, operations such as sending a message
14868 * will return with the error %G_IO_ERROR_CLOSED. Closing a connection
14869 * will not automatically flush the connection so queued messages may
14870 * be lost. Use g_dbus_connection_flush() if you need such guarantees.
14872 * If @connection is already closed, this method fails with
14873 * %G_IO_ERROR_CLOSED.
14875 * When @connection has been closed, the #GDBusConnection::closed
14876 * signal is emitted in the
14877 * [thread-default main context][g-main-context-push-thread-default]
14878 * of the thread that @connection was constructed in.
14880 * This is an asynchronous method. When the operation is finished,
14881 * @callback will be invoked in the
14882 * [thread-default main context][g-main-context-push-thread-default]
14883 * of the thread you are calling this method from. You can
14884 * then call g_dbus_connection_close_finish() to get the result of the
14885 * operation. See g_dbus_connection_close_sync() for the synchronous
14893 * g_dbus_connection_close_finish:
14894 * @connection: a #GDBusConnection
14895 * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed
14896 * to g_dbus_connection_close()
14897 * @error: return location for error or %NULL
14899 * Finishes an operation started with g_dbus_connection_close().
14901 * Returns: %TRUE if the operation succeeded, %FALSE if @error is set
14907 * g_dbus_connection_close_sync:
14908 * @connection: a #GDBusConnection
14909 * @cancellable: (allow-none): a #GCancellable or %NULL
14910 * @error: return location for error or %NULL
14912 * Synchronously closees @connection. The calling thread is blocked
14913 * until this is done. See g_dbus_connection_close() for the
14914 * asynchronous version of this method and more details about what it
14917 * Returns: %TRUE if the operation succeeded, %FALSE if @error is set
14923 * g_dbus_connection_emit_signal:
14924 * @connection: a #GDBusConnection
14925 * @destination_bus_name: (allow-none): the unique bus name for the destination
14926 * for the signal or %NULL to emit to all listeners
14927 * @object_path: path of remote object
14928 * @interface_name: D-Bus interface to emit a signal on
14929 * @signal_name: the name of the signal to emit
14930 * @parameters: (allow-none): a #GVariant tuple with parameters for the signal
14931 * or %NULL if not passing parameters
14932 * @error: Return location for error or %NULL
14936 * If the parameters GVariant is floating, it is consumed.
14938 * This can only fail if @parameters is not compatible with the D-Bus protocol.
14940 * Returns: %TRUE unless @error is set
14946 * g_dbus_connection_export_action_group:
14947 * @connection: a #GDBusConnection
14948 * @object_path: a D-Bus object path
14949 * @action_group: a #GActionGroup
14950 * @error: a pointer to a %NULL #GError, or %NULL
14952 * Exports @action_group on @connection at @object_path.
14954 * The implemented D-Bus API should be considered private. It is
14955 * subject to change in the future.
14957 * A given object path can only have one action group exported on it.
14958 * If this constraint is violated, the export will fail and 0 will be
14959 * returned (with @error set accordingly).
14961 * You can unexport the action group using
14962 * g_dbus_connection_unexport_action_group() with the return value of
14965 * The thread default main context is taken at the time of this call.
14966 * All incoming action activations and state change requests are
14967 * reported from this context. Any changes on the action group that
14968 * cause it to emit signals must also come from this same context.
14969 * Since incoming action activations and state change requests are
14970 * rather likely to cause changes on the action group, this effectively
14971 * limits a given action group to being exported from only one main
14974 * Returns: the ID of the export (never zero), or 0 in case of failure
14980 * g_dbus_connection_export_menu_model:
14981 * @connection: a #GDBusConnection
14982 * @object_path: a D-Bus object path
14983 * @menu: a #GMenuModel
14984 * @error: return location for an error, or %NULL
14986 * Exports @menu on @connection at @object_path.
14988 * The implemented D-Bus API should be considered private.
14989 * It is subject to change in the future.
14991 * An object path can only have one menu model exported on it. If this
14992 * constraint is violated, the export will fail and 0 will be
14993 * returned (with @error set accordingly).
14995 * You can unexport the menu model using
14996 * g_dbus_connection_unexport_menu_model() with the return value of
14999 * Returns: the ID of the export (never zero), or 0 in case of failure
15005 * g_dbus_connection_flush:
15006 * @connection: a #GDBusConnection
15007 * @cancellable: (allow-none): a #GCancellable or %NULL
15008 * @callback: (allow-none): a #GAsyncReadyCallback to call when the
15009 * request is satisfied or %NULL if you don't care about the result
15010 * @user_data: The data to pass to @callback
15012 * Asynchronously flushes @connection, that is, writes all queued
15013 * outgoing message to the transport and then flushes the transport
15014 * (using g_output_stream_flush_async()). This is useful in programs
15015 * that wants to emit a D-Bus signal and then exit immediately. Without
15016 * flushing the connection, there is no guaranteed that the message has
15017 * been sent to the networking buffers in the OS kernel.
15019 * This is an asynchronous method. When the operation is finished,
15020 * @callback will be invoked in the
15021 * [thread-default main context][g-main-context-push-thread-default]
15022 * of the thread you are calling this method from. You can
15023 * then call g_dbus_connection_flush_finish() to get the result of the
15024 * operation. See g_dbus_connection_flush_sync() for the synchronous
15032 * g_dbus_connection_flush_finish:
15033 * @connection: a #GDBusConnection
15034 * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed
15035 * to g_dbus_connection_flush()
15036 * @error: return location for error or %NULL
15038 * Finishes an operation started with g_dbus_connection_flush().
15040 * Returns: %TRUE if the operation succeeded, %FALSE if @error is set
15046 * g_dbus_connection_flush_sync:
15047 * @connection: a #GDBusConnection
15048 * @cancellable: (allow-none): a #GCancellable or %NULL
15049 * @error: return location for error or %NULL
15051 * Synchronously flushes @connection. The calling thread is blocked
15052 * until this is done. See g_dbus_connection_flush() for the
15053 * asynchronous version of this method and more details about what it
15056 * Returns: %TRUE if the operation succeeded, %FALSE if @error is set
15062 * g_dbus_connection_get_capabilities:
15063 * @connection: a #GDBusConnection
15065 * Gets the capabilities negotiated with the remote peer
15067 * Returns: zero or more flags from the #GDBusCapabilityFlags enumeration
15073 * g_dbus_connection_get_exit_on_close:
15074 * @connection: a #GDBusConnection
15076 * Gets whether the process is terminated when @connection is
15077 * closed by the remote peer. See
15078 * #GDBusConnection:exit-on-close for more details.
15080 * Returns: whether the process is terminated when @connection is
15081 * closed by the remote peer
15087 * g_dbus_connection_get_guid:
15088 * @connection: a #GDBusConnection
15090 * The GUID of the peer performing the role of server when
15091 * authenticating. See #GDBusConnection:guid for more details.
15093 * Returns: The GUID. Do not free this string, it is owned by
15100 * g_dbus_connection_get_last_serial:
15101 * @connection: a #GDBusConnection
15103 * Retrieves the last serial number assigned to a #GDBusMessage on
15104 * the current thread. This includes messages sent via both low-level
15105 * API such as g_dbus_connection_send_message() as well as
15106 * high-level API such as g_dbus_connection_emit_signal(),
15107 * g_dbus_connection_call() or g_dbus_proxy_call().
15109 * Returns: the last used serial or zero when no message has been sent
15110 * within the current thread
15116 * g_dbus_connection_get_peer_credentials:
15117 * @connection: a #GDBusConnection
15119 * Gets the credentials of the authenticated peer. This will always
15120 * return %NULL unless @connection acted as a server
15121 * (e.g. %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER was passed)
15122 * when set up and the client passed credentials as part of the
15123 * authentication process.
15125 * In a message bus setup, the message bus is always the server and
15126 * each application is a client. So this method will always return
15127 * %NULL for message bus clients.
15129 * Returns: (transfer none): a #GCredentials or %NULL if not available.
15130 * Do not free this object, it is owned by @connection.
15136 * g_dbus_connection_get_stream:
15137 * @connection: a #GDBusConnection
15139 * Gets the underlying stream used for IO.
15141 * While the #GDBusConnection is active, it will interact with this
15142 * stream from a worker thread, so it is not safe to interact with
15143 * the stream directly.
15145 * Returns: (transfer none): the stream used for IO
15151 * g_dbus_connection_get_unique_name:
15152 * @connection: a #GDBusConnection
15154 * Gets the unique name of @connection as assigned by the message
15155 * bus. This can also be used to figure out if @connection is a
15156 * message bus connection.
15158 * Returns: the unique name or %NULL if @connection is not a message
15159 * bus connection. Do not free this string, it is owned by
15166 * g_dbus_connection_is_closed:
15167 * @connection: a #GDBusConnection
15169 * Gets whether @connection is closed.
15171 * Returns: %TRUE if the connection is closed, %FALSE otherwise
15177 * g_dbus_connection_new:
15178 * @stream: a #GIOStream
15179 * @guid: (allow-none): the GUID to use if a authenticating as a server or %NULL
15180 * @flags: flags describing how to make the connection
15181 * @observer: (allow-none): a #GDBusAuthObserver or %NULL
15182 * @cancellable: (allow-none): a #GCancellable or %NULL
15183 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
15184 * @user_data: the data to pass to @callback
15186 * Asynchronously sets up a D-Bus connection for exchanging D-Bus messages
15187 * with the end represented by @stream.
15189 * If @stream is a #GSocketConnection, then the corresponding #GSocket
15190 * will be put into non-blocking mode.
15192 * The D-Bus connection will interact with @stream from a worker thread.
15193 * As a result, the caller should not interact with @stream after this
15194 * method has been called, except by calling g_object_unref() on it.
15196 * If @observer is not %NULL it may be used to control the
15197 * authentication process.
15199 * When the operation is finished, @callback will be invoked. You can
15200 * then call g_dbus_connection_new_finish() to get the result of the
15203 * This is a asynchronous failable constructor. See
15204 * g_dbus_connection_new_sync() for the synchronous
15212 * g_dbus_connection_new_finish:
15213 * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback
15214 * passed to g_dbus_connection_new().
15215 * @error: return location for error or %NULL
15217 * Finishes an operation started with g_dbus_connection_new().
15219 * Returns: a #GDBusConnection or %NULL if @error is set. Free
15220 * with g_object_unref().
15226 * g_dbus_connection_new_for_address:
15227 * @address: a D-Bus address
15228 * @flags: flags describing how to make the connection
15229 * @observer: (allow-none): a #GDBusAuthObserver or %NULL
15230 * @cancellable: (allow-none): a #GCancellable or %NULL
15231 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
15232 * @user_data: the data to pass to @callback
15234 * Asynchronously connects and sets up a D-Bus client connection for
15235 * exchanging D-Bus messages with an endpoint specified by @address
15236 * which must be in the D-Bus address format.
15238 * This constructor can only be used to initiate client-side
15239 * connections - use g_dbus_connection_new() if you need to act as the
15240 * server. In particular, @flags cannot contain the
15241 * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER or
15242 * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS flags.
15244 * When the operation is finished, @callback will be invoked. You can
15245 * then call g_dbus_connection_new_finish() to get the result of the
15248 * If @observer is not %NULL it may be used to control the
15249 * authentication process.
15251 * This is a asynchronous failable constructor. See
15252 * g_dbus_connection_new_for_address_sync() for the synchronous
15260 * g_dbus_connection_new_for_address_finish:
15261 * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed
15262 * to g_dbus_connection_new()
15263 * @error: return location for error or %NULL
15265 * Finishes an operation started with g_dbus_connection_new_for_address().
15267 * Returns: a #GDBusConnection or %NULL if @error is set. Free with
15268 * g_object_unref().
15274 * g_dbus_connection_new_for_address_sync:
15275 * @address: a D-Bus address
15276 * @flags: flags describing how to make the connection
15277 * @observer: (allow-none): a #GDBusAuthObserver or %NULL
15278 * @cancellable: (allow-none): a #GCancellable or %NULL
15279 * @error: return location for error or %NULL
15281 * Synchronously connects and sets up a D-Bus client connection for
15282 * exchanging D-Bus messages with an endpoint specified by @address
15283 * which must be in the D-Bus address format.
15285 * This constructor can only be used to initiate client-side
15286 * connections - use g_dbus_connection_new_sync() if you need to act
15287 * as the server. In particular, @flags cannot contain the
15288 * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER or
15289 * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS flags.
15291 * This is a synchronous failable constructor. See
15292 * g_dbus_connection_new_for_address() for the asynchronous version.
15294 * If @observer is not %NULL it may be used to control the
15295 * authentication process.
15297 * Returns: a #GDBusConnection or %NULL if @error is set. Free with
15298 * g_object_unref().
15304 * g_dbus_connection_new_sync:
15305 * @stream: a #GIOStream
15306 * @guid: (allow-none): the GUID to use if a authenticating as a server or %NULL
15307 * @flags: flags describing how to make the connection
15308 * @observer: (allow-none): a #GDBusAuthObserver or %NULL
15309 * @cancellable: (allow-none): a #GCancellable or %NULL
15310 * @error: return location for error or %NULL
15312 * Synchronously sets up a D-Bus connection for exchanging D-Bus messages
15313 * with the end represented by @stream.
15315 * If @stream is a #GSocketConnection, then the corresponding #GSocket
15316 * will be put into non-blocking mode.
15318 * The D-Bus connection will interact with @stream from a worker thread.
15319 * As a result, the caller should not interact with @stream after this
15320 * method has been called, except by calling g_object_unref() on it.
15322 * If @observer is not %NULL it may be used to control the
15323 * authentication process.
15325 * This is a synchronous failable constructor. See
15326 * g_dbus_connection_new() for the asynchronous version.
15328 * Returns: a #GDBusConnection or %NULL if @error is set. Free with g_object_unref().
15334 * g_dbus_connection_register_object:
15335 * @connection: a #GDBusConnection
15336 * @object_path: the object path to register at
15337 * @interface_info: introspection data for the interface
15338 * @vtable: (allow-none): a #GDBusInterfaceVTable to call into or %NULL
15339 * @user_data: (allow-none): data to pass to functions in @vtable
15340 * @user_data_free_func: function to call when the object path is unregistered
15341 * @error: return location for error or %NULL
15343 * Registers callbacks for exported objects at @object_path with the
15344 * D-Bus interface that is described in @interface_info.
15346 * Calls to functions in @vtable (and @user_data_free_func) will happen
15348 * [thread-default main context][g-main-context-push-thread-default]
15349 * of the thread you are calling this method from.
15351 * Note that all #GVariant values passed to functions in @vtable will match
15352 * the signature given in @interface_info - if a remote caller passes
15353 * incorrect values, the `org.freedesktop.DBus.Error.InvalidArgs`
15354 * is returned to the remote caller.
15356 * Additionally, if the remote caller attempts to invoke methods or
15357 * access properties not mentioned in @interface_info the
15358 * `org.freedesktop.DBus.Error.UnknownMethod` resp.
15359 * `org.freedesktop.DBus.Error.InvalidArgs` errors
15360 * are returned to the caller.
15362 * It is considered a programming error if the
15363 * #GDBusInterfaceGetPropertyFunc function in @vtable returns a
15364 * #GVariant of incorrect type.
15366 * If an existing callback is already registered at @object_path and
15367 * @interface_name, then @error is set to #G_IO_ERROR_EXISTS.
15369 * GDBus automatically implements the standard D-Bus interfaces
15370 * org.freedesktop.DBus.Properties, org.freedesktop.DBus.Introspectable
15371 * and org.freedesktop.Peer, so you don't have to implement those for the
15372 * objects you export. You can implement org.freedesktop.DBus.Properties
15373 * yourself, e.g. to handle getting and setting of properties asynchronously.
15375 * Note that the reference count on @interface_info will be
15376 * incremented by 1 (unless allocated statically, e.g. if the
15377 * reference count is -1, see g_dbus_interface_info_ref()) for as long
15378 * as the object is exported. Also note that @vtable will be copied.
15380 * See this [server][gdbus-server] for an example of how to use this method.
15382 * Returns: 0 if @error is set, otherwise a registration id (never 0)
15383 * that can be used with g_dbus_connection_unregister_object()
15389 * g_dbus_connection_register_subtree:
15390 * @connection: a #GDBusConnection
15391 * @object_path: the object path to register the subtree at
15392 * @vtable: a #GDBusSubtreeVTable to enumerate, introspect and
15393 * dispatch nodes in the subtree
15394 * @flags: flags used to fine tune the behavior of the subtree
15395 * @user_data: data to pass to functions in @vtable
15396 * @user_data_free_func: function to call when the subtree is unregistered
15397 * @error: return location for error or %NULL
15399 * Registers a whole subtree of dynamic objects.
15401 * The @enumerate and @introspection functions in @vtable are used to
15402 * convey, to remote callers, what nodes exist in the subtree rooted
15405 * When handling remote calls into any node in the subtree, first the
15406 * @enumerate function is used to check if the node exists. If the node exists
15407 * or the #G_DBUS_SUBTREE_FLAGS_DISPATCH_TO_UNENUMERATED_NODES flag is set
15408 * the @introspection function is used to check if the node supports the
15409 * requested method. If so, the @dispatch function is used to determine
15410 * where to dispatch the call. The collected #GDBusInterfaceVTable and
15411 * #gpointer will be used to call into the interface vtable for processing
15414 * All calls into user-provided code will be invoked in the
15415 * [thread-default main context][g-main-context-push-thread-default]
15416 * of the thread you are calling this method from.
15418 * If an existing subtree is already registered at @object_path or
15419 * then @error is set to #G_IO_ERROR_EXISTS.
15421 * Note that it is valid to register regular objects (using
15422 * g_dbus_connection_register_object()) in a subtree registered with
15423 * g_dbus_connection_register_subtree() - if so, the subtree handler
15424 * is tried as the last resort. One way to think about a subtree
15425 * handler is to consider it a fallback handler for object paths not
15426 * registered via g_dbus_connection_register_object() or other bindings.
15428 * Note that @vtable will be copied so you cannot change it after
15431 * See this [server][gdbus-subtree-server] for an example of how to use
15434 * Returns: 0 if @error is set, otherwise a subtree registration id (never 0)
15435 * that can be used with g_dbus_connection_unregister_subtree() .
15441 * g_dbus_connection_remove_filter:
15442 * @connection: a #GDBusConnection
15443 * @filter_id: an identifier obtained from g_dbus_connection_add_filter()
15445 * Removes a filter.
15452 * g_dbus_connection_send_message:
15453 * @connection: a #GDBusConnection
15454 * @message: a #GDBusMessage
15455 * @flags: flags affecting how the message is sent
15456 * @out_serial: (out) (allow-none): return location for serial number assigned
15457 * to @message when sending it or %NULL
15458 * @error: Return location for error or %NULL
15460 * Asynchronously sends @message to the peer represented by @connection.
15462 * Unless @flags contain the
15463 * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number
15464 * will be assigned by @connection and set on @message via
15465 * g_dbus_message_set_serial(). If @out_serial is not %NULL, then the
15466 * serial number used will be written to this location prior to
15467 * submitting the message to the underlying transport.
15469 * If @connection is closed then the operation will fail with
15470 * %G_IO_ERROR_CLOSED. If @message is not well-formed,
15471 * the operation fails with %G_IO_ERROR_INVALID_ARGUMENT.
15473 * See this [server][gdbus-server] and [client][gdbus-unix-fd-client]
15474 * for an example of how to use this low-level API to send and receive
15475 * UNIX file descriptors.
15477 * Note that @message must be unlocked, unless @flags contain the
15478 * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag.
15480 * Returns: %TRUE if the message was well-formed and queued for
15481 * transmission, %FALSE if @error is set
15487 * g_dbus_connection_send_message_with_reply:
15488 * @connection: a #GDBusConnection
15489 * @message: a #GDBusMessage
15490 * @flags: flags affecting how the message is sent
15491 * @timeout_msec: the timeout in milliseconds, -1 to use the default
15492 * timeout or %G_MAXINT for no timeout
15493 * @out_serial: (out) (allow-none): return location for serial number assigned
15494 * to @message when sending it or %NULL
15495 * @cancellable: (allow-none): a #GCancellable or %NULL
15496 * @callback: (allow-none): a #GAsyncReadyCallback to call when the request
15497 * is satisfied or %NULL if you don't care about the result
15498 * @user_data: The data to pass to @callback
15500 * Asynchronously sends @message to the peer represented by @connection.
15502 * Unless @flags contain the
15503 * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number
15504 * will be assigned by @connection and set on @message via
15505 * g_dbus_message_set_serial(). If @out_serial is not %NULL, then the
15506 * serial number used will be written to this location prior to
15507 * submitting the message to the underlying transport.
15509 * If @connection is closed then the operation will fail with
15510 * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will
15511 * fail with %G_IO_ERROR_CANCELLED. If @message is not well-formed,
15512 * the operation fails with %G_IO_ERROR_INVALID_ARGUMENT.
15514 * This is an asynchronous method. When the operation is finished, @callback
15515 * will be invoked in the
15516 * [thread-default main context][g-main-context-push-thread-default]
15517 * of the thread you are calling this method from. You can then call
15518 * g_dbus_connection_send_message_with_reply_finish() to get the result of the operation.
15519 * See g_dbus_connection_send_message_with_reply_sync() for the synchronous version.
15521 * Note that @message must be unlocked, unless @flags contain the
15522 * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag.
15524 * See this [server][gdbus-server] and [client][gdbus-unix-fd-client]
15525 * for an example of how to use this low-level API to send and receive
15526 * UNIX file descriptors.
15533 * g_dbus_connection_send_message_with_reply_finish:
15534 * @connection: a #GDBusConnection
15535 * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed to
15536 * g_dbus_connection_send_message_with_reply()
15537 * @error: teturn location for error or %NULL
15539 * Finishes an operation started with g_dbus_connection_send_message_with_reply().
15541 * Note that @error is only set if a local in-process error
15542 * occurred. That is to say that the returned #GDBusMessage object may
15543 * be of type %G_DBUS_MESSAGE_TYPE_ERROR. Use
15544 * g_dbus_message_to_gerror() to transcode this to a #GError.
15546 * See this [server][gdbus-server] and [client][gdbus-unix-fd-client]
15547 * for an example of how to use this low-level API to send and receive
15548 * UNIX file descriptors.
15550 * Returns: (transfer full): a locked #GDBusMessage or %NULL if @error is set
15556 * g_dbus_connection_send_message_with_reply_sync:
15557 * @connection: a #GDBusConnection
15558 * @message: a #GDBusMessage
15559 * @flags: flags affecting how the message is sent.
15560 * @timeout_msec: the timeout in milliseconds, -1 to use the default
15561 * timeout or %G_MAXINT for no timeout
15562 * @out_serial: (out) (allow-none): return location for serial number
15563 * assigned to @message when sending it or %NULL
15564 * @cancellable: (allow-none): a #GCancellable or %NULL
15565 * @error: return location for error or %NULL
15567 * Synchronously sends @message to the peer represented by @connection
15568 * and blocks the calling thread until a reply is received or the
15569 * timeout is reached. See g_dbus_connection_send_message_with_reply()
15570 * for the asynchronous version of this method.
15572 * Unless @flags contain the
15573 * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number
15574 * will be assigned by @connection and set on @message via
15575 * g_dbus_message_set_serial(). If @out_serial is not %NULL, then the
15576 * serial number used will be written to this location prior to
15577 * submitting the message to the underlying transport.
15579 * If @connection is closed then the operation will fail with
15580 * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will
15581 * fail with %G_IO_ERROR_CANCELLED. If @message is not well-formed,
15582 * the operation fails with %G_IO_ERROR_INVALID_ARGUMENT.
15584 * Note that @error is only set if a local in-process error
15585 * occurred. That is to say that the returned #GDBusMessage object may
15586 * be of type %G_DBUS_MESSAGE_TYPE_ERROR. Use
15587 * g_dbus_message_to_gerror() to transcode this to a #GError.
15589 * See this [server][gdbus-server] and [client][gdbus-unix-fd-client]
15590 * for an example of how to use this low-level API to send and receive
15591 * UNIX file descriptors.
15593 * Note that @message must be unlocked, unless @flags contain the
15594 * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag.
15596 * Returns: (transfer full): a locked #GDBusMessage that is the reply
15597 * to @message or %NULL if @error is set
15603 * g_dbus_connection_set_exit_on_close:
15604 * @connection: a #GDBusConnection
15605 * @exit_on_close: whether the process should be terminated
15606 * when @connection is closed by the remote peer
15608 * Sets whether the process should be terminated when @connection is
15609 * closed by the remote peer. See #GDBusConnection:exit-on-close for
15612 * Note that this function should be used with care. Most modern UNIX
15613 * desktops tie the notion of a user session the session bus, and expect
15614 * all of a users applications to quit when their bus connection goes away.
15615 * If you are setting @exit_on_close to %FALSE for the shared session
15616 * bus connection, you should make sure that your application exits
15617 * when the user session ends.
15624 * g_dbus_connection_signal_subscribe:
15625 * @connection: a #GDBusConnection
15626 * @sender: (allow-none): sender name to match on (unique or well-known name)
15627 * or %NULL to listen from all senders
15628 * @interface_name: (allow-none): D-Bus interface name to match on or %NULL to
15629 * match on all interfaces
15630 * @member: (allow-none): D-Bus signal name to match on or %NULL to match on
15632 * @object_path: (allow-none): object path to match on or %NULL to match on
15634 * @arg0: (allow-none): contents of first string argument to match on or %NULL
15635 * to match on all kinds of arguments
15636 * @flags: flags describing how to subscribe to the signal (currently unused)
15637 * @callback: callback to invoke when there is a signal matching the requested data
15638 * @user_data: user data to pass to @callback
15639 * @user_data_free_func: (allow-none): function to free @user_data with when
15640 * subscription is removed or %NULL
15642 * Subscribes to signals on @connection and invokes @callback with a whenever
15643 * the signal is received. Note that @callback will be invoked in the
15644 * [thread-default main context][g-main-context-push-thread-default]
15645 * of the thread you are calling this method from.
15647 * If @connection is not a message bus connection, @sender must be
15650 * If @sender is a well-known name note that @callback is invoked with
15651 * the unique name for the owner of @sender, not the well-known name
15652 * as one would expect. This is because the message bus rewrites the
15653 * name. As such, to avoid certain race conditions, users should be
15654 * tracking the name owner of the well-known name and use that when
15655 * processing the received signal.
15657 * If one of %G_DBUS_SIGNAL_FLAGS_MATCH_ARG0_NAMESPACE or
15658 * %G_DBUS_SIGNAL_FLAGS_MATCH_ARG0_PATH are given, @arg0 is
15659 * interpreted as part of a namespace or path. The first argument
15660 * of a signal is matched against that part as specified by D-Bus.
15662 * Returns: a subscription identifier that can be used with g_dbus_connection_signal_unsubscribe()
15668 * g_dbus_connection_signal_unsubscribe:
15669 * @connection: a #GDBusConnection
15670 * @subscription_id: a subscription id obtained from
15671 * g_dbus_connection_signal_subscribe()
15673 * Unsubscribes from signals.
15680 * g_dbus_connection_start_message_processing:
15681 * @connection: a #GDBusConnection
15683 * If @connection was created with
15684 * %G_DBUS_CONNECTION_FLAGS_DELAY_MESSAGE_PROCESSING, this method
15685 * starts processing messages. Does nothing on if @connection wasn't
15686 * created with this flag or if the method has already been called.
15693 * g_dbus_connection_unexport_action_group:
15694 * @connection: a #GDBusConnection
15695 * @export_id: the ID from g_dbus_connection_export_action_group()
15697 * Reverses the effect of a previous call to
15698 * g_dbus_connection_export_action_group().
15700 * It is an error to call this function with an ID that wasn't returned
15701 * from g_dbus_connection_export_action_group() or to call it with the
15702 * same ID more than once.
15709 * g_dbus_connection_unexport_menu_model:
15710 * @connection: a #GDBusConnection
15711 * @export_id: the ID from g_dbus_connection_export_menu_model()
15713 * Reverses the effect of a previous call to
15714 * g_dbus_connection_export_menu_model().
15716 * It is an error to call this function with an ID that wasn't returned
15717 * from g_dbus_connection_export_menu_model() or to call it with the
15718 * same ID more than once.
15725 * g_dbus_connection_unregister_object:
15726 * @connection: a #GDBusConnection
15727 * @registration_id: a registration id obtained from
15728 * g_dbus_connection_register_object()
15730 * Unregisters an object.
15732 * Returns: %TRUE if the object was unregistered, %FALSE otherwise
15738 * g_dbus_connection_unregister_subtree:
15739 * @connection: a #GDBusConnection
15740 * @registration_id: a subtree registration id obtained from
15741 * g_dbus_connection_register_subtree()
15743 * Unregisters a subtree.
15745 * Returns: %TRUE if the subtree was unregistered, %FALSE otherwise
15751 * g_dbus_error_encode_gerror:
15752 * @error: A #GError.
15754 * Creates a D-Bus error name to use for @error. If @error matches
15755 * a registered error (cf. g_dbus_error_register_error()), the corresponding
15756 * D-Bus error name will be returned.
15758 * Otherwise the a name of the form
15759 * `org.gtk.GDBus.UnmappedGError.Quark._ESCAPED_QUARK_NAME.Code_ERROR_CODE`
15760 * will be used. This allows other GDBus applications to map the error
15761 * on the wire back to a #GError using g_dbus_error_new_for_dbus_error().
15763 * This function is typically only used in object mappings to put a
15764 * #GError on the wire. Regular applications should not use it.
15766 * Returns: A D-Bus error name (never %NULL). Free with g_free().
15772 * g_dbus_error_get_remote_error:
15773 * @error: a #GError
15775 * Gets the D-Bus error name used for @error, if any.
15777 * This function is guaranteed to return a D-Bus error name for all
15778 * #GErrors returned from functions handling remote method calls
15779 * (e.g. g_dbus_connection_call_finish()) unless
15780 * g_dbus_error_strip_remote_error() has been used on @error.
15782 * Returns: an allocated string or %NULL if the D-Bus error name
15783 * could not be found. Free with g_free().
15789 * g_dbus_error_is_remote_error:
15790 * @error: A #GError.
15792 * Checks if @error represents an error received via D-Bus from a remote peer. If so,
15793 * use g_dbus_error_get_remote_error() to get the name of the error.
15795 * Returns: %TRUE if @error represents an error from a remote peer,
15796 * %FALSE otherwise.
15802 * g_dbus_error_new_for_dbus_error:
15803 * @dbus_error_name: D-Bus error name.
15804 * @dbus_error_message: D-Bus error message.
15806 * Creates a #GError based on the contents of @dbus_error_name and
15807 * @dbus_error_message.
15809 * Errors registered with g_dbus_error_register_error() will be looked
15810 * up using @dbus_error_name and if a match is found, the error domain
15811 * and code is used. Applications can use g_dbus_error_get_remote_error()
15812 * to recover @dbus_error_name.
15814 * If a match against a registered error is not found and the D-Bus
15815 * error name is in a form as returned by g_dbus_error_encode_gerror()
15816 * the error domain and code encoded in the name is used to
15817 * create the #GError. Also, @dbus_error_name is added to the error message
15818 * such that it can be recovered with g_dbus_error_get_remote_error().
15820 * Otherwise, a #GError with the error code %G_IO_ERROR_DBUS_ERROR
15821 * in the #G_IO_ERROR error domain is returned. Also, @dbus_error_name is
15822 * added to the error message such that it can be recovered with
15823 * g_dbus_error_get_remote_error().
15825 * In all three cases, @dbus_error_name can always be recovered from the
15826 * returned #GError using the g_dbus_error_get_remote_error() function
15827 * (unless g_dbus_error_strip_remote_error() hasn't been used on the returned error).
15829 * This function is typically only used in object mappings to prepare
15830 * #GError instances for applications. Regular applications should not use
15833 * Returns: An allocated #GError. Free with g_error_free().
15839 * g_dbus_error_register_error:
15840 * @error_domain: A #GQuark for a error domain.
15841 * @error_code: An error code.
15842 * @dbus_error_name: A D-Bus error name.
15844 * Creates an association to map between @dbus_error_name and
15845 * #GErrors specified by @error_domain and @error_code.
15847 * This is typically done in the routine that returns the #GQuark for
15850 * Returns: %TRUE if the association was created, %FALSE if it already
15857 * g_dbus_error_register_error_domain:
15858 * @error_domain_quark_name: The error domain name.
15859 * @quark_volatile: A pointer where to store the #GQuark.
15860 * @entries: A pointer to @num_entries #GDBusErrorEntry struct items.
15861 * @num_entries: Number of items to register.
15863 * Helper function for associating a #GError error domain with D-Bus error names.
15870 * g_dbus_error_set_dbus_error:
15871 * @error: A pointer to a #GError or %NULL.
15872 * @dbus_error_name: D-Bus error name.
15873 * @dbus_error_message: D-Bus error message.
15874 * @format: (allow-none): printf()-style format to prepend to @dbus_error_message or %NULL.
15875 * @...: Arguments for @format.
15877 * Does nothing if @error is %NULL. Otherwise sets *@error to
15878 * a new #GError created with g_dbus_error_new_for_dbus_error()
15879 * with @dbus_error_message prepend with @format (unless %NULL).
15886 * g_dbus_error_set_dbus_error_valist:
15887 * @error: A pointer to a #GError or %NULL.
15888 * @dbus_error_name: D-Bus error name.
15889 * @dbus_error_message: D-Bus error message.
15890 * @format: (allow-none): printf()-style format to prepend to @dbus_error_message or %NULL.
15891 * @var_args: Arguments for @format.
15893 * Like g_dbus_error_set_dbus_error() but intended for language bindings.
15900 * g_dbus_error_strip_remote_error:
15901 * @error: A #GError.
15903 * Looks for extra information in the error message used to recover
15904 * the D-Bus error name and strips it if found. If stripped, the
15905 * message field in @error will correspond exactly to what was
15906 * received on the wire.
15908 * This is typically used when presenting errors to the end user.
15910 * Returns: %TRUE if information was stripped, %FALSE otherwise.
15916 * g_dbus_error_unregister_error:
15917 * @error_domain: A #GQuark for a error domain.
15918 * @error_code: An error code.
15919 * @dbus_error_name: A D-Bus error name.
15921 * Destroys an association previously set up with g_dbus_error_register_error().
15923 * Returns: %TRUE if the association was destroyed, %FALSE if it wasn't found.
15929 * g_dbus_generate_guid:
15931 * Generate a D-Bus GUID that can be used with
15932 * e.g. g_dbus_connection_new().
15934 * See the D-Bus specification regarding what strings are valid D-Bus
15935 * GUID (for example, D-Bus GUIDs are not RFC-4122 compliant).
15937 * Returns: A valid D-Bus GUID. Free with g_free().
15943 * g_dbus_gvalue_to_gvariant:
15944 * @gvalue: A #GValue to convert to a #GVariant
15945 * @type: A #GVariantType
15947 * Converts a #GValue to a #GVariant of the type indicated by the @type
15950 * The conversion is using the following rules:
15952 * - #G_TYPE_STRING: 's', 'o', 'g' or 'ay'
15953 * - #G_TYPE_STRV: 'as', 'ao' or 'aay'
15954 * - #G_TYPE_BOOLEAN: 'b'
15955 * - #G_TYPE_UCHAR: 'y'
15956 * - #G_TYPE_INT: 'i', 'n'
15957 * - #G_TYPE_UINT: 'u', 'q'
15958 * - #G_TYPE_INT64 'x'
15959 * - #G_TYPE_UINT64: 't'
15960 * - #G_TYPE_DOUBLE: 'd'
15961 * - #G_TYPE_VARIANT: Any #GVariantType
15963 * This can fail if e.g. @gvalue is of type #G_TYPE_STRING and @type
15964 * is ['i'][G-VARIANT-TYPE-INT32:CAPS]. It will also fail for any #GType
15965 * (including e.g. #G_TYPE_OBJECT and #G_TYPE_BOXED derived-types) not
15966 * in the table above.
15968 * Note that if @gvalue is of type #G_TYPE_VARIANT and its value is
15969 * %NULL, the empty #GVariant instance (never %NULL) for @type is
15970 * returned (e.g. 0 for scalar types, the empty string for string types,
15971 * '/' for object path types, the empty array for any array type and so on).
15973 * See the g_dbus_gvariant_to_gvalue() function for how to convert a
15974 * #GVariant to a #GValue.
15976 * Returns: A #GVariant (never floating) of #GVariantType @type holding
15977 * the data from @gvalue or %NULL in case of failure. Free with
15978 * g_variant_unref().
15984 * g_dbus_gvariant_to_gvalue:
15985 * @value: A #GVariant.
15986 * @out_gvalue: (out): Return location pointing to a zero-filled (uninitialized) #GValue.
15988 * Converts a #GVariant to a #GValue. If @value is floating, it is consumed.
15990 * The rules specified in the g_dbus_gvalue_to_gvariant() function are
15991 * used - this function is essentially its reverse form.
15993 * The conversion never fails - a valid #GValue is always returned in
16001 * g_dbus_interface_dup_object: (rename-to g_dbus_interface_get_object)
16002 * @interface_: An exported D-Bus interface.
16004 * Gets the #GDBusObject that @interface_ belongs to, if any.
16006 * Returns: (transfer full): A #GDBusObject or %NULL. The returned
16007 * reference should be freed with g_object_unref().
16013 * g_dbus_interface_get_info:
16014 * @interface_: An exported D-Bus interface.
16016 * Gets D-Bus introspection information for the D-Bus interface
16017 * implemented by @interface_.
16019 * Returns: (transfer none): A #GDBusInterfaceInfo. Do not free.
16025 * g_dbus_interface_get_object: (skip)
16026 * @interface_: An exported D-Bus interface
16028 * Gets the #GDBusObject that @interface_ belongs to, if any.
16030 * It is not safe to use the returned object if @interface_ or
16031 * the returned object is being used from other threads. See
16032 * g_dbus_interface_dup_object() for a thread-safe alternative.
16034 * Returns: (transfer none): A #GDBusObject or %NULL. The returned
16035 * reference belongs to @interface_ and should not be freed.
16041 * g_dbus_interface_info_cache_build:
16042 * @info: A #GDBusInterfaceInfo.
16044 * Builds a lookup-cache to speed up
16045 * g_dbus_interface_info_lookup_method(),
16046 * g_dbus_interface_info_lookup_signal() and
16047 * g_dbus_interface_info_lookup_property().
16049 * If this has already been called with @info, the existing cache is
16050 * used and its use count is increased.
16052 * Note that @info cannot be modified until
16053 * g_dbus_interface_info_cache_release() is called.
16060 * g_dbus_interface_info_cache_release:
16061 * @info: A GDBusInterfaceInfo
16063 * Decrements the usage count for the cache for @info built by
16064 * g_dbus_interface_info_cache_build() (if any) and frees the
16065 * resources used by the cache if the usage count drops to zero.
16072 * g_dbus_interface_info_generate_xml:
16073 * @info: A #GDBusNodeInfo
16074 * @indent: Indentation level.
16075 * @string_builder: (out): A #GString to to append XML data to.
16077 * Appends an XML representation of @info (and its children) to @string_builder.
16079 * This function is typically used for generating introspection XML
16080 * documents at run-time for handling the
16081 * `org.freedesktop.DBus.Introspectable.Introspect`
16089 * g_dbus_interface_info_lookup_method:
16090 * @info: A #GDBusInterfaceInfo.
16091 * @name: A D-Bus method name (typically in CamelCase)
16093 * Looks up information about a method.
16095 * The cost of this function is O(n) in number of methods unless
16096 * g_dbus_interface_info_cache_build() has been used on @info.
16098 * Returns: (transfer none): A #GDBusMethodInfo or %NULL if not found. Do not free, it is owned by @info.
16104 * g_dbus_interface_info_lookup_property:
16105 * @info: A #GDBusInterfaceInfo.
16106 * @name: A D-Bus property name (typically in CamelCase).
16108 * Looks up information about a property.
16110 * The cost of this function is O(n) in number of properties unless
16111 * g_dbus_interface_info_cache_build() has been used on @info.
16113 * Returns: (transfer none): A #GDBusPropertyInfo or %NULL if not found. Do not free, it is owned by @info.
16119 * g_dbus_interface_info_lookup_signal:
16120 * @info: A #GDBusInterfaceInfo.
16121 * @name: A D-Bus signal name (typically in CamelCase)
16123 * Looks up information about a signal.
16125 * The cost of this function is O(n) in number of signals unless
16126 * g_dbus_interface_info_cache_build() has been used on @info.
16128 * Returns: (transfer none): A #GDBusSignalInfo or %NULL if not found. Do not free, it is owned by @info.
16134 * g_dbus_interface_info_ref:
16135 * @info: A #GDBusInterfaceInfo
16137 * If @info is statically allocated does nothing. Otherwise increases
16138 * the reference count.
16140 * Returns: The same @info.
16146 * g_dbus_interface_info_unref:
16147 * @info: A #GDBusInterfaceInfo.
16149 * If @info is statically allocated, does nothing. Otherwise decreases
16150 * the reference count of @info. When its reference count drops to 0,
16151 * the memory used is freed.
16158 * g_dbus_interface_set_object:
16159 * @interface_: An exported D-Bus interface.
16160 * @object: (allow-none): A #GDBusObject or %NULL.
16162 * Sets the #GDBusObject for @interface_ to @object.
16164 * Note that @interface_ will hold a weak reference to @object.
16171 * g_dbus_interface_skeleton_export:
16172 * @interface_: The D-Bus interface to export.
16173 * @connection: A #GDBusConnection to export @interface_ on.
16174 * @object_path: The path to export the interface at.
16175 * @error: Return location for error or %NULL.
16177 * Exports @interface_ at @object_path on @connection.
16179 * This can be called multiple times to export the same @interface_
16180 * onto multiple connections however the @object_path provided must be
16181 * the same for all connections.
16183 * Use g_dbus_interface_skeleton_unexport() to unexport the object.
16185 * Returns: %TRUE if the interface was exported on @connection, otherwise %FALSE with
16192 * g_dbus_interface_skeleton_flush:
16193 * @interface_: A #GDBusInterfaceSkeleton.
16195 * If @interface_ has outstanding changes, request for these changes to be
16196 * emitted immediately.
16198 * For example, an exported D-Bus interface may queue up property
16199 * changes and emit the
16200 * `org.freedesktop.DBus.Properties::Propert``
16201 * signal later (e.g. in an idle handler). This technique is useful
16202 * for collapsing multiple property changes into one.
16209 * g_dbus_interface_skeleton_get_connection:
16210 * @interface_: A #GDBusInterfaceSkeleton.
16212 * Gets the first connection that @interface_ is exported on, if any.
16214 * Returns: (transfer none): A #GDBusConnection or %NULL if @interface_ is
16215 * not exported anywhere. Do not free, the object belongs to @interface_.
16221 * g_dbus_interface_skeleton_get_connections:
16222 * @interface_: A #GDBusInterfaceSkeleton.
16224 * Gets a list of the connections that @interface_ is exported on.
16226 * Returns: (element-type GDBusConnection) (transfer full): A list of
16227 * all the connections that @interface_ is exported on. The returned
16228 * list should be freed with g_list_free() after each element has
16229 * been freed with g_object_unref().
16235 * g_dbus_interface_skeleton_get_flags:
16236 * @interface_: A #GDBusInterfaceSkeleton.
16238 * Gets the #GDBusInterfaceSkeletonFlags that describes what the behavior
16241 * Returns: One or more flags from the #GDBusInterfaceSkeletonFlags enumeration.
16247 * g_dbus_interface_skeleton_get_info:
16248 * @interface_: A #GDBusInterfaceSkeleton.
16250 * Gets D-Bus introspection information for the D-Bus interface
16251 * implemented by @interface_.
16253 * Returns: (transfer none): A #GDBusInterfaceInfo (never %NULL). Do not free.
16259 * g_dbus_interface_skeleton_get_object_path:
16260 * @interface_: A #GDBusInterfaceSkeleton.
16262 * Gets the object path that @interface_ is exported on, if any.
16264 * Returns: A string owned by @interface_ or %NULL if @interface_ is not exported
16265 * anywhere. Do not free, the string belongs to @interface_.
16271 * g_dbus_interface_skeleton_get_properties:
16272 * @interface_: A #GDBusInterfaceSkeleton.
16274 * Gets all D-Bus properties for @interface_.
16276 * Returns: (transfer full): A #GVariant of type
16277 * ['a{sv}'][G-VARIANT-TYPE-VARDICT:CAPS].
16278 * Free with g_variant_unref().
16284 * g_dbus_interface_skeleton_get_vtable: (skip)
16285 * @interface_: A #GDBusInterfaceSkeleton.
16287 * Gets the interface vtable for the D-Bus interface implemented by
16288 * @interface_. The returned function pointers should expect @interface_
16289 * itself to be passed as @user_data.
16291 * Returns: A #GDBusInterfaceVTable (never %NULL).
16297 * g_dbus_interface_skeleton_has_connection:
16298 * @interface_: A #GDBusInterfaceSkeleton.
16299 * @connection: A #GDBusConnection.
16301 * Checks if @interface_ is exported on @connection.
16303 * Returns: %TRUE if @interface_ is exported on @connection, %FALSE otherwise.
16309 * g_dbus_interface_skeleton_set_flags:
16310 * @interface_: A #GDBusInterfaceSkeleton.
16311 * @flags: Flags from the #GDBusInterfaceSkeletonFlags enumeration.
16313 * Sets flags describing what the behavior of @skeleton should be.
16320 * g_dbus_interface_skeleton_unexport:
16321 * @interface_: A #GDBusInterfaceSkeleton.
16323 * Stops exporting @interface_ on all connections it is exported on.
16325 * To unexport @interface_ from only a single connection, use
16326 * g_dbus_interface_skeleton_unexport_from_connection()
16333 * g_dbus_interface_skeleton_unexport_from_connection:
16334 * @interface_: A #GDBusInterfaceSkeleton.
16335 * @connection: A #GDBusConnection.
16337 * Stops exporting @interface_ on @connection.
16339 * To stop exporting on all connections the interface is exported on,
16340 * use g_dbus_interface_skeleton_unexport().
16347 * g_dbus_is_address:
16348 * @string: A string.
16350 * Checks if @string is a D-Bus address.
16352 * This doesn't check if @string is actually supported by #GDBusServer
16353 * or #GDBusConnection - use g_dbus_is_supported_address() to do more
16356 * Returns: %TRUE if @string is a valid D-Bus address, %FALSE otherwise.
16363 * @string: The string to check.
16365 * Checks if @string is a D-Bus GUID.
16367 * See the D-Bus specification regarding what strings are valid D-Bus
16368 * GUID (for example, D-Bus GUIDs are not RFC-4122 compliant).
16370 * Returns: %TRUE if @string is a guid, %FALSE otherwise.
16376 * g_dbus_is_interface_name:
16377 * @string: The string to check.
16379 * Checks if @string is a valid D-Bus interface name.
16381 * Returns: %TRUE if valid, %FALSE otherwise.
16387 * g_dbus_is_member_name:
16388 * @string: The string to check.
16390 * Checks if @string is a valid D-Bus member (e.g. signal or method) name.
16392 * Returns: %TRUE if valid, %FALSE otherwise.
16399 * @string: The string to check.
16401 * Checks if @string is a valid D-Bus bus name (either unique or well-known).
16403 * Returns: %TRUE if valid, %FALSE otherwise.
16409 * g_dbus_is_supported_address:
16410 * @string: A string.
16411 * @error: Return location for error or %NULL.
16413 * Like g_dbus_is_address() but also checks if the library suppors the
16414 * transports in @string and that key/value pairs for each transport
16417 * Returns: %TRUE if @string is a valid D-Bus address that is
16418 * supported by this library, %FALSE if @error is set.
16424 * g_dbus_is_unique_name:
16425 * @string: The string to check.
16427 * Checks if @string is a valid D-Bus unique bus name.
16429 * Returns: %TRUE if valid, %FALSE otherwise.
16435 * g_dbus_menu_model_get:
16436 * @connection: a #GDBusConnection
16437 * @bus_name: the bus name which exports the menu model
16438 * @object_path: the object path at which the menu model is exported
16440 * Obtains a #GDBusMenuModel for the menu model which is exported
16441 * at the given @bus_name and @object_path.
16443 * The thread default main context is taken at the time of this call.
16444 * All signals on the menu model (and any linked models) are reported
16445 * with respect to this context. All calls on the returned menu model
16446 * (and linked models) must also originate from this same context, with
16447 * the thread default main context unchanged.
16449 * Returns: (transfer full): a #GDBusMenuModel object. Free with
16450 * g_object_unref().
16456 * g_dbus_message_bytes_needed:
16457 * @blob: (array length=blob_len) (element-type guint8): A blob represent a binary D-Bus message.
16458 * @blob_len: The length of @blob (must be at least 16).
16459 * @error: Return location for error or %NULL.
16461 * Utility function to calculate how many bytes are needed to
16462 * completely deserialize the D-Bus message stored at @blob.
16464 * Returns: Number of bytes needed or -1 if @error is set (e.g. if
16465 * @blob contains invalid data or not enough data is available to
16466 * determine the size).
16472 * g_dbus_message_copy:
16473 * @message: A #GDBusMessage.
16474 * @error: Return location for error or %NULL.
16476 * Copies @message. The copy is a deep copy and the returned
16477 * #GDBusMessage is completely identical except that it is guaranteed
16478 * to not be locked.
16480 * This operation can fail if e.g. @message contains file descriptors
16481 * and the per-process or system-wide open files limit is reached.
16483 * Returns: (transfer full): A new #GDBusMessage or %NULL if @error is set.
16484 * Free with g_object_unref().
16490 * g_dbus_message_get_arg0:
16491 * @message: A #GDBusMessage.
16493 * Convenience to get the first item in the body of @message.
16495 * Returns: The string item or %NULL if the first item in the body of
16496 * @message is not a string.
16502 * g_dbus_message_get_body:
16503 * @message: A #GDBusMessage.
16505 * Gets the body of a message.
16507 * Returns: (transfer none): A #GVariant or %NULL if the body is
16508 * empty. Do not free, it is owned by @message.
16514 * g_dbus_message_get_byte_order:
16515 * @message: A #GDBusMessage.
16517 * Gets the byte order of @message.
16519 * Returns: The byte order.
16524 * g_dbus_message_get_destination:
16525 * @message: A #GDBusMessage.
16527 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field.
16529 * Returns: The value.
16535 * g_dbus_message_get_error_name:
16536 * @message: A #GDBusMessage.
16538 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field.
16540 * Returns: The value.
16546 * g_dbus_message_get_flags:
16547 * @message: A #GDBusMessage.
16549 * Gets the flags for @message.
16551 * Returns: Flags that are set (typically values from the #GDBusMessageFlags enumeration bitwise ORed together).
16557 * g_dbus_message_get_header:
16558 * @message: A #GDBusMessage.
16559 * @header_field: A 8-bit unsigned integer (typically a value from the #GDBusMessageHeaderField enumeration)
16561 * Gets a header field on @message.
16563 * Returns: A #GVariant with the value if the header was found, %NULL
16564 * otherwise. Do not free, it is owned by @message.
16570 * g_dbus_message_get_header_fields:
16571 * @message: A #GDBusMessage.
16573 * Gets an array of all header fields on @message that are set.
16575 * Returns: (array zero-terminated=1): An array of header fields
16576 * terminated by %G_DBUS_MESSAGE_HEADER_FIELD_INVALID. Each element
16577 * is a #guchar. Free with g_free().
16583 * g_dbus_message_get_interface:
16584 * @message: A #GDBusMessage.
16586 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE header field.
16588 * Returns: The value.
16594 * g_dbus_message_get_locked:
16595 * @message: A #GDBusMessage.
16597 * Checks whether @message is locked. To monitor changes to this
16598 * value, conncet to the #GObject::notify signal to listen for changes
16599 * on the #GDBusMessage:locked property.
16601 * Returns: %TRUE if @message is locked, %FALSE otherwise.
16607 * g_dbus_message_get_member:
16608 * @message: A #GDBusMessage.
16610 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_MEMBER header field.
16612 * Returns: The value.
16618 * g_dbus_message_get_message_type:
16619 * @message: A #GDBusMessage.
16621 * Gets the type of @message.
16623 * Returns: A 8-bit unsigned integer (typically a value from the #GDBusMessageType enumeration).
16629 * g_dbus_message_get_num_unix_fds:
16630 * @message: A #GDBusMessage.
16632 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header field.
16634 * Returns: The value.
16640 * g_dbus_message_get_path:
16641 * @message: A #GDBusMessage.
16643 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_PATH header field.
16645 * Returns: The value.
16651 * g_dbus_message_get_reply_serial:
16652 * @message: A #GDBusMessage.
16654 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL header field.
16656 * Returns: The value.
16662 * g_dbus_message_get_sender:
16663 * @message: A #GDBusMessage.
16665 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_SENDER header field.
16667 * Returns: The value.
16673 * g_dbus_message_get_serial:
16674 * @message: A #GDBusMessage.
16676 * Gets the serial for @message.
16678 * Returns: A #guint32.
16684 * g_dbus_message_get_signature:
16685 * @message: A #GDBusMessage.
16687 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field.
16689 * Returns: The value.
16695 * g_dbus_message_get_unix_fd_list:
16696 * @message: A #GDBusMessage.
16698 * Gets the UNIX file descriptors associated with @message, if any.
16700 * This method is only available on UNIX.
16702 * Returns: (transfer none): A #GUnixFDList or %NULL if no file descriptors are
16703 * associated. Do not free, this object is owned by @message.
16709 * g_dbus_message_lock:
16710 * @message: A #GDBusMessage.
16712 * If @message is locked, does nothing. Otherwise locks the message.
16719 * g_dbus_message_new:
16721 * Creates a new empty #GDBusMessage.
16723 * Returns: A #GDBusMessage. Free with g_object_unref().
16729 * g_dbus_message_new_from_blob:
16730 * @blob: (array length=blob_len) (element-type guint8): A blob represent a binary D-Bus message.
16731 * @blob_len: The length of @blob.
16732 * @capabilities: A #GDBusCapabilityFlags describing what protocol features are supported.
16733 * @error: Return location for error or %NULL.
16735 * Creates a new #GDBusMessage from the data stored at @blob. The byte
16736 * order that the message was in can be retrieved using
16737 * g_dbus_message_get_byte_order().
16739 * Returns: A new #GDBusMessage or %NULL if @error is set. Free with
16740 * g_object_unref().
16746 * g_dbus_message_new_method_call:
16747 * @name: (allow-none): A valid D-Bus name or %NULL.
16748 * @path: A valid object path.
16749 * @interface_: (allow-none): A valid D-Bus interface name or %NULL.
16750 * @method: A valid method name.
16752 * Creates a new #GDBusMessage for a method call.
16754 * Returns: A #GDBusMessage. Free with g_object_unref().
16760 * g_dbus_message_new_method_error:
16761 * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to
16762 * create a reply message to.
16763 * @error_name: A valid D-Bus error name.
16764 * @error_message_format: The D-Bus error message in a printf() format.
16765 * @...: Arguments for @error_message_format.
16767 * Creates a new #GDBusMessage that is an error reply to @method_call_message.
16769 * Returns: (transfer full): A #GDBusMessage. Free with g_object_unref().
16775 * g_dbus_message_new_method_error_literal:
16776 * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to
16777 * create a reply message to.
16778 * @error_name: A valid D-Bus error name.
16779 * @error_message: The D-Bus error message.
16781 * Creates a new #GDBusMessage that is an error reply to @method_call_message.
16783 * Returns: (transfer full): A #GDBusMessage. Free with g_object_unref().
16789 * g_dbus_message_new_method_error_valist:
16790 * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to
16791 * create a reply message to.
16792 * @error_name: A valid D-Bus error name.
16793 * @error_message_format: The D-Bus error message in a printf() format.
16794 * @var_args: Arguments for @error_message_format.
16796 * Like g_dbus_message_new_method_error() but intended for language bindings.
16798 * Returns: (transfer full): A #GDBusMessage. Free with g_object_unref().
16804 * g_dbus_message_new_method_reply:
16805 * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to
16806 * create a reply message to.
16808 * Creates a new #GDBusMessage that is a reply to @method_call_message.
16810 * Returns: (transfer full): #GDBusMessage. Free with g_object_unref().
16816 * g_dbus_message_new_signal:
16817 * @path: A valid object path.
16818 * @interface_: A valid D-Bus interface name.
16819 * @signal: A valid signal name.
16821 * Creates a new #GDBusMessage for a signal emission.
16823 * Returns: A #GDBusMessage. Free with g_object_unref().
16829 * g_dbus_message_print: (type method-return)
16830 * @message: A #GDBusMessage.
16831 * @indent: Indentation level.
16833 * Produces a human-readable multi-line description of @message.
16835 * The contents of the description has no ABI guarantees, the contents
16836 * and formatting is subject to change at any time. Typical output
16837 * looks something like this:
16843 * path -> objectpath '/org/gtk/GDBus/TestObject'
16844 * interface -> 'org.gtk.GDBus.TestInterface'
16845 * member -> 'GimmeStdout'
16846 * destination -> ':1.146'
16848 * UNIX File Descriptors:
16853 * Flags: no-reply-expected
16857 * reply-serial -> uint32 4
16858 * destination -> ':1.159'
16859 * sender -> ':1.146'
16860 * num-unix-fds -> uint32 1
16862 * UNIX File Descriptors:
16863 * fd 12: dev=0:10,mode=020620,ino=5,uid=500,gid=5,rdev=136:2,size=0,atime=1273085037,mtime=1273085851,ctime=1272982635
16866 * Returns: A string that should be freed with g_free().
16872 * g_dbus_message_set_body:
16873 * @message: A #GDBusMessage.
16874 * @body: Either %NULL or a #GVariant that is a tuple.
16876 * Sets the body @message. As a side-effect the
16877 * %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field is set to the
16878 * type string of @body (or cleared if @body is %NULL).
16880 * If @body is floating, @message assumes ownership of @body.
16887 * g_dbus_message_set_byte_order:
16888 * @message: A #GDBusMessage.
16889 * @byte_order: The byte order.
16891 * Sets the byte order of @message.
16896 * g_dbus_message_set_destination:
16897 * @message: A #GDBusMessage.
16898 * @value: The value to set.
16900 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field.
16907 * g_dbus_message_set_error_name:
16908 * @message: A #GDBusMessage.
16909 * @value: The value to set.
16911 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field.
16918 * g_dbus_message_set_flags:
16919 * @message: A #GDBusMessage.
16920 * @flags: Flags for @message that are set (typically values from the #GDBusMessageFlags
16921 * enumeration bitwise ORed together).
16923 * Sets the flags to set on @message.
16930 * g_dbus_message_set_header:
16931 * @message: A #GDBusMessage.
16932 * @header_field: A 8-bit unsigned integer (typically a value from the #GDBusMessageHeaderField enumeration)
16933 * @value: (allow-none): A #GVariant to set the header field or %NULL to clear the header field.
16935 * Sets a header field on @message.
16937 * If @value is floating, @message assumes ownership of @value.
16944 * g_dbus_message_set_interface:
16945 * @message: A #GDBusMessage.
16946 * @value: The value to set.
16948 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE header field.
16955 * g_dbus_message_set_member:
16956 * @message: A #GDBusMessage.
16957 * @value: The value to set.
16959 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_MEMBER header field.
16966 * g_dbus_message_set_message_type:
16967 * @message: A #GDBusMessage.
16968 * @type: A 8-bit unsigned integer (typically a value from the #GDBusMessageType enumeration).
16970 * Sets @message to be of @type.
16977 * g_dbus_message_set_num_unix_fds:
16978 * @message: A #GDBusMessage.
16979 * @value: The value to set.
16981 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header field.
16988 * g_dbus_message_set_path:
16989 * @message: A #GDBusMessage.
16990 * @value: The value to set.
16992 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_PATH header field.
16999 * g_dbus_message_set_reply_serial:
17000 * @message: A #GDBusMessage.
17001 * @value: The value to set.
17003 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL header field.
17010 * g_dbus_message_set_sender:
17011 * @message: A #GDBusMessage.
17012 * @value: The value to set.
17014 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_SENDER header field.
17021 * g_dbus_message_set_serial:
17022 * @message: A #GDBusMessage.
17023 * @serial: A #guint32.
17025 * Sets the serial for @message.
17032 * g_dbus_message_set_signature:
17033 * @message: A #GDBusMessage.
17034 * @value: The value to set.
17036 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field.
17043 * g_dbus_message_set_unix_fd_list:
17044 * @message: A #GDBusMessage.
17045 * @fd_list: (allow-none): A #GUnixFDList or %NULL.
17047 * Sets the UNIX file descriptors associated with @message. As a
17048 * side-effect the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header
17049 * field is set to the number of fds in @fd_list (or cleared if
17050 * @fd_list is %NULL).
17052 * This method is only available on UNIX.
17059 * g_dbus_message_to_blob:
17060 * @message: A #GDBusMessage.
17061 * @out_size: Return location for size of generated blob.
17062 * @capabilities: A #GDBusCapabilityFlags describing what protocol features are supported.
17063 * @error: Return location for error.
17065 * Serializes @message to a blob. The byte order returned by
17066 * g_dbus_message_get_byte_order() will be used.
17068 * Returns: (array length=out_size) (transfer full): A pointer to a
17069 * valid binary D-Bus message of @out_size bytes generated by @message
17070 * or %NULL if @error is set. Free with g_free().
17076 * g_dbus_message_to_gerror:
17077 * @message: A #GDBusMessage.
17078 * @error: The #GError to set.
17080 * If @message is not of type %G_DBUS_MESSAGE_TYPE_ERROR does
17081 * nothing and returns %FALSE.
17083 * Otherwise this method encodes the error in @message as a #GError
17084 * using g_dbus_error_set_dbus_error() using the information in the
17085 * %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field of @message as
17086 * well as the first string item in @message's body.
17088 * Returns: %TRUE if @error was set, %FALSE otherwise.
17094 * g_dbus_method_info_ref:
17095 * @info: A #GDBusMethodInfo
17097 * If @info is statically allocated does nothing. Otherwise increases
17098 * the reference count.
17100 * Returns: The same @info.
17106 * g_dbus_method_info_unref:
17107 * @info: A #GDBusMethodInfo.
17109 * If @info is statically allocated, does nothing. Otherwise decreases
17110 * the reference count of @info. When its reference count drops to 0,
17111 * the memory used is freed.
17118 * g_dbus_method_invocation_get_connection:
17119 * @invocation: A #GDBusMethodInvocation.
17121 * Gets the #GDBusConnection the method was invoked on.
17123 * Returns: (transfer none): A #GDBusConnection. Do not free, it is owned by @invocation.
17129 * g_dbus_method_invocation_get_interface_name:
17130 * @invocation: A #GDBusMethodInvocation.
17132 * Gets the name of the D-Bus interface the method was invoked on.
17134 * If this method call is a property Get, Set or GetAll call that has
17135 * been redirected to the method call handler then
17136 * "org.freedesktop.DBus.Properties" will be returned. See
17137 * #GDBusInterfaceVTable for more information.
17139 * Returns: A string. Do not free, it is owned by @invocation.
17145 * g_dbus_method_invocation_get_message:
17146 * @invocation: A #GDBusMethodInvocation.
17148 * Gets the #GDBusMessage for the method invocation. This is useful if
17149 * you need to use low-level protocol features, such as UNIX file
17150 * descriptor passing, that cannot be properly expressed in the
17153 * See this [server][gdbus-server] and [client][gdbus-unix-fd-client]
17154 * for an example of how to use this low-level API to send and receive
17155 * UNIX file descriptors.
17157 * Returns: (transfer none): #GDBusMessage. Do not free, it is owned by @invocation.
17163 * g_dbus_method_invocation_get_method_info:
17164 * @invocation: A #GDBusMethodInvocation.
17166 * Gets information about the method call, if any.
17168 * If this method invocation is a property Get, Set or GetAll call that
17169 * has been redirected to the method call handler then %NULL will be
17170 * returned. See g_dbus_method_invocation_get_property_info() and
17171 * #GDBusInterfaceVTable for more information.
17173 * Returns: A #GDBusMethodInfo or %NULL. Do not free, it is owned by @invocation.
17179 * g_dbus_method_invocation_get_method_name:
17180 * @invocation: A #GDBusMethodInvocation.
17182 * Gets the name of the method that was invoked.
17184 * Returns: A string. Do not free, it is owned by @invocation.
17190 * g_dbus_method_invocation_get_object_path:
17191 * @invocation: A #GDBusMethodInvocation.
17193 * Gets the object path the method was invoked on.
17195 * Returns: A string. Do not free, it is owned by @invocation.
17201 * g_dbus_method_invocation_get_parameters:
17202 * @invocation: A #GDBusMethodInvocation.
17204 * Gets the parameters of the method invocation. If there are no input
17205 * parameters then this will return a GVariant with 0 children rather than NULL.
17207 * Returns: (transfer none): A #GVariant tuple. Do not unref this because it is owned by @invocation.
17213 * g_dbus_method_invocation_get_property_info:
17214 * @invocation: A #GDBusMethodInvocation
17216 * Gets information about the property that this method call is for, if
17219 * This will only be set in the case of an invocation in response to a
17220 * property Get or Set call that has been directed to the method call
17221 * handler for an object on account of its property_get() or
17222 * property_set() vtable pointers being unset.
17224 * See #GDBusInterfaceVTable for more information.
17226 * If the call was GetAll, %NULL will be returned.
17228 * Returns: (transfer none): a #GDBusPropertyInfo or %NULL
17234 * g_dbus_method_invocation_get_sender:
17235 * @invocation: A #GDBusMethodInvocation.
17237 * Gets the bus name that invoked the method.
17239 * Returns: A string. Do not free, it is owned by @invocation.
17245 * g_dbus_method_invocation_get_user_data: (skip)
17246 * @invocation: A #GDBusMethodInvocation.
17248 * Gets the @user_data #gpointer passed to g_dbus_connection_register_object().
17250 * Returns: A #gpointer.
17256 * g_dbus_method_invocation_return_dbus_error:
17257 * @invocation: (transfer full): A #GDBusMethodInvocation.
17258 * @error_name: A valid D-Bus error name.
17259 * @error_message: A valid D-Bus error message.
17261 * Finishes handling a D-Bus method call by returning an error.
17263 * This method will free @invocation, you cannot use it afterwards.
17270 * g_dbus_method_invocation_return_error:
17271 * @invocation: (transfer full): A #GDBusMethodInvocation.
17272 * @domain: A #GQuark for the #GError error domain.
17273 * @code: The error code.
17274 * @format: printf()-style format.
17275 * @...: Parameters for @format.
17277 * Finishes handling a D-Bus method call by returning an error.
17279 * See g_dbus_error_encode_gerror() for details about what error name
17280 * will be returned on the wire. In a nutshell, if the given error is
17281 * registered using g_dbus_error_register_error() the name given
17282 * during registration is used. Otherwise, a name of the form
17283 * `org.gtk.GDBus.UnmappedGError.Quark...` is used. This provides
17284 * transparent mapping of #GError between applications using GDBus.
17286 * If you are writing an application intended to be portable,
17287 * always register errors with g_dbus_error_register_error()
17288 * or use g_dbus_method_invocation_return_dbus_error().
17290 * This method will free @invocation, you cannot use it afterwards.
17297 * g_dbus_method_invocation_return_error_literal:
17298 * @invocation: (transfer full): A #GDBusMethodInvocation.
17299 * @domain: A #GQuark for the #GError error domain.
17300 * @code: The error code.
17301 * @message: The error message.
17303 * Like g_dbus_method_invocation_return_error() but without printf()-style formatting.
17305 * This method will free @invocation, you cannot use it afterwards.
17312 * g_dbus_method_invocation_return_error_valist:
17313 * @invocation: (transfer full): A #GDBusMethodInvocation.
17314 * @domain: A #GQuark for the #GError error domain.
17315 * @code: The error code.
17316 * @format: printf()-style format.
17317 * @var_args: #va_list of parameters for @format.
17319 * Like g_dbus_method_invocation_return_error() but intended for
17320 * language bindings.
17322 * This method will free @invocation, you cannot use it afterwards.
17329 * g_dbus_method_invocation_return_gerror:
17330 * @invocation: (transfer full): A #GDBusMethodInvocation.
17331 * @error: A #GError.
17333 * Like g_dbus_method_invocation_return_error() but takes a #GError
17334 * instead of the error domain, error code and message.
17336 * This method will free @invocation, you cannot use it afterwards.
17343 * g_dbus_method_invocation_return_value:
17344 * @invocation: (transfer full): A #GDBusMethodInvocation.
17345 * @parameters: (allow-none): A #GVariant tuple with out parameters for the method or %NULL if not passing any parameters.
17347 * Finishes handling a D-Bus method call by returning @parameters.
17348 * If the @parameters GVariant is floating, it is consumed.
17350 * It is an error if @parameters is not of the right format.
17352 * This method will free @invocation, you cannot use it afterwards.
17359 * g_dbus_method_invocation_return_value_with_unix_fd_list:
17360 * @invocation: (transfer full): A #GDBusMethodInvocation.
17361 * @parameters: (allow-none): A #GVariant tuple with out parameters for the method or %NULL if not passing any parameters.
17362 * @fd_list: (allow-none): A #GUnixFDList or %NULL.
17364 * Like g_dbus_method_invocation_return_value() but also takes a #GUnixFDList.
17366 * This method is only available on UNIX.
17368 * This method will free @invocation, you cannot use it afterwards.
17375 * g_dbus_method_invocation_take_error: (skip)
17376 * @invocation: (transfer full): A #GDBusMethodInvocation.
17377 * @error: (transfer full): A #GError.
17379 * Like g_dbus_method_invocation_return_gerror() but takes ownership
17380 * of @error so the caller does not need to free it.
17382 * This method will free @invocation, you cannot use it afterwards.
17389 * g_dbus_node_info_generate_xml:
17390 * @info: A #GDBusNodeInfo.
17391 * @indent: Indentation level.
17392 * @string_builder: (out): A #GString to to append XML data to.
17394 * Appends an XML representation of @info (and its children) to @string_builder.
17396 * This function is typically used for generating introspection XML documents at run-time for
17397 * handling the `org.freedesktop.DBus.Introspectable.Introspect` method.
17404 * g_dbus_node_info_lookup_interface:
17405 * @info: A #GDBusNodeInfo.
17406 * @name: A D-Bus interface name.
17408 * Looks up information about an interface.
17410 * The cost of this function is O(n) in number of interfaces.
17412 * Returns: (transfer none): A #GDBusInterfaceInfo or %NULL if not found. Do not free, it is owned by @info.
17418 * g_dbus_node_info_new_for_xml:
17419 * @xml_data: Valid D-Bus introspection XML.
17420 * @error: Return location for error.
17422 * Parses @xml_data and returns a #GDBusNodeInfo representing the data.
17424 * The introspection XML must contain exactly one top-level
17427 * Note that this routine is using a
17428 * [GMarkup][glib-Simple-XML-Subset-Parser.description]-based
17429 * parser that only accepts a subset of valid XML documents.
17431 * Returns: A #GDBusNodeInfo structure or %NULL if @error is set. Free
17432 * with g_dbus_node_info_unref().
17438 * g_dbus_node_info_ref:
17439 * @info: A #GDBusNodeInfo
17441 * If @info is statically allocated does nothing. Otherwise increases
17442 * the reference count.
17444 * Returns: The same @info.
17450 * g_dbus_node_info_unref:
17451 * @info: A #GDBusNodeInfo.
17453 * If @info is statically allocated, does nothing. Otherwise decreases
17454 * the reference count of @info. When its reference count drops to 0,
17455 * the memory used is freed.
17462 * g_dbus_object_get_interface:
17463 * @object: A #GDBusObject.
17464 * @interface_name: A D-Bus interface name.
17466 * Gets the D-Bus interface with name @interface_name associated with
17469 * Returns: (transfer full): %NULL if not found, otherwise a
17470 * #GDBusInterface that must be freed with g_object_unref().
17476 * g_dbus_object_get_interfaces:
17477 * @object: A #GDBusObject.
17479 * Gets the D-Bus interfaces associated with @object.
17481 * Returns: (element-type GDBusInterface) (transfer full): A list of #GDBusInterface instances.
17482 * The returned list must be freed by g_list_free() after each element has been freed
17483 * with g_object_unref().
17489 * g_dbus_object_get_object_path:
17490 * @object: A #GDBusObject.
17492 * Gets the object path for @object.
17494 * Returns: A string owned by @object. Do not free.
17500 * g_dbus_object_manager_client_get_connection:
17501 * @manager: A #GDBusObjectManagerClient
17503 * Gets the #GDBusConnection used by @manager.
17505 * Returns: (transfer none): A #GDBusConnection object. Do not free,
17506 * the object belongs to @manager.
17512 * g_dbus_object_manager_client_get_flags:
17513 * @manager: A #GDBusObjectManagerClient
17515 * Gets the flags that @manager was constructed with.
17517 * Returns: Zero of more flags from the #GDBusObjectManagerClientFlags
17524 * g_dbus_object_manager_client_get_name:
17525 * @manager: A #GDBusObjectManagerClient
17527 * Gets the name that @manager is for, or %NULL if not a message bus
17530 * Returns: A unique or well-known name. Do not free, the string
17531 * belongs to @manager.
17537 * g_dbus_object_manager_client_get_name_owner:
17538 * @manager: A #GDBusObjectManagerClient.
17540 * The unique name that owns the name that @manager is for or %NULL if
17541 * no-one currently owns that name. You can connect to the
17542 * #GObject::notify signal to track changes to the
17543 * #GDBusObjectManagerClient:name-owner property.
17545 * Returns: (nullable): The name owner or %NULL if no name owner
17546 * exists. Free with g_free().
17552 * g_dbus_object_manager_client_new:
17553 * @connection: A #GDBusConnection.
17554 * @flags: Zero or more flags from the #GDBusObjectManagerClientFlags enumeration.
17555 * @name: The owner of the control object (unique or well-known name).
17556 * @object_path: The object path of the control object.
17557 * @get_proxy_type_func: (allow-none): A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies.
17558 * @get_proxy_type_user_data: User data to pass to @get_proxy_type_func.
17559 * @get_proxy_type_destroy_notify: (allow-none): Free function for @get_proxy_type_user_data or %NULL.
17560 * @cancellable: (allow-none): A #GCancellable or %NULL
17561 * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
17562 * @user_data: The data to pass to @callback.
17564 * Asynchronously creates a new #GDBusObjectManagerClient object.
17566 * This is an asynchronous failable constructor. When the result is
17567 * ready, @callback will be invoked in the
17568 * [thread-default main context][g-main-context-push-thread-default]
17569 * of the thread you are calling this method from. You can
17570 * then call g_dbus_object_manager_client_new_finish() to get the result. See
17571 * g_dbus_object_manager_client_new_sync() for the synchronous version.
17578 * g_dbus_object_manager_client_new_finish:
17579 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_object_manager_client_new().
17580 * @error: Return location for error or %NULL.
17582 * Finishes an operation started with g_dbus_object_manager_client_new().
17584 * Returns: (transfer full) (type GDBusObjectManagerClient): A
17585 * #GDBusObjectManagerClient object or %NULL if @error is set. Free
17586 * with g_object_unref().
17592 * g_dbus_object_manager_client_new_for_bus:
17593 * @bus_type: A #GBusType.
17594 * @flags: Zero or more flags from the #GDBusObjectManagerClientFlags enumeration.
17595 * @name: The owner of the control object (unique or well-known name).
17596 * @object_path: The object path of the control object.
17597 * @get_proxy_type_func: (allow-none): A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies.
17598 * @get_proxy_type_user_data: User data to pass to @get_proxy_type_func.
17599 * @get_proxy_type_destroy_notify: (allow-none): Free function for @get_proxy_type_user_data or %NULL.
17600 * @cancellable: (allow-none): A #GCancellable or %NULL
17601 * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
17602 * @user_data: The data to pass to @callback.
17604 * Like g_dbus_object_manager_client_new() but takes a #GBusType instead of a
17605 * #GDBusConnection.
17607 * This is an asynchronous failable constructor. When the result is
17608 * ready, @callback will be invoked in the
17609 * [thread-default main loop][g-main-context-push-thread-default]
17610 * of the thread you are calling this method from. You can
17611 * then call g_dbus_object_manager_client_new_for_bus_finish() to get the result. See
17612 * g_dbus_object_manager_client_new_for_bus_sync() for the synchronous version.
17619 * g_dbus_object_manager_client_new_for_bus_finish:
17620 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_object_manager_client_new_for_bus().
17621 * @error: Return location for error or %NULL.
17623 * Finishes an operation started with g_dbus_object_manager_client_new_for_bus().
17625 * Returns: (transfer full) (type GDBusObjectManagerClient): A
17626 * #GDBusObjectManagerClient object or %NULL if @error is set. Free
17627 * with g_object_unref().
17633 * g_dbus_object_manager_client_new_for_bus_sync:
17634 * @bus_type: A #GBusType.
17635 * @flags: Zero or more flags from the #GDBusObjectManagerClientFlags enumeration.
17636 * @name: The owner of the control object (unique or well-known name).
17637 * @object_path: The object path of the control object.
17638 * @get_proxy_type_func: (allow-none): A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies.
17639 * @get_proxy_type_user_data: User data to pass to @get_proxy_type_func.
17640 * @get_proxy_type_destroy_notify: (allow-none): Free function for @get_proxy_type_user_data or %NULL.
17641 * @cancellable: (allow-none): A #GCancellable or %NULL
17642 * @error: Return location for error or %NULL.
17644 * Like g_dbus_object_manager_client_new_sync() but takes a #GBusType instead
17645 * of a #GDBusConnection.
17647 * This is a synchronous failable constructor - the calling thread is
17648 * blocked until a reply is received. See g_dbus_object_manager_client_new_for_bus()
17649 * for the asynchronous version.
17651 * Returns: (transfer full) (type GDBusObjectManagerClient): A
17652 * #GDBusObjectManagerClient object or %NULL if @error is set. Free
17653 * with g_object_unref().
17659 * g_dbus_object_manager_client_new_sync:
17660 * @connection: A #GDBusConnection.
17661 * @flags: Zero or more flags from the #GDBusObjectManagerClientFlags enumeration.
17662 * @name: (allow-none): The owner of the control object (unique or well-known name), or %NULL when not using a message bus connection.
17663 * @object_path: The object path of the control object.
17664 * @get_proxy_type_func: (allow-none): A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies.
17665 * @get_proxy_type_user_data: User data to pass to @get_proxy_type_func.
17666 * @get_proxy_type_destroy_notify: (allow-none): Free function for @get_proxy_type_user_data or %NULL.
17667 * @cancellable: (allow-none): A #GCancellable or %NULL
17668 * @error: Return location for error or %NULL.
17670 * Creates a new #GDBusObjectManagerClient object.
17672 * This is a synchronous failable constructor - the calling thread is
17673 * blocked until a reply is received. See g_dbus_object_manager_client_new()
17674 * for the asynchronous version.
17676 * Returns: (transfer full) (type GDBusObjectManagerClient): A
17677 * #GDBusObjectManagerClient object or %NULL if @error is set. Free
17678 * with g_object_unref().
17684 * g_dbus_object_manager_get_interface:
17685 * @manager: A #GDBusObjectManager.
17686 * @object_path: Object path to lookup.
17687 * @interface_name: D-Bus interface name to lookup.
17689 * Gets the interface proxy for @interface_name at @object_path, if
17692 * Returns: (transfer full): A #GDBusInterface instance or %NULL. Free
17693 * with g_object_unref().
17699 * g_dbus_object_manager_get_object:
17700 * @manager: A #GDBusObjectManager.
17701 * @object_path: Object path to lookup.
17703 * Gets the #GDBusObjectProxy at @object_path, if any.
17705 * Returns: (transfer full): A #GDBusObject or %NULL. Free with
17706 * g_object_unref().
17712 * g_dbus_object_manager_get_object_path:
17713 * @manager: A #GDBusObjectManager.
17715 * Gets the object path that @manager is for.
17717 * Returns: A string owned by @manager. Do not free.
17723 * g_dbus_object_manager_get_objects:
17724 * @manager: A #GDBusObjectManager.
17726 * Gets all #GDBusObject objects known to @manager.
17728 * Returns: (transfer full) (element-type GDBusObject): A list of
17729 * #GDBusObject objects. The returned list should be freed with
17730 * g_list_free() after each element has been freed with
17731 * g_object_unref().
17737 * g_dbus_object_manager_server_export:
17738 * @manager: A #GDBusObjectManagerServer.
17739 * @object: A #GDBusObjectSkeleton.
17741 * Exports @object on @manager.
17743 * If there is already a #GDBusObject exported at the object path,
17744 * then the old object is removed.
17746 * The object path for @object must be in the hierarchy rooted by the
17747 * object path for @manager.
17749 * Note that @manager will take a reference on @object for as long as
17757 * g_dbus_object_manager_server_export_uniquely:
17758 * @manager: A #GDBusObjectManagerServer.
17759 * @object: An object.
17761 * Like g_dbus_object_manager_server_export() but appends a string of
17762 * the form _N (with N being a natural number) to @object's object path
17763 * if an object with the given path already exists. As such, the
17764 * #GDBusObjectProxy:g-object-path property of @object may be modified.
17771 * g_dbus_object_manager_server_get_connection:
17772 * @manager: A #GDBusObjectManagerServer
17774 * Gets the #GDBusConnection used by @manager.
17776 * Returns: (transfer full): A #GDBusConnection object or %NULL if
17777 * @manager isn't exported on a connection. The returned object should
17778 * be freed with g_object_unref().
17784 * g_dbus_object_manager_server_is_exported:
17785 * @manager: A #GDBusObjectManagerServer.
17786 * @object: An object.
17788 * Returns whether @object is currently exported on @manager.
17790 * Returns: %TRUE if @object is exported
17796 * g_dbus_object_manager_server_new:
17797 * @object_path: The object path to export the manager object at.
17799 * Creates a new #GDBusObjectManagerServer object.
17801 * The returned server isn't yet exported on any connection. To do so,
17802 * use g_dbus_object_manager_server_set_connection(). Normally you
17803 * want to export all of your objects before doing so to avoid <ulink
17804 * url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager">InterfacesAdded</ulink>
17805 * signals being emitted.
17807 * Returns: A #GDBusObjectManagerServer object. Free with g_object_unref().
17813 * g_dbus_object_manager_server_set_connection:
17814 * @manager: A #GDBusObjectManagerServer.
17815 * @connection: (allow-none): A #GDBusConnection or %NULL.
17817 * Exports all objects managed by @manager on @connection. If
17818 * @connection is %NULL, stops exporting objects.
17823 * g_dbus_object_manager_server_unexport:
17824 * @manager: A #GDBusObjectManagerServer.
17825 * @object_path: An object path.
17827 * If @manager has an object at @path, removes the object. Otherwise
17830 * Note that @object_path must be in the hierarchy rooted by the
17831 * object path for @manager.
17833 * Returns: %TRUE if object at @object_path was removed, %FALSE otherwise.
17839 * g_dbus_object_proxy_get_connection:
17840 * @proxy: a #GDBusObjectProxy
17842 * Gets the connection that @proxy is for.
17844 * Returns: (transfer none): A #GDBusConnection. Do not free, the
17845 * object is owned by @proxy.
17851 * g_dbus_object_proxy_new:
17852 * @connection: a #GDBusConnection
17853 * @object_path: the object path
17855 * Creates a new #GDBusObjectProxy for the given connection and
17858 * Returns: a new #GDBusObjectProxy
17864 * g_dbus_object_skeleton_add_interface:
17865 * @object: A #GDBusObjectSkeleton.
17866 * @interface_: A #GDBusInterfaceSkeleton.
17868 * Adds @interface_ to @object.
17870 * If @object already contains a #GDBusInterfaceSkeleton with the same
17871 * interface name, it is removed before @interface_ is added.
17873 * Note that @object takes its own reference on @interface_ and holds
17874 * it until removed.
17881 * g_dbus_object_skeleton_flush:
17882 * @object: A #GDBusObjectSkeleton.
17884 * This method simply calls g_dbus_interface_skeleton_flush() on all
17885 * interfaces belonging to @object. See that method for when flushing
17893 * g_dbus_object_skeleton_new:
17894 * @object_path: An object path.
17896 * Creates a new #GDBusObjectSkeleton.
17898 * Returns: A #GDBusObjectSkeleton. Free with g_object_unref().
17904 * g_dbus_object_skeleton_remove_interface:
17905 * @object: A #GDBusObjectSkeleton.
17906 * @interface_: A #GDBusInterfaceSkeleton.
17908 * Removes @interface_ from @object.
17915 * g_dbus_object_skeleton_remove_interface_by_name:
17916 * @object: A #GDBusObjectSkeleton.
17917 * @interface_name: A D-Bus interface name.
17919 * Removes the #GDBusInterface with @interface_name from @object.
17921 * If no D-Bus interface of the given interface exists, this function
17929 * g_dbus_object_skeleton_set_object_path:
17930 * @object: A #GDBusObjectSkeleton.
17931 * @object_path: A valid D-Bus object path.
17933 * Sets the object path for @object.
17940 * g_dbus_property_info_ref:
17941 * @info: A #GDBusPropertyInfo
17943 * If @info is statically allocated does nothing. Otherwise increases
17944 * the reference count.
17946 * Returns: The same @info.
17952 * g_dbus_property_info_unref:
17953 * @info: A #GDBusPropertyInfo.
17955 * If @info is statically allocated, does nothing. Otherwise decreases
17956 * the reference count of @info. When its reference count drops to 0,
17957 * the memory used is freed.
17964 * g_dbus_proxy_call:
17965 * @proxy: A #GDBusProxy.
17966 * @method_name: Name of method to invoke.
17967 * @parameters: (allow-none): A #GVariant tuple with parameters for the signal or %NULL if not passing parameters.
17968 * @flags: Flags from the #GDBusCallFlags enumeration.
17969 * @timeout_msec: The timeout in milliseconds (with %G_MAXINT meaning
17970 * "infinite") or -1 to use the proxy default timeout.
17971 * @cancellable: (allow-none): A #GCancellable or %NULL.
17972 * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't
17973 * care about the result of the method invocation.
17974 * @user_data: The data to pass to @callback.
17976 * Asynchronously invokes the @method_name method on @proxy.
17978 * If @method_name contains any dots, then @name is split into interface and
17979 * method name parts. This allows using @proxy for invoking methods on
17980 * other interfaces.
17982 * If the #GDBusConnection associated with @proxy is closed then
17983 * the operation will fail with %G_IO_ERROR_CLOSED. If
17984 * @cancellable is canceled, the operation will fail with
17985 * %G_IO_ERROR_CANCELLED. If @parameters contains a value not
17986 * compatible with the D-Bus protocol, the operation fails with
17987 * %G_IO_ERROR_INVALID_ARGUMENT.
17989 * If the @parameters #GVariant is floating, it is consumed. This allows
17990 * convenient 'inline' use of g_variant_new(), e.g.:
17991 * |[<!-- language="C" -->
17992 * g_dbus_proxy_call (proxy,
17994 * g_variant_new ("(ss)",
17997 * G_DBUS_CALL_FLAGS_NONE,
18000 * (GAsyncReadyCallback) two_strings_done,
18004 * If @proxy has an expected interface (see
18005 * #GDBusProxy:g-interface-info) and @method_name is referenced by it,
18006 * then the return value is checked against the return type.
18008 * This is an asynchronous method. When the operation is finished,
18009 * @callback will be invoked in the
18010 * [thread-default main context][g-main-context-push-thread-default]
18011 * of the thread you are calling this method from.
18012 * You can then call g_dbus_proxy_call_finish() to get the result of
18013 * the operation. See g_dbus_proxy_call_sync() for the synchronous
18014 * version of this method.
18016 * If @callback is %NULL then the D-Bus method call message will be sent with
18017 * the %G_DBUS_MESSAGE_FLAGS_NO_REPLY_EXPECTED flag set.
18024 * g_dbus_proxy_call_finish:
18025 * @proxy: A #GDBusProxy.
18026 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_proxy_call().
18027 * @error: Return location for error or %NULL.
18029 * Finishes an operation started with g_dbus_proxy_call().
18031 * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
18032 * return values. Free with g_variant_unref().
18038 * g_dbus_proxy_call_sync:
18039 * @proxy: A #GDBusProxy.
18040 * @method_name: Name of method to invoke.
18041 * @parameters: (allow-none): A #GVariant tuple with parameters for the signal
18042 * or %NULL if not passing parameters.
18043 * @flags: Flags from the #GDBusCallFlags enumeration.
18044 * @timeout_msec: The timeout in milliseconds (with %G_MAXINT meaning
18045 * "infinite") or -1 to use the proxy default timeout.
18046 * @cancellable: (allow-none): A #GCancellable or %NULL.
18047 * @error: Return location for error or %NULL.
18049 * Synchronously invokes the @method_name method on @proxy.
18051 * If @method_name contains any dots, then @name is split into interface and
18052 * method name parts. This allows using @proxy for invoking methods on
18053 * other interfaces.
18055 * If the #GDBusConnection associated with @proxy is disconnected then
18056 * the operation will fail with %G_IO_ERROR_CLOSED. If
18057 * @cancellable is canceled, the operation will fail with
18058 * %G_IO_ERROR_CANCELLED. If @parameters contains a value not
18059 * compatible with the D-Bus protocol, the operation fails with
18060 * %G_IO_ERROR_INVALID_ARGUMENT.
18062 * If the @parameters #GVariant is floating, it is consumed. This allows
18063 * convenient 'inline' use of g_variant_new(), e.g.:
18064 * |[<!-- language="C" -->
18065 * g_dbus_proxy_call_sync (proxy,
18067 * g_variant_new ("(ss)",
18070 * G_DBUS_CALL_FLAGS_NONE,
18076 * The calling thread is blocked until a reply is received. See
18077 * g_dbus_proxy_call() for the asynchronous version of this
18080 * If @proxy has an expected interface (see
18081 * #GDBusProxy:g-interface-info) and @method_name is referenced by it,
18082 * then the return value is checked against the return type.
18084 * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
18085 * return values. Free with g_variant_unref().
18091 * g_dbus_proxy_call_with_unix_fd_list:
18092 * @proxy: A #GDBusProxy.
18093 * @method_name: Name of method to invoke.
18094 * @parameters: (allow-none): A #GVariant tuple with parameters for the signal or %NULL if not passing parameters.
18095 * @flags: Flags from the #GDBusCallFlags enumeration.
18096 * @timeout_msec: The timeout in milliseconds (with %G_MAXINT meaning
18097 * "infinite") or -1 to use the proxy default timeout.
18098 * @fd_list: (allow-none): A #GUnixFDList or %NULL.
18099 * @cancellable: (allow-none): A #GCancellable or %NULL.
18100 * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't
18101 * care about the result of the method invocation.
18102 * @user_data: The data to pass to @callback.
18104 * Like g_dbus_proxy_call() but also takes a #GUnixFDList object.
18106 * This method is only available on UNIX.
18113 * g_dbus_proxy_call_with_unix_fd_list_finish:
18114 * @proxy: A #GDBusProxy.
18115 * @out_fd_list: (out) (allow-none): Return location for a #GUnixFDList or %NULL.
18116 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_proxy_call_with_unix_fd_list().
18117 * @error: Return location for error or %NULL.
18119 * Finishes an operation started with g_dbus_proxy_call_with_unix_fd_list().
18121 * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
18122 * return values. Free with g_variant_unref().
18128 * g_dbus_proxy_call_with_unix_fd_list_sync:
18129 * @proxy: A #GDBusProxy.
18130 * @method_name: Name of method to invoke.
18131 * @parameters: (allow-none): A #GVariant tuple with parameters for the signal
18132 * or %NULL if not passing parameters.
18133 * @flags: Flags from the #GDBusCallFlags enumeration.
18134 * @timeout_msec: The timeout in milliseconds (with %G_MAXINT meaning
18135 * "infinite") or -1 to use the proxy default timeout.
18136 * @fd_list: (allow-none): A #GUnixFDList or %NULL.
18137 * @out_fd_list: (out) (allow-none): Return location for a #GUnixFDList or %NULL.
18138 * @cancellable: (allow-none): A #GCancellable or %NULL.
18139 * @error: Return location for error or %NULL.
18141 * Like g_dbus_proxy_call_sync() but also takes and returns #GUnixFDList objects.
18143 * This method is only available on UNIX.
18145 * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
18146 * return values. Free with g_variant_unref().
18152 * g_dbus_proxy_get_cached_property:
18153 * @proxy: A #GDBusProxy.
18154 * @property_name: Property name.
18156 * Looks up the value for a property from the cache. This call does no
18159 * If @proxy has an expected interface (see
18160 * #GDBusProxy:g-interface-info) and @property_name is referenced by
18161 * it, then @value is checked against the type of the property.
18163 * Returns: A reference to the #GVariant instance that holds the value
18164 * for @property_name or %NULL if the value is not in the cache. The
18165 * returned reference must be freed with g_variant_unref().
18171 * g_dbus_proxy_get_cached_property_names:
18172 * @proxy: A #GDBusProxy.
18174 * Gets the names of all cached properties on @proxy.
18176 * Returns: (transfer full): A %NULL-terminated array of strings or %NULL if
18177 * @proxy has no cached properties. Free the returned array with
18184 * g_dbus_proxy_get_connection:
18185 * @proxy: A #GDBusProxy.
18187 * Gets the connection @proxy is for.
18189 * Returns: (transfer none): A #GDBusConnection owned by @proxy. Do not free.
18195 * g_dbus_proxy_get_default_timeout:
18196 * @proxy: A #GDBusProxy.
18198 * Gets the timeout to use if -1 (specifying default timeout) is
18199 * passed as @timeout_msec in the g_dbus_proxy_call() and
18200 * g_dbus_proxy_call_sync() functions.
18202 * See the #GDBusProxy:g-default-timeout property for more details.
18204 * Returns: Timeout to use for @proxy.
18210 * g_dbus_proxy_get_flags:
18211 * @proxy: A #GDBusProxy.
18213 * Gets the flags that @proxy was constructed with.
18215 * Returns: Flags from the #GDBusProxyFlags enumeration.
18221 * g_dbus_proxy_get_interface_info:
18222 * @proxy: A #GDBusProxy
18224 * Returns the #GDBusInterfaceInfo, if any, specifying the interface
18225 * that @proxy conforms to. See the #GDBusProxy:g-interface-info
18226 * property for more details.
18228 * Returns: A #GDBusInterfaceInfo or %NULL. Do not unref the returned
18229 * object, it is owned by @proxy.
18235 * g_dbus_proxy_get_interface_name:
18236 * @proxy: A #GDBusProxy.
18238 * Gets the D-Bus interface name @proxy is for.
18240 * Returns: A string owned by @proxy. Do not free.
18246 * g_dbus_proxy_get_name:
18247 * @proxy: A #GDBusProxy.
18249 * Gets the name that @proxy was constructed for.
18251 * Returns: A string owned by @proxy. Do not free.
18257 * g_dbus_proxy_get_name_owner:
18258 * @proxy: A #GDBusProxy.
18260 * The unique name that owns the name that @proxy is for or %NULL if
18261 * no-one currently owns that name. You may connect to the
18262 * #GObject::notify signal to track changes to the
18263 * #GDBusProxy:g-name-owner property.
18265 * Returns: The name owner or %NULL if no name owner exists. Free with g_free().
18271 * g_dbus_proxy_get_object_path:
18272 * @proxy: A #GDBusProxy.
18274 * Gets the object path @proxy is for.
18276 * Returns: A string owned by @proxy. Do not free.
18282 * g_dbus_proxy_new:
18283 * @connection: A #GDBusConnection.
18284 * @flags: Flags used when constructing the proxy.
18285 * @info: (allow-none): A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL.
18286 * @name: (allow-none): A bus name (well-known or unique) or %NULL if @connection is not a message bus connection.
18287 * @object_path: An object path.
18288 * @interface_name: A D-Bus interface name.
18289 * @cancellable: (allow-none): A #GCancellable or %NULL.
18290 * @callback: Callback function to invoke when the proxy is ready.
18291 * @user_data: User data to pass to @callback.
18293 * Creates a proxy for accessing @interface_name on the remote object
18294 * at @object_path owned by @name at @connection and asynchronously
18295 * loads D-Bus properties unless the
18296 * %G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES flag is used. Connect to
18297 * the #GDBusProxy::g-properties-changed signal to get notified about
18298 * property changes.
18300 * If the %G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS flag is not set, also sets up
18301 * match rules for signals. Connect to the #GDBusProxy::g-signal signal
18302 * to handle signals from the remote object.
18304 * If @name is a well-known name and the
18305 * %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START and %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START_AT_CONSTRUCTION
18306 * flags aren't set and no name owner currently exists, the message bus
18307 * will be requested to launch a name owner for the name.
18309 * This is a failable asynchronous constructor - when the proxy is
18310 * ready, @callback will be invoked and you can use
18311 * g_dbus_proxy_new_finish() to get the result.
18313 * See g_dbus_proxy_new_sync() and for a synchronous version of this constructor.
18315 * #GDBusProxy is used in this [example][gdbus-wellknown-proxy].
18322 * g_dbus_proxy_new_finish:
18323 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback function passed to g_dbus_proxy_new().
18324 * @error: Return location for error or %NULL.
18326 * Finishes creating a #GDBusProxy.
18328 * Returns: A #GDBusProxy or %NULL if @error is set. Free with g_object_unref().
18334 * g_dbus_proxy_new_for_bus:
18335 * @bus_type: A #GBusType.
18336 * @flags: Flags used when constructing the proxy.
18337 * @info: (allow-none): A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL.
18338 * @name: A bus name (well-known or unique).
18339 * @object_path: An object path.
18340 * @interface_name: A D-Bus interface name.
18341 * @cancellable: (allow-none): A #GCancellable or %NULL.
18342 * @callback: Callback function to invoke when the proxy is ready.
18343 * @user_data: User data to pass to @callback.
18345 * Like g_dbus_proxy_new() but takes a #GBusType instead of a #GDBusConnection.
18347 * #GDBusProxy is used in this [example][gdbus-wellknown-proxy].
18354 * g_dbus_proxy_new_for_bus_finish:
18355 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback function passed to g_dbus_proxy_new_for_bus().
18356 * @error: Return location for error or %NULL.
18358 * Finishes creating a #GDBusProxy.
18360 * Returns: A #GDBusProxy or %NULL if @error is set. Free with g_object_unref().
18366 * g_dbus_proxy_new_for_bus_sync:
18367 * @bus_type: A #GBusType.
18368 * @flags: Flags used when constructing the proxy.
18369 * @info: (allow-none): A #GDBusInterfaceInfo specifying the minimal interface
18370 * that @proxy conforms to or %NULL.
18371 * @name: A bus name (well-known or unique).
18372 * @object_path: An object path.
18373 * @interface_name: A D-Bus interface name.
18374 * @cancellable: (allow-none): A #GCancellable or %NULL.
18375 * @error: Return location for error or %NULL.
18377 * Like g_dbus_proxy_new_sync() but takes a #GBusType instead of a #GDBusConnection.
18379 * #GDBusProxy is used in this [example][gdbus-wellknown-proxy].
18381 * Returns: A #GDBusProxy or %NULL if error is set. Free with g_object_unref().
18387 * g_dbus_proxy_new_sync:
18388 * @connection: A #GDBusConnection.
18389 * @flags: Flags used when constructing the proxy.
18390 * @info: (allow-none): A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL.
18391 * @name: (allow-none): A bus name (well-known or unique) or %NULL if @connection is not a message bus connection.
18392 * @object_path: An object path.
18393 * @interface_name: A D-Bus interface name.
18394 * @cancellable: (allow-none): A #GCancellable or %NULL.
18395 * @error: (allow-none): Return location for error or %NULL.
18397 * Creates a proxy for accessing @interface_name on the remote object
18398 * at @object_path owned by @name at @connection and synchronously
18399 * loads D-Bus properties unless the
18400 * %G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES flag is used.
18402 * If the %G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS flag is not set, also sets up
18403 * match rules for signals. Connect to the #GDBusProxy::g-signal signal
18404 * to handle signals from the remote object.
18406 * If @name is a well-known name and the
18407 * %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START and %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START_AT_CONSTRUCTION
18408 * flags aren't set and no name owner currently exists, the message bus
18409 * will be requested to launch a name owner for the name.
18411 * This is a synchronous failable constructor. See g_dbus_proxy_new()
18412 * and g_dbus_proxy_new_finish() for the asynchronous version.
18414 * #GDBusProxy is used in this [example][gdbus-wellknown-proxy].
18416 * Returns: A #GDBusProxy or %NULL if error is set. Free with g_object_unref().
18422 * g_dbus_proxy_set_cached_property:
18423 * @proxy: A #GDBusProxy
18424 * @property_name: Property name.
18425 * @value: (allow-none): Value for the property or %NULL to remove it from the cache.
18427 * If @value is not %NULL, sets the cached value for the property with
18428 * name @property_name to the value in @value.
18430 * If @value is %NULL, then the cached value is removed from the
18433 * If @proxy has an expected interface (see
18434 * #GDBusProxy:g-interface-info) and @property_name is referenced by
18435 * it, then @value is checked against the type of the property.
18437 * If the @value #GVariant is floating, it is consumed. This allows
18438 * convenient 'inline' use of g_variant_new(), e.g.
18439 * |[<!-- language="C" -->
18440 * g_dbus_proxy_set_cached_property (proxy,
18442 * g_variant_new ("(si)",
18447 * Normally you will not need to use this method since @proxy
18448 * is tracking changes using the
18449 * `org.freedesktop.DBus.Properties.PropertiesChanged`
18450 * D-Bus signal. However, for performance reasons an object may
18451 * decide to not use this signal for some properties and instead
18452 * use a proprietary out-of-band mechanism to transmit changes.
18454 * As a concrete example, consider an object with a property
18455 * `ChatroomParticipants` which is an array of strings. Instead of
18456 * transmitting the same (long) array every time the property changes,
18457 * it is more efficient to only transmit the delta using e.g. signals
18458 * `ChatroomParticipantJoined(String name)` and
18459 * `ChatroomParticipantParted(String name)`.
18466 * g_dbus_proxy_set_default_timeout:
18467 * @proxy: A #GDBusProxy.
18468 * @timeout_msec: Timeout in milliseconds.
18470 * Sets the timeout to use if -1 (specifying default timeout) is
18471 * passed as @timeout_msec in the g_dbus_proxy_call() and
18472 * g_dbus_proxy_call_sync() functions.
18474 * See the #GDBusProxy:g-default-timeout property for more details.
18481 * g_dbus_proxy_set_interface_info:
18482 * @proxy: A #GDBusProxy
18483 * @info: (allow-none): Minimum interface this proxy conforms to or %NULL to unset.
18485 * Ensure that interactions with @proxy conform to the given
18486 * interface. See the #GDBusProxy:g-interface-info property for more
18494 * g_dbus_server_get_client_address:
18495 * @server: A #GDBusServer.
18497 * Gets a D-Bus address string that can be used by clients to connect
18500 * Returns: A D-Bus address string. Do not free, the string is owned
18507 * g_dbus_server_get_flags:
18508 * @server: A #GDBusServer.
18510 * Gets the flags for @server.
18512 * Returns: A set of flags from the #GDBusServerFlags enumeration.
18518 * g_dbus_server_get_guid:
18519 * @server: A #GDBusServer.
18521 * Gets the GUID for @server.
18523 * Returns: A D-Bus GUID. Do not free this string, it is owned by @server.
18529 * g_dbus_server_is_active:
18530 * @server: A #GDBusServer.
18532 * Gets whether @server is active.
18534 * Returns: %TRUE if server is active, %FALSE otherwise.
18540 * g_dbus_server_new_sync:
18541 * @address: A D-Bus address.
18542 * @flags: Flags from the #GDBusServerFlags enumeration.
18543 * @guid: A D-Bus GUID.
18544 * @observer: (allow-none): A #GDBusAuthObserver or %NULL.
18545 * @cancellable: (allow-none): A #GCancellable or %NULL.
18546 * @error: Return location for server or %NULL.
18548 * Creates a new D-Bus server that listens on the first address in
18549 * @address that works.
18551 * Once constructed, you can use g_dbus_server_get_client_address() to
18552 * get a D-Bus address string that clients can use to connect.
18554 * Connect to the #GDBusServer::new-connection signal to handle
18555 * incoming connections.
18557 * The returned #GDBusServer isn't active - you have to start it with
18558 * g_dbus_server_start().
18560 * #GDBusServer is used in this [example][gdbus-peer-to-peer].
18562 * This is a synchronous failable constructor. See
18563 * g_dbus_server_new() for the asynchronous version.
18565 * Returns: A #GDBusServer or %NULL if @error is set. Free with
18566 * g_object_unref().
18572 * g_dbus_server_start:
18573 * @server: A #GDBusServer.
18582 * g_dbus_server_stop:
18583 * @server: A #GDBusServer.
18592 * g_dbus_signal_info_ref:
18593 * @info: A #GDBusSignalInfo
18595 * If @info is statically allocated does nothing. Otherwise increases
18596 * the reference count.
18598 * Returns: The same @info.
18604 * g_dbus_signal_info_unref:
18605 * @info: A #GDBusSignalInfo.
18607 * If @info is statically allocated, does nothing. Otherwise decreases
18608 * the reference count of @info. When its reference count drops to 0,
18609 * the memory used is freed.
18616 * g_desktop_app_info_get_action_name:
18617 * @info: a #GDesktopAppInfo
18618 * @action_name: the name of the action as from
18619 * g_desktop_app_info_list_actions()
18621 * Gets the user-visible display name of the "additional application
18622 * action" specified by @action_name.
18624 * This corresponds to the "Name" key within the keyfile group for the
18627 * Returns: (transfer full): the locale-specific action name
18633 * g_desktop_app_info_get_boolean:
18634 * @info: a #GDesktopAppInfo
18635 * @key: the key to look up
18637 * Looks up a boolean value in the keyfile backing @info.
18639 * The @key is looked up in the "Desktop Entry" group.
18641 * Returns: the boolean value, or %FALSE if the key
18648 * g_desktop_app_info_get_categories:
18649 * @info: a #GDesktopAppInfo
18651 * Gets the categories from the desktop file.
18653 * Returns: The unparsed Categories key from the desktop file;
18654 * i.e. no attempt is made to split it by ';' or validate it.
18659 * g_desktop_app_info_get_filename:
18660 * @info: a #GDesktopAppInfo
18662 * When @info was created from a known filename, return it. In some
18663 * situations such as the #GDesktopAppInfo returned from
18664 * g_desktop_app_info_new_from_keyfile(), this function will return %NULL.
18666 * Returns: The full path to the file for @info, or %NULL if not known.
18672 * g_desktop_app_info_get_generic_name:
18673 * @info: a #GDesktopAppInfo
18675 * Gets the generic name from the destkop file.
18677 * Returns: The value of the GenericName key
18682 * g_desktop_app_info_get_implementations:
18683 * @interface: the name of the interface
18685 * Gets all applications that implement @interface.
18687 * An application implements an interface if that interface is listed in
18688 * the Implements= line of the desktop file of the application.
18695 * g_desktop_app_info_get_is_hidden:
18696 * @info: a #GDesktopAppInfo.
18698 * A desktop file is hidden if the Hidden key in it is
18701 * Returns: %TRUE if hidden, %FALSE otherwise.
18706 * g_desktop_app_info_get_keywords:
18707 * @info: a #GDesktopAppInfo
18709 * Gets the keywords from the desktop file.
18711 * Returns: (transfer none): The value of the Keywords key
18717 * g_desktop_app_info_get_nodisplay:
18718 * @info: a #GDesktopAppInfo
18720 * Gets the value of the NoDisplay key, which helps determine if the
18721 * application info should be shown in menus. See
18722 * #G_KEY_FILE_DESKTOP_KEY_NO_DISPLAY and g_app_info_should_show().
18724 * Returns: The value of the NoDisplay key
18730 * g_desktop_app_info_get_show_in:
18731 * @info: a #GDesktopAppInfo
18732 * @desktop_env: (nullable): a string specifying a desktop name
18734 * Checks if the application info should be shown in menus that list available
18735 * applications for a specific name of the desktop, based on the
18736 * `OnlyShowIn` and `NotShowIn` keys.
18738 * @desktop_env should typically be given as %NULL, in which case the
18739 * `XDG_CURRENT_DESKTOP` environment variable is consulted. If you want
18740 * to override the default mechanism then you may specify @desktop_env,
18741 * but this is not recommended.
18743 * Note that g_app_info_should_show() for @info will include this check (with
18744 * %NULL for @desktop_env) as well as additional checks.
18746 * Returns: %TRUE if the @info should be shown in @desktop_env according to the
18747 * `OnlyShowIn` and `NotShowIn` keys, %FALSE
18754 * g_desktop_app_info_get_startup_wm_class:
18755 * @info: a #GDesktopAppInfo that supports startup notify
18757 * Retrieves the StartupWMClass field from @info. This represents the
18758 * WM_CLASS property of the main window of the application, if launched
18761 * Returns: (transfer none): the startup WM class, or %NULL if none is set
18762 * in the desktop file.
18768 * g_desktop_app_info_get_string:
18769 * @info: a #GDesktopAppInfo
18770 * @key: the key to look up
18772 * Looks up a string value in the keyfile backing @info.
18774 * The @key is looked up in the "Desktop Entry" group.
18776 * Returns: a newly allocated string, or %NULL if the key
18783 * g_desktop_app_info_has_key:
18784 * @info: a #GDesktopAppInfo
18785 * @key: the key to look up
18787 * Returns whether @key exists in the "Desktop Entry" group
18788 * of the keyfile backing @info.
18790 * Returns: %TRUE if the @key exists
18796 * g_desktop_app_info_launch_action:
18797 * @info: a #GDesktopAppInfo
18798 * @action_name: the name of the action as from
18799 * g_desktop_app_info_list_actions()
18800 * @launch_context: (allow-none): a #GAppLaunchContext
18802 * Activates the named application action.
18804 * You may only call this function on action names that were
18805 * returned from g_desktop_app_info_list_actions().
18807 * Note that if the main entry of the desktop file indicates that the
18808 * application supports startup notification, and @launch_context is
18809 * non-%NULL, then startup notification will be used when activating the
18810 * action (and as such, invocation of the action on the receiving side
18811 * must signal the end of startup notification when it is completed).
18812 * This is the expected behaviour of applications declaring additional
18813 * actions, as per the desktop file specification.
18815 * As with g_app_info_launch() there is no way to detect failures that
18816 * occur while using this function.
18823 * g_desktop_app_info_launch_uris_as_manager:
18824 * @appinfo: a #GDesktopAppInfo
18825 * @uris: (element-type utf8): List of URIs
18826 * @launch_context: (allow-none): a #GAppLaunchContext
18827 * @spawn_flags: #GSpawnFlags, used for each process
18828 * @user_setup: (scope call) (allow-none): a #GSpawnChildSetupFunc, used once
18829 * for each process.
18830 * @user_setup_data: (closure user_setup) (allow-none): User data for @user_setup
18831 * @pid_callback: (scope call) (allow-none): Callback for child processes
18832 * @pid_callback_data: (closure pid_callback) (allow-none): User data for @callback
18833 * @error: return location for a #GError, or %NULL
18835 * This function performs the equivalent of g_app_info_launch_uris(),
18836 * but is intended primarily for operating system components that
18837 * launch applications. Ordinary applications should use
18838 * g_app_info_launch_uris().
18840 * If the application is launched via traditional UNIX fork()/exec()
18841 * then @spawn_flags, @user_setup and @user_setup_data are used for the
18842 * call to g_spawn_async(). Additionally, @pid_callback (with
18843 * @pid_callback_data) will be called to inform about the PID of the
18846 * If application launching occurs via some other mechanism (eg: D-Bus
18847 * activation) then @spawn_flags, @user_setup, @user_setup_data,
18848 * @pid_callback and @pid_callback_data are ignored.
18850 * Returns: %TRUE on successful launch, %FALSE otherwise.
18855 * g_desktop_app_info_list_actions:
18856 * @info: a #GDesktopAppInfo
18858 * Returns the list of "additional application actions" supported on the
18859 * desktop file, as per the desktop file specification.
18861 * As per the specification, this is the list of actions that are
18862 * explicitly listed in the "Actions" key of the [Desktop Entry] group.
18864 * Returns: (array zero-terminated=1) (element-type utf8) (transfer none): a list of strings, always non-%NULL
18870 * g_desktop_app_info_lookup_get_default_for_uri_scheme:
18871 * @lookup: a #GDesktopAppInfoLookup
18872 * @uri_scheme: a string containing a URI scheme.
18874 * Gets the default application for launching applications
18875 * using this URI scheme for a particular GDesktopAppInfoLookup
18878 * The GDesktopAppInfoLookup interface and this function is used
18879 * to implement g_app_info_get_default_for_uri_scheme() backends
18880 * in a GIO module. There is no reason for applications to use it
18881 * directly. Applications should use g_app_info_get_default_for_uri_scheme().
18883 * Returns: (transfer full): #GAppInfo for given @uri_scheme or %NULL on error.
18884 * Deprecated: The #GDesktopAppInfoLookup interface is deprecated and unused by gio.
18889 * g_desktop_app_info_new:
18890 * @desktop_id: the desktop file id
18892 * Creates a new #GDesktopAppInfo based on a desktop file id.
18894 * A desktop file id is the basename of the desktop file, including the
18895 * .desktop extension. GIO is looking for a desktop file with this name
18896 * in the `applications` subdirectories of the XDG
18897 * data directories (i.e. the directories specified in the `XDG_DATA_HOME`
18898 * and `XDG_DATA_DIRS` environment variables). GIO also supports the
18899 * prefix-to-subdirectory mapping that is described in the
18900 * [Menu Spec](http://standards.freedesktop.org/menu-spec/latest/)
18901 * (i.e. a desktop id of kde-foo.desktop will match
18902 * `/usr/share/applications/kde/foo.desktop`).
18904 * Returns: a new #GDesktopAppInfo, or %NULL if no desktop file with that id
18909 * g_desktop_app_info_new_from_filename:
18910 * @filename: the path of a desktop file, in the GLib filename encoding
18912 * Creates a new #GDesktopAppInfo.
18914 * Returns: a new #GDesktopAppInfo or %NULL on error.
18919 * g_desktop_app_info_new_from_keyfile:
18920 * @key_file: an opened #GKeyFile
18922 * Creates a new #GDesktopAppInfo.
18924 * Returns: a new #GDesktopAppInfo or %NULL on error.
18930 * g_desktop_app_info_search:
18931 * @search_string: the search string to use
18933 * Searches desktop files for ones that match @search_string.
18935 * The return value is an array of strvs. Each strv contains a list of
18936 * applications that matched @search_string with an equal score. The
18937 * outer list is sorted by score so that the first strv contains the
18938 * best-matching applications, and so on.
18939 * The algorithm for determining matches is undefined and may change at
18942 * Returns: (array zero-terminated=1) (element-type GStrv) (transfer full): a
18943 * list of strvs. Free each item with g_strfreev() and free the outer
18944 * list with g_free().
18949 * g_desktop_app_info_set_desktop_env:
18950 * @desktop_env: a string specifying what desktop this is
18952 * Sets the name of the desktop that the application is running in.
18953 * This is used by g_app_info_should_show() and
18954 * g_desktop_app_info_get_show_in() to evaluate the
18955 * `OnlyShowIn` and `NotShowIn`
18956 * desktop entry fields.
18958 * Should be called only once; subsequent calls are ignored.
18960 * Deprecated: 2.42: do not use this API. Since 2.42 the value of the
18961 * `XDG_CURRENT_DESKTOP` environment variable will be used.
18966 * g_drive_can_eject:
18967 * @drive: a #GDrive.
18969 * Checks if a drive can be ejected.
18971 * Returns: %TRUE if the @drive can be ejected, %FALSE otherwise.
18976 * g_drive_can_poll_for_media:
18977 * @drive: a #GDrive.
18979 * Checks if a drive can be polled for media changes.
18981 * Returns: %TRUE if the @drive can be polled for media changes,
18982 * %FALSE otherwise.
18987 * g_drive_can_start:
18988 * @drive: a #GDrive.
18990 * Checks if a drive can be started.
18992 * Returns: %TRUE if the @drive can be started, %FALSE otherwise.
18998 * g_drive_can_start_degraded:
18999 * @drive: a #GDrive.
19001 * Checks if a drive can be started degraded.
19003 * Returns: %TRUE if the @drive can be started degraded, %FALSE otherwise.
19009 * g_drive_can_stop:
19010 * @drive: a #GDrive.
19012 * Checks if a drive can be stopped.
19014 * Returns: %TRUE if the @drive can be stopped, %FALSE otherwise.
19021 * @drive: a #GDrive.
19022 * @flags: flags affecting the unmount if required for eject
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 ejects a drive.
19029 * When the operation is finished, @callback will be called.
19030 * You can then call g_drive_eject_finish() to obtain the
19031 * result of the operation.
19033 * Deprecated: 2.22: Use g_drive_eject_with_operation() instead.
19038 * g_drive_eject_finish:
19039 * @drive: a #GDrive.
19040 * @result: a #GAsyncResult.
19041 * @error: a #GError, or %NULL
19043 * Finishes ejecting a drive.
19045 * Returns: %TRUE if the drive has been ejected successfully,
19046 * %FALSE otherwise.
19047 * Deprecated: 2.22: Use g_drive_eject_with_operation_finish() instead.
19052 * g_drive_eject_with_operation:
19053 * @drive: a #GDrive.
19054 * @flags: flags affecting the unmount if required for eject
19055 * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid
19056 * user interaction.
19057 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
19058 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
19059 * @user_data: user data passed to @callback.
19061 * Ejects a drive. This is an asynchronous operation, and is
19062 * finished by calling g_drive_eject_with_operation_finish() with the @drive
19063 * and #GAsyncResult data returned in the @callback.
19070 * g_drive_eject_with_operation_finish:
19071 * @drive: a #GDrive.
19072 * @result: a #GAsyncResult.
19073 * @error: a #GError location to store the error occurring, or %NULL to
19076 * Finishes ejecting a drive. If any errors occurred during the operation,
19077 * @error will be set to contain the errors and %FALSE will be returned.
19079 * Returns: %TRUE if the drive was successfully ejected. %FALSE otherwise.
19085 * g_drive_enumerate_identifiers:
19086 * @drive: a #GDrive
19088 * Gets the kinds of identifiers that @drive has.
19089 * Use g_drive_get_identifier() to obtain the identifiers
19092 * Returns: (transfer full) (array zero-terminated=1): a %NULL-terminated
19093 * array of strings containing kinds of identifiers. Use g_strfreev()
19099 * g_drive_get_icon:
19100 * @drive: a #GDrive.
19102 * Gets the icon for @drive.
19104 * Returns: (transfer full): #GIcon for the @drive.
19105 * Free the returned object with g_object_unref().
19110 * g_drive_get_identifier:
19111 * @drive: a #GDrive
19112 * @kind: the kind of identifier to return
19114 * Gets the identifier of the given kind for @drive.
19116 * Returns: a newly allocated string containing the
19117 * requested identfier, or %NULL if the #GDrive
19118 * doesn't have this kind of identifier.
19123 * g_drive_get_name:
19124 * @drive: a #GDrive.
19126 * Gets the name of @drive.
19128 * Returns: a string containing @drive's name. The returned
19129 * string should be freed when no longer needed.
19134 * g_drive_get_sort_key:
19135 * @drive: A #GDrive.
19137 * Gets the sort key for @drive, if any.
19139 * Returns: Sorting key for @drive or %NULL if no such key is available.
19145 * g_drive_get_start_stop_type:
19146 * @drive: a #GDrive.
19148 * Gets a hint about how a drive can be started/stopped.
19150 * Returns: A value from the #GDriveStartStopType enumeration.
19156 * g_drive_get_symbolic_icon:
19157 * @drive: a #GDrive.
19159 * Gets the icon for @drive.
19161 * Returns: (transfer full): symbolic #GIcon for the @drive.
19162 * Free the returned object with g_object_unref().
19168 * g_drive_get_volumes:
19169 * @drive: a #GDrive.
19171 * Get a list of mountable volumes for @drive.
19173 * The returned list should be freed with g_list_free(), after
19174 * its elements have been unreffed with g_object_unref().
19176 * Returns: (element-type GVolume) (transfer full): #GList containing any #GVolume objects on the given @drive.
19181 * g_drive_has_media:
19182 * @drive: a #GDrive.
19184 * Checks if the @drive has media. Note that the OS may not be polling
19185 * the drive for media changes; see g_drive_is_media_check_automatic()
19186 * for more details.
19188 * Returns: %TRUE if @drive has media, %FALSE otherwise.
19193 * g_drive_has_volumes:
19194 * @drive: a #GDrive.
19196 * Check if @drive has any mountable volumes.
19198 * Returns: %TRUE if the @drive contains volumes, %FALSE otherwise.
19203 * g_drive_is_media_check_automatic:
19204 * @drive: a #GDrive.
19206 * Checks if @drive is capabable of automatically detecting media changes.
19208 * Returns: %TRUE if the @drive is capabable of automatically detecting
19209 * media changes, %FALSE otherwise.
19214 * g_drive_is_media_removable:
19215 * @drive: a #GDrive.
19217 * Checks if the @drive supports removable media.
19219 * Returns: %TRUE if @drive supports removable media, %FALSE otherwise.
19224 * g_drive_poll_for_media:
19225 * @drive: a #GDrive.
19226 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
19227 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
19228 * @user_data: user data to pass to @callback
19230 * Asynchronously polls @drive to see if media has been inserted or removed.
19232 * When the operation is finished, @callback will be called.
19233 * You can then call g_drive_poll_for_media_finish() to obtain the
19234 * result of the operation.
19239 * g_drive_poll_for_media_finish:
19240 * @drive: a #GDrive.
19241 * @result: a #GAsyncResult.
19242 * @error: a #GError, or %NULL
19244 * Finishes an operation started with g_drive_poll_for_media() on a drive.
19246 * Returns: %TRUE if the drive has been poll_for_mediaed successfully,
19247 * %FALSE otherwise.
19253 * @drive: a #GDrive.
19254 * @flags: flags affecting the start operation.
19255 * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid
19256 * user interaction.
19257 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
19258 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
19259 * @user_data: user data to pass to @callback
19261 * Asynchronously starts a drive.
19263 * When the operation is finished, @callback will be called.
19264 * You can then call g_drive_start_finish() to obtain the
19265 * result of the operation.
19272 * g_drive_start_finish:
19273 * @drive: a #GDrive.
19274 * @result: a #GAsyncResult.
19275 * @error: a #GError, or %NULL
19277 * Finishes starting a drive.
19279 * Returns: %TRUE if the drive has been started successfully,
19280 * %FALSE otherwise.
19287 * @drive: a #GDrive.
19288 * @flags: flags affecting the unmount if required for stopping.
19289 * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid
19290 * user interaction.
19291 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
19292 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
19293 * @user_data: user data to pass to @callback
19295 * Asynchronously stops a drive.
19297 * When the operation is finished, @callback will be called.
19298 * You can then call g_drive_stop_finish() to obtain the
19299 * result of the operation.
19306 * g_drive_stop_finish:
19307 * @drive: a #GDrive.
19308 * @result: a #GAsyncResult.
19309 * @error: a #GError, or %NULL
19311 * Finishes stopping a drive.
19313 * Returns: %TRUE if the drive has been stopped successfully,
19314 * %FALSE otherwise.
19320 * g_emblem_get_icon:
19321 * @emblem: a #GEmblem from which the icon should be extracted.
19323 * Gives back the icon from @emblem.
19325 * Returns: (transfer none): a #GIcon. The returned object belongs to
19326 * the emblem and should not be modified or freed.
19332 * g_emblem_get_origin:
19333 * @emblem: a #GEmblem
19335 * Gets the origin of the emblem.
19337 * Returns: (transfer none): the origin of the emblem
19344 * @icon: a GIcon containing the icon.
19346 * Creates a new emblem for @icon.
19348 * Returns: a new #GEmblem.
19354 * g_emblem_new_with_origin:
19355 * @icon: a GIcon containing the icon.
19356 * @origin: a GEmblemOrigin enum defining the emblem's origin
19358 * Creates a new emblem for @icon.
19360 * Returns: a new #GEmblem.
19366 * g_emblemed_icon_add_emblem:
19367 * @emblemed: a #GEmblemedIcon
19368 * @emblem: a #GEmblem
19370 * Adds @emblem to the #GList of #GEmblems.
19377 * g_emblemed_icon_clear_emblems:
19378 * @emblemed: a #GEmblemedIcon
19380 * Removes all the emblems from @icon.
19387 * g_emblemed_icon_get_emblems:
19388 * @emblemed: a #GEmblemedIcon
19390 * Gets the list of emblems for the @icon.
19392 * Returns: (element-type Gio.Emblem) (transfer none): a #GList of
19393 * #GEmblems that is owned by @emblemed
19399 * g_emblemed_icon_get_icon:
19400 * @emblemed: a #GEmblemedIcon
19402 * Gets the main icon for @emblemed.
19404 * Returns: (transfer none): a #GIcon that is owned by @emblemed
19410 * g_emblemed_icon_new:
19412 * @emblem: (allow-none): a #GEmblem, or %NULL
19414 * Creates a new emblemed icon for @icon with the emblem @emblem.
19416 * Returns: (transfer full) (type GEmblemedIcon): a new #GIcon
19422 * g_file_append_to:
19423 * @file: input #GFile
19424 * @flags: a set of #GFileCreateFlags
19425 * @cancellable: (allow-none): optional #GCancellable object,
19427 * @error: a #GError, or %NULL
19429 * Gets an output stream for appending data to the file.
19430 * If the file doesn't already exist it is created.
19432 * By default files created are generally readable by everyone,
19433 * but if you pass #G_FILE_CREATE_PRIVATE in @flags the file
19434 * will be made readable only to the current user, to the level that
19435 * is supported on the target filesystem.
19437 * If @cancellable is not %NULL, then the operation can be cancelled
19438 * by triggering the cancellable object from another thread. If the
19439 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
19442 * Some file systems don't allow all file names, and may return an
19443 * %G_IO_ERROR_INVALID_FILENAME error. If the file is a directory the
19444 * %G_IO_ERROR_IS_DIRECTORY error will be returned. Other errors are
19445 * possible too, and depend on what kind of filesystem the file is on.
19447 * Returns: (transfer full): a #GFileOutputStream, or %NULL on error.
19448 * Free the returned object with g_object_unref().
19453 * g_file_append_to_async:
19454 * @file: input #GFile
19455 * @flags: a set of #GFileCreateFlags
19456 * @io_priority: the [I/O priority][io-priority] of the request
19457 * @cancellable: (allow-none): optional #GCancellable object,
19459 * @callback: (scope async): a #GAsyncReadyCallback to call
19460 * when the request is satisfied
19461 * @user_data: (closure): the data to pass to callback function
19463 * Asynchronously opens @file for appending.
19465 * For more details, see g_file_append_to() which is
19466 * the synchronous version of this call.
19468 * When the operation is finished, @callback will be called.
19469 * You can then call g_file_append_to_finish() to get the result
19470 * of the operation.
19475 * g_file_append_to_finish:
19476 * @file: input #GFile
19477 * @res: #GAsyncResult
19478 * @error: a #GError, or %NULL
19480 * Finishes an asynchronous file append operation started with
19481 * g_file_append_to_async().
19483 * Returns: (transfer full): a valid #GFileOutputStream
19484 * or %NULL on error.
19485 * Free the returned object with g_object_unref().
19490 * g_file_attribute_info_list_add:
19491 * @list: a #GFileAttributeInfoList.
19492 * @name: the name of the attribute to add.
19493 * @type: the #GFileAttributeType for the attribute.
19494 * @flags: #GFileAttributeInfoFlags for the attribute.
19496 * Adds a new attribute with @name to the @list, setting
19497 * its @type and @flags.
19502 * g_file_attribute_info_list_dup:
19503 * @list: a #GFileAttributeInfoList to duplicate.
19505 * Makes a duplicate of a file attribute info list.
19507 * Returns: a copy of the given @list.
19512 * g_file_attribute_info_list_lookup:
19513 * @list: a #GFileAttributeInfoList.
19514 * @name: the name of the attribute to lookup.
19516 * Gets the file attribute with the name @name from @list.
19518 * Returns: a #GFileAttributeInfo for the @name, or %NULL if an
19519 * attribute isn't found.
19524 * g_file_attribute_info_list_new:
19526 * Creates a new file attribute info list.
19528 * Returns: a #GFileAttributeInfoList.
19533 * g_file_attribute_info_list_ref:
19534 * @list: a #GFileAttributeInfoList to reference.
19536 * References a file attribute info list.
19538 * Returns: #GFileAttributeInfoList or %NULL on error.
19543 * g_file_attribute_info_list_unref:
19544 * @list: The #GFileAttributeInfoList to unreference.
19546 * Removes a reference from the given @list. If the reference count
19547 * falls to zero, the @list is deleted.
19552 * g_file_attribute_matcher_enumerate_namespace:
19553 * @matcher: a #GFileAttributeMatcher.
19554 * @ns: a string containing a file attribute namespace.
19556 * Checks if the matcher will match all of the keys in a given namespace.
19557 * This will always return %TRUE if a wildcard character is in use (e.g. if
19558 * matcher was created with "standard::*" and @ns is "standard", or if matcher was created
19559 * using "*" and namespace is anything.)
19561 * TODO: this is awkwardly worded.
19563 * Returns: %TRUE if the matcher matches all of the entries
19564 * in the given @ns, %FALSE otherwise.
19569 * g_file_attribute_matcher_enumerate_next:
19570 * @matcher: a #GFileAttributeMatcher.
19572 * Gets the next matched attribute from a #GFileAttributeMatcher.
19574 * Returns: a string containing the next attribute or %NULL if
19575 * no more attribute exist.
19580 * g_file_attribute_matcher_matches:
19581 * @matcher: a #GFileAttributeMatcher.
19582 * @attribute: a file attribute key.
19584 * Checks if an attribute will be matched by an attribute matcher. If
19585 * the matcher was created with the "*" matching string, this function
19586 * will always return %TRUE.
19588 * Returns: %TRUE if @attribute matches @matcher. %FALSE otherwise.
19593 * g_file_attribute_matcher_matches_only:
19594 * @matcher: a #GFileAttributeMatcher.
19595 * @attribute: a file attribute key.
19597 * Checks if a attribute matcher only matches a given attribute. Always
19598 * returns %FALSE if "*" was used when creating the matcher.
19600 * Returns: %TRUE if the matcher only matches @attribute. %FALSE otherwise.
19605 * g_file_attribute_matcher_new:
19606 * @attributes: an attribute string to match.
19608 * Creates a new file attribute matcher, which matches attributes
19609 * against a given string. #GFileAttributeMatchers are reference
19610 * counted structures, and are created with a reference count of 1. If
19611 * the number of references falls to 0, the #GFileAttributeMatcher is
19612 * automatically destroyed.
19614 * The @attribute string should be formatted with specific keys separated
19615 * from namespaces with a double colon. Several "namespace::key" strings may be
19616 * concatenated with a single comma (e.g. "standard::type,standard::is-hidden").
19617 * The wildcard "*" may be used to match all keys and namespaces, or
19618 * "namespace::*" will match all keys in a given namespace.
19620 * ## Examples of file attribute matcher strings and results
19622 * - `"*"`: matches all attributes.
19623 * - `"standard::is-hidden"`: matches only the key is-hidden in the
19624 * standard namespace.
19625 * - `"standard::type,unix::*"`: matches the type key in the standard
19626 * namespace and all keys in the unix namespace.
19628 * Returns: a #GFileAttributeMatcher
19633 * g_file_attribute_matcher_ref:
19634 * @matcher: a #GFileAttributeMatcher.
19636 * References a file attribute matcher.
19638 * Returns: a #GFileAttributeMatcher.
19643 * g_file_attribute_matcher_subtract:
19644 * @matcher: Matcher to subtract from
19645 * @subtract: The matcher to subtract
19647 * Subtracts all attributes of @subtract from @matcher and returns
19648 * a matcher that supports those attributes.
19650 * Note that currently it is not possible to remove a single
19651 * attribute when the @matcher matches the whole namespace - or remove
19652 * a namespace or attribute when the matcher matches everything. This
19653 * is a limitation of the current implementation, but may be fixed
19656 * Returns: A file attribute matcher matching all attributes of
19657 * @matcher that are not matched by @subtract
19662 * g_file_attribute_matcher_to_string:
19663 * @matcher: (allow-none): a #GFileAttributeMatcher.
19665 * Prints what the matcher is matching against. The format will be
19666 * equal to the format passed to g_file_attribute_matcher_new().
19667 * The output however, might not be identical, as the matcher may
19668 * decide to use a different order or omit needless parts.
19670 * Returns: a string describing the attributes the matcher matches
19671 * against or %NULL if @matcher was %NULL.
19677 * g_file_attribute_matcher_unref:
19678 * @matcher: a #GFileAttributeMatcher.
19680 * Unreferences @matcher. If the reference count falls below 1,
19681 * the @matcher is automatically freed.
19686 * g_file_attribute_value_dup:
19687 * @other: a #GFileAttributeValue to duplicate.
19689 * Duplicates a file attribute.
19691 * Returns: a duplicate of the @other.
19696 * g_file_attribute_value_set:
19697 * @attr: a #GFileAttributeValue to set the value in.
19698 * @new_value: a #GFileAttributeValue to get the value from.
19700 * Sets an attribute's value from another attribute.
19706 * @source: input #GFile
19707 * @destination: destination #GFile
19708 * @flags: set of #GFileCopyFlags
19709 * @cancellable: (allow-none): optional #GCancellable object,
19711 * @progress_callback: (allow-none) (scope call): function to callback with
19712 * progress information, or %NULL if progress information is not needed
19713 * @progress_callback_data: (closure): user data to pass to @progress_callback
19714 * @error: #GError to set on error, or %NULL
19716 * Copies the file @source to the location specified by @destination.
19717 * Can not handle recursive copies of directories.
19719 * If the flag #G_FILE_COPY_OVERWRITE is specified an already
19720 * existing @destination file is overwritten.
19722 * If the flag #G_FILE_COPY_NOFOLLOW_SYMLINKS is specified then symlinks
19723 * will be copied as symlinks, otherwise the target of the
19724 * @source symlink will be copied.
19726 * If @cancellable is not %NULL, then the operation can be cancelled by
19727 * triggering the cancellable object from another thread. If the operation
19728 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
19730 * If @progress_callback is not %NULL, then the operation can be monitored
19731 * by setting this to a #GFileProgressCallback function.
19732 * @progress_callback_data will be passed to this function. It is guaranteed
19733 * that this callback will be called after all data has been transferred with
19734 * the total number of bytes copied during the operation.
19736 * If the @source file does not exist, then the %G_IO_ERROR_NOT_FOUND error
19737 * is returned, independent on the status of the @destination.
19739 * If #G_FILE_COPY_OVERWRITE is not specified and the target exists, then
19740 * the error %G_IO_ERROR_EXISTS is returned.
19742 * If trying to overwrite a file over a directory, the %G_IO_ERROR_IS_DIRECTORY
19743 * error is returned. If trying to overwrite a directory with a directory the
19744 * %G_IO_ERROR_WOULD_MERGE error is returned.
19746 * If the source is a directory and the target does not exist, or
19747 * #G_FILE_COPY_OVERWRITE is specified and the target is a file, then the
19748 * %G_IO_ERROR_WOULD_RECURSE error is returned.
19750 * If you are interested in copying the #GFile object itself (not the on-disk
19751 * file), see g_file_dup().
19753 * Returns: %TRUE on success, %FALSE otherwise.
19758 * g_file_copy_async: (skip)
19759 * @source: input #GFile
19760 * @destination: destination #GFile
19761 * @flags: set of #GFileCopyFlags
19762 * @io_priority: the [I/O priority][io-priority] of the request
19763 * @cancellable: (allow-none): optional #GCancellable object,
19765 * @progress_callback: (allow-none): function to callback with progress
19766 * information, or %NULL if progress information is not needed
19767 * @progress_callback_data: (closure): user data to pass to @progress_callback
19768 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
19769 * @user_data: the data to pass to callback function
19771 * Copies the file @source to the location specified by @destination
19772 * asynchronously. For details of the behaviour, see g_file_copy().
19774 * If @progress_callback is not %NULL, then that function that will be called
19775 * just like in g_file_copy(). The callback will run in the default main context
19776 * of the thread calling g_file_copy_async() — the same context as @callback is
19779 * When the operation is finished, @callback will be called. You can then call
19780 * g_file_copy_finish() to get the result of the operation.
19785 * g_file_copy_attributes:
19786 * @source: a #GFile with attributes
19787 * @destination: a #GFile to copy attributes to
19788 * @flags: a set of #GFileCopyFlags
19789 * @cancellable: (allow-none): optional #GCancellable object,
19791 * @error: a #GError, %NULL to ignore
19793 * Copies the file attributes from @source to @destination.
19795 * Normally only a subset of the file attributes are copied,
19796 * those that are copies in a normal file copy operation
19797 * (which for instance does not include e.g. owner). However
19798 * if #G_FILE_COPY_ALL_METADATA is specified in @flags, then
19799 * all the metadata that is possible to copy is copied. This
19800 * is useful when implementing move by copy + delete source.
19802 * Returns: %TRUE if the attributes were copied successfully,
19803 * %FALSE otherwise.
19808 * g_file_copy_finish:
19809 * @file: input #GFile
19810 * @res: a #GAsyncResult
19811 * @error: a #GError, or %NULL
19813 * Finishes copying the file started with g_file_copy_async().
19815 * Returns: a %TRUE on success, %FALSE on error.
19821 * @file: input #GFile
19822 * @flags: a set of #GFileCreateFlags
19823 * @cancellable: (allow-none): optional #GCancellable object,
19825 * @error: a #GError, or %NULL
19827 * Creates a new file and returns an output stream for writing to it.
19828 * The file must not already exist.
19830 * By default files created are generally readable by everyone,
19831 * but if you pass #G_FILE_CREATE_PRIVATE in @flags the file
19832 * will be made readable only to the current user, to the level
19833 * that is supported on the target filesystem.
19835 * If @cancellable is not %NULL, then the operation can be cancelled
19836 * by triggering the cancellable object from another thread. If the
19837 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
19840 * If a file or directory with this name already exists the
19841 * %G_IO_ERROR_EXISTS error will be returned. Some file systems don't
19842 * allow all file names, and may return an %G_IO_ERROR_INVALID_FILENAME
19843 * error, and if the name is to long %G_IO_ERROR_FILENAME_TOO_LONG will
19844 * be returned. Other errors are possible too, and depend on what kind
19845 * of filesystem the file is on.
19847 * Returns: (transfer full): a #GFileOutputStream for the newly created
19848 * file, or %NULL on error.
19849 * Free the returned object with g_object_unref().
19854 * g_file_create_async:
19855 * @file: input #GFile
19856 * @flags: a set of #GFileCreateFlags
19857 * @io_priority: the [I/O priority][io-priority] of the request
19858 * @cancellable: (allow-none): optional #GCancellable object,
19860 * @callback: (scope async): a #GAsyncReadyCallback to call
19861 * when the request is satisfied
19862 * @user_data: (closure): the data to pass to callback function
19864 * Asynchronously creates a new file and returns an output stream
19865 * for writing to it. The file must not already exist.
19867 * For more details, see g_file_create() which is
19868 * the synchronous version of this call.
19870 * When the operation is finished, @callback will be called.
19871 * You can then call g_file_create_finish() to get the result
19872 * of the operation.
19877 * g_file_create_finish:
19878 * @file: input #GFile
19879 * @res: a #GAsyncResult
19880 * @error: a #GError, or %NULL
19882 * Finishes an asynchronous file create operation started with
19883 * g_file_create_async().
19885 * Returns: (transfer full): a #GFileOutputStream or %NULL on error.
19886 * Free the returned object with g_object_unref().
19891 * g_file_create_readwrite:
19893 * @flags: a set of #GFileCreateFlags
19894 * @cancellable: (allow-none): optional #GCancellable object,
19896 * @error: return location for a #GError, or %NULL
19898 * Creates a new file and returns a stream for reading and
19899 * writing to it. The file must not already exist.
19901 * By default files created are generally readable by everyone,
19902 * but if you pass #G_FILE_CREATE_PRIVATE in @flags the file
19903 * will be made readable only to the current user, to the level
19904 * that is supported on the target filesystem.
19906 * If @cancellable is not %NULL, then the operation can be cancelled
19907 * by triggering the cancellable object from another thread. If the
19908 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
19911 * If a file or directory with this name already exists, the
19912 * %G_IO_ERROR_EXISTS error will be returned. Some file systems don't
19913 * allow all file names, and may return an %G_IO_ERROR_INVALID_FILENAME
19914 * error, and if the name is too long, %G_IO_ERROR_FILENAME_TOO_LONG
19915 * will be returned. Other errors are possible too, and depend on what
19916 * kind of filesystem the file is on.
19918 * Note that in many non-local file cases read and write streams are
19919 * not supported, so make sure you really need to do read and write
19920 * streaming, rather than just opening for reading or writing.
19922 * Returns: (transfer full): a #GFileIOStream for the newly created
19923 * file, or %NULL on error.
19924 * Free the returned object with g_object_unref().
19930 * g_file_create_readwrite_async:
19931 * @file: input #GFile
19932 * @flags: a set of #GFileCreateFlags
19933 * @io_priority: the [I/O priority][io-priority] of the request
19934 * @cancellable: (allow-none): optional #GCancellable object,
19936 * @callback: (scope async): a #GAsyncReadyCallback to call
19937 * when the request is satisfied
19938 * @user_data: (closure): the data to pass to callback function
19940 * Asynchronously creates a new file and returns a stream
19941 * for reading and writing to it. The file must not already exist.
19943 * For more details, see g_file_create_readwrite() which is
19944 * the synchronous version of this call.
19946 * When the operation is finished, @callback will be called.
19947 * You can then call g_file_create_readwrite_finish() to get
19948 * the result of the operation.
19955 * g_file_create_readwrite_finish:
19956 * @file: input #GFile
19957 * @res: a #GAsyncResult
19958 * @error: a #GError, or %NULL
19960 * Finishes an asynchronous file create operation started with
19961 * g_file_create_readwrite_async().
19963 * Returns: (transfer full): a #GFileIOStream or %NULL on error.
19964 * Free the returned object with g_object_unref().
19970 * g_file_delete: (virtual delete_file)
19971 * @file: input #GFile
19972 * @cancellable: (allow-none): optional #GCancellable object,
19974 * @error: a #GError, or %NULL
19976 * Deletes a file. If the @file is a directory, it will only be
19977 * deleted if it is empty. This has the same semantics as g_unlink().
19979 * If @cancellable is not %NULL, then the operation can be cancelled by
19980 * triggering the cancellable object from another thread. If the operation
19981 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
19983 * Returns: %TRUE if the file was deleted. %FALSE otherwise.
19988 * g_file_delete_async: (virtual delete_file_async)
19989 * @file: input #GFile
19990 * @io_priority: the [I/O priority][io-priority] of the request
19991 * @cancellable: (allow-none): optional #GCancellable object,
19993 * @callback: a #GAsyncReadyCallback to call
19994 * when the request is satisfied
19995 * @user_data: the data to pass to callback function
19997 * Asynchronously delete a file. If the @file is a directory, it will
19998 * only be deleted if it is empty. This has the same semantics as
20006 * g_file_delete_finish: (virtual delete_file_finish)
20007 * @file: input #GFile
20008 * @result: a #GAsyncResult
20009 * @error: a #GError, or %NULL
20011 * Finishes deleting a file started with g_file_delete_async().
20013 * Returns: %TRUE if the file was deleted. %FALSE otherwise.
20019 * g_file_descriptor_based_get_fd:
20020 * @fd_based: a #GFileDescriptorBased.
20022 * Gets the underlying file descriptor.
20024 * Returns: The file descriptor
20031 * @file: input #GFile
20033 * Duplicates a #GFile handle. This operation does not duplicate
20034 * the actual file or directory represented by the #GFile; see
20035 * g_file_copy() if attempting to copy a file.
20037 * This call does no blocking I/O.
20039 * Returns: (transfer full): a new #GFile that is a duplicate
20040 * of the given #GFile.
20045 * g_file_eject_mountable:
20046 * @file: input #GFile
20047 * @flags: flags affecting the operation
20048 * @cancellable: (allow-none): optional #GCancellable object,
20050 * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call
20051 * when the request is satisfied, or %NULL
20052 * @user_data: (closure): the data to pass to callback function
20054 * Starts an asynchronous eject on a mountable.
20055 * When this operation has completed, @callback will be called with
20056 * @user_user data, and the operation can be finalized with
20057 * g_file_eject_mountable_finish().
20059 * If @cancellable is not %NULL, then the operation can be cancelled by
20060 * triggering the cancellable object from another thread. If the operation
20061 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
20063 * Deprecated: 2.22: Use g_file_eject_mountable_with_operation() instead.
20068 * g_file_eject_mountable_finish:
20069 * @file: input #GFile
20070 * @result: a #GAsyncResult
20071 * @error: a #GError, or %NULL
20073 * Finishes an asynchronous eject operation started by
20074 * g_file_eject_mountable().
20076 * Returns: %TRUE if the @file was ejected successfully.
20077 * %FALSE otherwise.
20078 * Deprecated: 2.22: Use g_file_eject_mountable_with_operation_finish()
20084 * g_file_eject_mountable_with_operation:
20085 * @file: input #GFile
20086 * @flags: flags affecting the operation
20087 * @mount_operation: (allow-none): a #GMountOperation,
20088 * or %NULL to avoid user interaction
20089 * @cancellable: (allow-none): optional #GCancellable object,
20091 * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call
20092 * when the request is satisfied, or %NULL
20093 * @user_data: (closure): the data to pass to callback function
20095 * Starts an asynchronous eject on a mountable.
20096 * When this operation has completed, @callback will be called with
20097 * @user_user data, and the operation can be finalized with
20098 * g_file_eject_mountable_with_operation_finish().
20100 * If @cancellable is not %NULL, then the operation can be cancelled by
20101 * triggering the cancellable object from another thread. If the operation
20102 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
20109 * g_file_eject_mountable_with_operation_finish:
20110 * @file: input #GFile
20111 * @result: a #GAsyncResult
20112 * @error: a #GError, or %NULL
20114 * Finishes an asynchronous eject operation started by
20115 * g_file_eject_mountable_with_operation().
20117 * Returns: %TRUE if the @file was ejected successfully.
20118 * %FALSE otherwise.
20124 * g_file_enumerate_children:
20125 * @file: input #GFile
20126 * @attributes: an attribute query string
20127 * @flags: a set of #GFileQueryInfoFlags
20128 * @cancellable: (allow-none): optional #GCancellable object,
20130 * @error: #GError for error reporting
20132 * Gets the requested information about the files in a directory.
20133 * The result is a #GFileEnumerator object that will give out
20134 * #GFileInfo objects for all the files in the directory.
20136 * The @attributes value is a string that specifies the file
20137 * attributes that should be gathered. It is not an error if
20138 * it's not possible to read a particular requested attribute
20139 * from a file - it just won't be set. @attributes should
20140 * be a comma-separated list of attributes or attribute wildcards.
20141 * The wildcard "*" means all attributes, and a wildcard like
20142 * "standard::*" means all attributes in the standard namespace.
20143 * An example attribute query be "standard::*,owner::user".
20144 * The standard attributes are available as defines, like
20145 * #G_FILE_ATTRIBUTE_STANDARD_NAME.
20147 * If @cancellable is not %NULL, then the operation can be cancelled
20148 * by triggering the cancellable object from another thread. If the
20149 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
20152 * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will
20153 * be returned. If the file is not a directory, the %G_IO_ERROR_NOT_DIRECTORY
20154 * error will be returned. Other errors are possible too.
20156 * Returns: (transfer full): A #GFileEnumerator if successful,
20157 * %NULL on error. Free the returned object with g_object_unref().
20162 * g_file_enumerate_children_async:
20163 * @file: input #GFile
20164 * @attributes: an attribute query string
20165 * @flags: a set of #GFileQueryInfoFlags
20166 * @io_priority: the [I/O priority][io-priority] of the request
20167 * @cancellable: (allow-none): optional #GCancellable object,
20169 * @callback: (scope async): a #GAsyncReadyCallback to call when the
20170 * request is satisfied
20171 * @user_data: (closure): the data to pass to callback function
20173 * Asynchronously gets the requested information about the files
20174 * in a directory. The result is a #GFileEnumerator object that will
20175 * give out #GFileInfo objects for all the files in the directory.
20177 * For more details, see g_file_enumerate_children() which is
20178 * the synchronous version of this call.
20180 * When the operation is finished, @callback will be called. You can
20181 * then call g_file_enumerate_children_finish() to get the result of
20187 * g_file_enumerate_children_finish:
20188 * @file: input #GFile
20189 * @res: a #GAsyncResult
20190 * @error: a #GError
20192 * Finishes an async enumerate children operation.
20193 * See g_file_enumerate_children_async().
20195 * Returns: (transfer full): a #GFileEnumerator or %NULL
20196 * if an error occurred.
20197 * Free the returned object with g_object_unref().
20202 * g_file_enumerator_close:
20203 * @enumerator: a #GFileEnumerator.
20204 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
20205 * @error: location to store the error occurring, or %NULL to ignore
20207 * Releases all resources used by this enumerator, making the
20208 * enumerator return %G_IO_ERROR_CLOSED on all calls.
20210 * This will be automatically called when the last reference
20211 * is dropped, but you might want to call this function to make
20212 * sure resources are released as early as possible.
20214 * Returns: #TRUE on success or #FALSE on error.
20219 * g_file_enumerator_close_async:
20220 * @enumerator: a #GFileEnumerator.
20221 * @io_priority: the [I/O priority][io-priority] of the request
20222 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
20223 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
20224 * @user_data: (closure): the data to pass to callback function
20226 * Asynchronously closes the file enumerator.
20228 * If @cancellable is not %NULL, then the operation can be cancelled by
20229 * triggering the cancellable object from another thread. If the operation
20230 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned in
20231 * g_file_enumerator_close_finish().
20236 * g_file_enumerator_close_finish:
20237 * @enumerator: a #GFileEnumerator.
20238 * @result: a #GAsyncResult.
20239 * @error: a #GError location to store the error occurring, or %NULL to
20242 * Finishes closing a file enumerator, started from g_file_enumerator_close_async().
20244 * If the file enumerator was already closed when g_file_enumerator_close_async()
20245 * was called, then this function will report %G_IO_ERROR_CLOSED in @error, and
20246 * return %FALSE. If the file enumerator had pending operation when the close
20247 * operation was started, then this function will report %G_IO_ERROR_PENDING, and
20248 * return %FALSE. If @cancellable was not %NULL, then the operation may have been
20249 * cancelled by triggering the cancellable object from another thread. If the operation
20250 * was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %FALSE will be
20253 * Returns: %TRUE if the close operation has finished successfully.
20258 * g_file_enumerator_get_child:
20259 * @enumerator: a #GFileEnumerator
20260 * @info: a #GFileInfo gotten from g_file_enumerator_next_file()
20261 * or the async equivalents.
20263 * Return a new #GFile which refers to the file named by @info in the source
20264 * directory of @enumerator. This function is primarily intended to be used
20265 * inside loops with g_file_enumerator_next_file().
20267 * This is a convenience method that's equivalent to:
20268 * |[<!-- language="C" -->
20269 * gchar *name = g_file_info_get_name (info);
20270 * GFile *child = g_file_get_child (g_file_enumerator_get_container (enumr),
20274 * Returns: (transfer full): a #GFile for the #GFileInfo passed it.
20280 * g_file_enumerator_get_container:
20281 * @enumerator: a #GFileEnumerator
20283 * Get the #GFile container which is being enumerated.
20285 * Returns: (transfer none): the #GFile which is being enumerated.
20291 * g_file_enumerator_has_pending:
20292 * @enumerator: a #GFileEnumerator.
20294 * Checks if the file enumerator has pending operations.
20296 * Returns: %TRUE if the @enumerator has pending operations.
20301 * g_file_enumerator_is_closed:
20302 * @enumerator: a #GFileEnumerator.
20304 * Checks if the file enumerator has been closed.
20306 * Returns: %TRUE if the @enumerator is closed.
20311 * g_file_enumerator_next_file:
20312 * @enumerator: a #GFileEnumerator.
20313 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
20314 * @error: location to store the error occurring, or %NULL to ignore
20316 * Returns information for the next file in the enumerated object.
20317 * Will block until the information is available. The #GFileInfo
20318 * returned from this function will contain attributes that match the
20319 * attribute string that was passed when the #GFileEnumerator was created.
20321 * See the documentation of #GFileEnumerator for information about the
20322 * order of returned files.
20324 * On error, returns %NULL and sets @error to the error. If the
20325 * enumerator is at the end, %NULL will be returned and @error will
20328 * Returns: (nullable) (transfer full): A #GFileInfo or %NULL on error
20329 * or end of enumerator. Free the returned object with
20330 * g_object_unref() when no longer needed.
20335 * g_file_enumerator_next_files_async:
20336 * @enumerator: a #GFileEnumerator.
20337 * @num_files: the number of file info objects to request
20338 * @io_priority: the [I/O priority][io-priority] of the request
20339 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
20340 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
20341 * @user_data: (closure): the data to pass to callback function
20343 * Request information for a number of files from the enumerator asynchronously.
20344 * When all i/o for the operation is finished the @callback will be called with
20345 * the requested information.
20347 * See the documentation of #GFileEnumerator for information about the
20348 * order of returned files.
20350 * The callback can be called with less than @num_files files in case of error
20351 * or at the end of the enumerator. In case of a partial error the callback will
20352 * be called with any succeeding items and no error, and on the next request the
20353 * error will be reported. If a request is cancelled the callback will be called
20354 * with %G_IO_ERROR_CANCELLED.
20356 * During an async request no other sync and async calls are allowed, and will
20357 * result in %G_IO_ERROR_PENDING errors.
20359 * Any outstanding i/o request with higher priority (lower numerical value) will
20360 * be executed before an outstanding request with lower priority. Default
20361 * priority is %G_PRIORITY_DEFAULT.
20366 * g_file_enumerator_next_files_finish:
20367 * @enumerator: a #GFileEnumerator.
20368 * @result: a #GAsyncResult.
20369 * @error: a #GError location to store the error occurring, or %NULL to
20372 * Finishes the asynchronous operation started with g_file_enumerator_next_files_async().
20374 * Returns: (transfer full) (element-type Gio.FileInfo): a #GList of #GFileInfos. You must free the list with
20375 * g_list_free() and unref the infos with g_object_unref() when you're
20381 * g_file_enumerator_set_pending:
20382 * @enumerator: a #GFileEnumerator.
20383 * @pending: a boolean value.
20385 * Sets the file enumerator as having pending operations.
20391 * @file1: the first #GFile
20392 * @file2: the second #GFile
20394 * Checks equality of two given #GFiles.
20396 * Note that two #GFiles that differ can still refer to the same
20397 * file on the filesystem due to various forms of filename
20400 * This call does no blocking I/O.
20402 * Returns: %TRUE if @file1 and @file2 are equal.
20407 * g_file_find_enclosing_mount:
20408 * @file: input #GFile
20409 * @cancellable: (allow-none): optional #GCancellable object,
20411 * @error: a #GError
20413 * Gets a #GMount for the #GFile.
20415 * If the #GFileIface for @file does not have a mount (e.g.
20416 * possibly a remote share), @error will be set to %G_IO_ERROR_NOT_FOUND
20417 * and %NULL will be returned.
20419 * If @cancellable is not %NULL, then the operation can be cancelled by
20420 * triggering the cancellable object from another thread. If the operation
20421 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
20423 * Returns: (transfer full): a #GMount where the @file is located
20424 * or %NULL on error.
20425 * Free the returned object with g_object_unref().
20430 * g_file_find_enclosing_mount_async:
20432 * @io_priority: the [I/O priority][io-priority] of the request
20433 * @cancellable: (allow-none): optional #GCancellable object,
20435 * @callback: (scope async): a #GAsyncReadyCallback to call
20436 * when the request is satisfied
20437 * @user_data: (closure): the data to pass to callback function
20439 * Asynchronously gets the mount for the file.
20441 * For more details, see g_file_find_enclosing_mount() which is
20442 * the synchronous version of this call.
20444 * When the operation is finished, @callback will be called.
20445 * You can then call g_file_find_enclosing_mount_finish() to
20446 * get the result of the operation.
20451 * g_file_find_enclosing_mount_finish:
20453 * @res: a #GAsyncResult
20454 * @error: a #GError
20456 * Finishes an asynchronous find mount request.
20457 * See g_file_find_enclosing_mount_async().
20459 * Returns: (transfer full): #GMount for given @file or %NULL on error.
20460 * Free the returned object with g_object_unref().
20465 * g_file_get_basename:
20466 * @file: input #GFile
20468 * Gets the base name (the last component of the path) for a given #GFile.
20470 * If called for the top level of a system (such as the filesystem root
20471 * or a uri like sftp://host/) it will return a single directory separator
20472 * (and on Windows, possibly a drive letter).
20474 * The base name is a byte string (not UTF-8). It has no defined encoding
20475 * or rules other than it may not contain zero bytes. If you want to use
20476 * filenames in a user interface you should use the display name that you
20477 * can get by requesting the %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME
20478 * attribute with g_file_query_info().
20480 * This call does no blocking I/O.
20482 * Returns: (nullable): string containing the #GFile's base name, or
20483 * %NULL if given #GFile is invalid. The returned string should be
20484 * freed with g_free() when no longer needed.
20489 * g_file_get_child:
20490 * @file: input #GFile
20491 * @name: string containing the child's basename
20493 * Gets a child of @file with basename equal to @name.
20495 * Note that the file with that specific name might not exist, but
20496 * you can still have a #GFile that points to it. You can use this
20497 * for instance to create that file.
20499 * This call does no blocking I/O.
20501 * Returns: (transfer full): a #GFile to a child specified by @name.
20502 * Free the returned object with g_object_unref().
20507 * g_file_get_child_for_display_name:
20508 * @file: input #GFile
20509 * @display_name: string to a possible child
20510 * @error: return location for an error
20512 * Gets the child of @file for a given @display_name (i.e. a UTF-8
20513 * version of the name). If this function fails, it returns %NULL
20514 * and @error will be set. This is very useful when constructing a
20515 * #GFile for a new file and the user entered the filename in the
20516 * user interface, for instance when you select a directory and
20517 * type a filename in the file selector.
20519 * This call does no blocking I/O.
20521 * Returns: (transfer full): a #GFile to the specified child, or
20522 * %NULL if the display name couldn't be converted.
20523 * Free the returned object with g_object_unref().
20528 * g_file_get_parent:
20529 * @file: input #GFile
20531 * Gets the parent directory for the @file.
20532 * If the @file represents the root directory of the
20533 * file system, then %NULL will be returned.
20535 * This call does no blocking I/O.
20537 * Returns: (nullable) (transfer full): a #GFile structure to the
20538 * parent of the given #GFile or %NULL if there is no parent. Free
20539 * the returned object with g_object_unref().
20544 * g_file_get_parse_name:
20545 * @file: input #GFile
20547 * Gets the parse name of the @file.
20548 * A parse name is a UTF-8 string that describes the
20549 * file such that one can get the #GFile back using
20550 * g_file_parse_name().
20552 * This is generally used to show the #GFile as a nice
20553 * full-pathname kind of string in a user interface,
20554 * like in a location entry.
20556 * For local files with names that can safely be converted
20557 * to UTF-8 the pathname is used, otherwise the IRI is used
20558 * (a form of URI that allows UTF-8 characters unescaped).
20560 * This call does no blocking I/O.
20562 * Returns: a string containing the #GFile's parse name.
20563 * The returned string should be freed with g_free()
20564 * when no longer needed.
20570 * @file: input #GFile
20572 * Gets the local pathname for #GFile, if one exists.
20574 * This call does no blocking I/O.
20576 * Returns: (nullable): string containing the #GFile's path, or %NULL
20577 * if no such path exists. The returned string should be freed
20578 * with g_free() when no longer needed.
20583 * g_file_get_relative_path:
20584 * @parent: input #GFile
20585 * @descendant: input #GFile
20587 * Gets the path for @descendant relative to @parent.
20589 * This call does no blocking I/O.
20591 * Returns: (nullable): string with the relative path from @descendant
20592 * to @parent, or %NULL if @descendant doesn't have @parent as
20593 * prefix. The returned string should be freed with g_free() when
20594 * no longer needed.
20600 * @file: input #GFile
20602 * Gets the URI for the @file.
20604 * This call does no blocking I/O.
20606 * Returns: a string containing the #GFile's URI.
20607 * The returned string should be freed with g_free()
20608 * when no longer needed.
20613 * g_file_get_uri_scheme:
20614 * @file: input #GFile
20616 * Gets the URI scheme for a #GFile.
20617 * RFC 3986 decodes the scheme as:
20619 * URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
20621 * Common schemes include "file", "http", "ftp", etc.
20623 * This call does no blocking I/O.
20625 * Returns: a string containing the URI scheme for the given
20626 * #GFile. The returned string should be freed with g_free()
20627 * when no longer needed.
20632 * g_file_has_parent:
20633 * @file: input #GFile
20634 * @parent: (allow-none): the parent to check for, or %NULL
20636 * Checks if @file has a parent, and optionally, if it is @parent.
20638 * If @parent is %NULL then this function returns %TRUE if @file has any
20639 * parent at all. If @parent is non-%NULL then %TRUE is only returned
20640 * if @file is a child of @parent.
20642 * Returns: %TRUE if @file is a child of @parent (or any parent in the
20643 * case that @parent is %NULL).
20649 * g_file_has_prefix: (virtual prefix_matches)
20650 * @file: input #GFile
20651 * @prefix: input #GFile
20653 * Checks whether @file has the prefix specified by @prefix.
20655 * In other words, if the names of initial elements of @file's
20656 * pathname match @prefix. Only full pathname elements are matched,
20657 * so a path like /foo is not considered a prefix of /foobar, only
20660 * This call does no I/O, as it works purely on names. As such it can
20661 * sometimes return %FALSE even if @file is inside a @prefix (from a
20662 * filesystem point of view), because the prefix of @file is an alias
20665 * Returns: %TRUE if the @files's parent, grandparent, etc is @prefix,
20666 * %FALSE otherwise.
20671 * g_file_has_uri_scheme:
20672 * @file: input #GFile
20673 * @uri_scheme: a string containing a URI scheme
20675 * Checks to see if a #GFile has a given URI scheme.
20677 * This call does no blocking I/O.
20679 * Returns: %TRUE if #GFile's backend supports the
20680 * given URI scheme, %FALSE if URI scheme is %NULL,
20681 * not supported, or #GFile is invalid.
20686 * g_file_hash: (virtual hash)
20687 * @file: (type GFile): #gconstpointer to a #GFile
20689 * Creates a hash value for a #GFile.
20691 * This call does no blocking I/O.
20693 * Returns: 0 if @file is not a valid #GFile, otherwise an
20694 * integer that can be used as hash value for the #GFile.
20695 * This function is intended for easily hashing a #GFile to
20696 * add to a #GHashTable or similar data structure.
20701 * g_file_icon_get_file:
20704 * Gets the #GFile associated with the given @icon.
20706 * Returns: (transfer none): a #GFile, or %NULL.
20714 * Creates a new icon for a file.
20716 * Returns: (transfer full) (type GFileIcon): a #GIcon for the given
20717 * @file, or %NULL on error.
20722 * g_file_info_clear_status:
20723 * @info: a #GFileInfo.
20725 * Clears the status information from @info.
20730 * g_file_info_copy_into:
20731 * @src_info: source to copy attributes from.
20732 * @dest_info: destination to copy attributes to.
20734 * Copies all of the [GFileAttribute][gio-GFileAttribute]
20735 * from @src_info to @dest_info.
20741 * @other: a #GFileInfo.
20743 * Duplicates a file info structure.
20745 * Returns: (transfer full): a duplicate #GFileInfo of @other.
20750 * g_file_info_get_attribute_as_string:
20751 * @info: a #GFileInfo.
20752 * @attribute: a file attribute key.
20754 * Gets the value of a attribute, formated as a string.
20755 * This escapes things as needed to make the string valid
20758 * Returns: a UTF-8 string associated with the given @attribute.
20759 * When you're done with the string it must be freed with g_free().
20764 * g_file_info_get_attribute_boolean:
20765 * @info: a #GFileInfo.
20766 * @attribute: a file attribute key.
20768 * Gets the value of a boolean attribute. If the attribute does not
20769 * contain a boolean value, %FALSE will be returned.
20771 * Returns: the boolean value contained within the attribute.
20776 * g_file_info_get_attribute_byte_string:
20777 * @info: a #GFileInfo.
20778 * @attribute: a file attribute key.
20780 * Gets the value of a byte string attribute. If the attribute does
20781 * not contain a byte string, %NULL will be returned.
20783 * Returns: the contents of the @attribute value as a byte string, or
20789 * g_file_info_get_attribute_data:
20790 * @info: a #GFileInfo
20791 * @attribute: a file attribute key
20792 * @type: (out) (allow-none): return location for the attribute type, or %NULL
20793 * @value_pp: (out) (allow-none): return location for the attribute value, or %NULL
20794 * @status: (out) (allow-none): return location for the attribute status, or %NULL
20796 * Gets the attribute type, value and status for an attribute key.
20798 * Returns: (transfer none): %TRUE if @info has an attribute named @attribute,
20799 * %FALSE otherwise.
20804 * g_file_info_get_attribute_int32:
20805 * @info: a #GFileInfo.
20806 * @attribute: a file attribute key.
20808 * Gets a signed 32-bit integer contained within the attribute. If the
20809 * attribute does not contain a signed 32-bit integer, or is invalid,
20810 * 0 will be returned.
20812 * Returns: a signed 32-bit integer from the attribute.
20817 * g_file_info_get_attribute_int64:
20818 * @info: a #GFileInfo.
20819 * @attribute: a file attribute key.
20821 * Gets a signed 64-bit integer contained within the attribute. If the
20822 * attribute does not contain an signed 64-bit integer, or is invalid,
20823 * 0 will be returned.
20825 * Returns: a signed 64-bit integer from the attribute.
20830 * g_file_info_get_attribute_object:
20831 * @info: a #GFileInfo.
20832 * @attribute: a file attribute key.
20834 * Gets the value of a #GObject attribute. If the attribute does
20835 * not contain a #GObject, %NULL will be returned.
20837 * Returns: (transfer none): a #GObject associated with the given @attribute, or
20843 * g_file_info_get_attribute_status:
20844 * @info: a #GFileInfo
20845 * @attribute: a file attribute key
20847 * Gets the attribute status for an attribute key.
20849 * Returns: a #GFileAttributeStatus for the given @attribute, or
20850 * %G_FILE_ATTRIBUTE_STATUS_UNSET if the key is invalid.
20855 * g_file_info_get_attribute_string:
20856 * @info: a #GFileInfo.
20857 * @attribute: a file attribute key.
20859 * Gets the value of a string attribute. If the attribute does
20860 * not contain a string, %NULL will be returned.
20862 * Returns: the contents of the @attribute value as a UTF-8 string, or
20868 * g_file_info_get_attribute_stringv:
20869 * @info: a #GFileInfo.
20870 * @attribute: a file attribute key.
20872 * Gets the value of a stringv attribute. If the attribute does
20873 * not contain a stringv, %NULL will be returned.
20875 * Returns: (transfer none): the contents of the @attribute value as a stringv, or
20876 * %NULL otherwise. Do not free. These returned strings are UTF-8.
20882 * g_file_info_get_attribute_type:
20883 * @info: a #GFileInfo.
20884 * @attribute: a file attribute key.
20886 * Gets the attribute type for an attribute key.
20888 * Returns: a #GFileAttributeType for the given @attribute, or
20889 * %G_FILE_ATTRIBUTE_TYPE_INVALID if the key is not set.
20894 * g_file_info_get_attribute_uint32:
20895 * @info: a #GFileInfo.
20896 * @attribute: a file attribute key.
20898 * Gets an unsigned 32-bit integer contained within the attribute. If the
20899 * attribute does not contain an unsigned 32-bit integer, or is invalid,
20900 * 0 will be returned.
20902 * Returns: an unsigned 32-bit integer from the attribute.
20907 * g_file_info_get_attribute_uint64:
20908 * @info: a #GFileInfo.
20909 * @attribute: a file attribute key.
20911 * Gets a unsigned 64-bit integer contained within the attribute. If the
20912 * attribute does not contain an unsigned 64-bit integer, or is invalid,
20913 * 0 will be returned.
20915 * Returns: a unsigned 64-bit integer from the attribute.
20920 * g_file_info_get_content_type:
20921 * @info: a #GFileInfo.
20923 * Gets the file's content type.
20925 * Returns: a string containing the file's content type.
20930 * g_file_info_get_deletion_date:
20931 * @info: a #GFileInfo.
20933 * Returns the #GDateTime representing the deletion date of the file, as
20934 * available in G_FILE_ATTRIBUTE_TRASH_DELETION_DATE. If the
20935 * G_FILE_ATTRIBUTE_TRASH_DELETION_DATE attribute is unset, %NULL is returned.
20937 * Returns: a #GDateTime, or %NULL.
20943 * g_file_info_get_display_name:
20944 * @info: a #GFileInfo.
20946 * Gets a display name for a file.
20948 * Returns: a string containing the display name.
20953 * g_file_info_get_edit_name:
20954 * @info: a #GFileInfo.
20956 * Gets the edit name for a file.
20958 * Returns: a string containing the edit name.
20963 * g_file_info_get_etag:
20964 * @info: a #GFileInfo.
20966 * Gets the [entity tag][gfile-etag] for a given
20967 * #GFileInfo. See %G_FILE_ATTRIBUTE_ETAG_VALUE.
20969 * Returns: a string containing the value of the "etag:value" attribute.
20974 * g_file_info_get_file_type:
20975 * @info: a #GFileInfo.
20977 * Gets a file's type (whether it is a regular file, symlink, etc).
20978 * This is different from the file's content type, see g_file_info_get_content_type().
20980 * Returns: a #GFileType for the given file.
20985 * g_file_info_get_icon:
20986 * @info: a #GFileInfo.
20988 * Gets the icon for a file.
20990 * Returns: (transfer none): #GIcon for the given @info.
20995 * g_file_info_get_is_backup:
20996 * @info: a #GFileInfo.
20998 * Checks if a file is a backup file.
21000 * Returns: %TRUE if file is a backup file, %FALSE otherwise.
21005 * g_file_info_get_is_hidden:
21006 * @info: a #GFileInfo.
21008 * Checks if a file is hidden.
21010 * Returns: %TRUE if the file is a hidden file, %FALSE otherwise.
21015 * g_file_info_get_is_symlink:
21016 * @info: a #GFileInfo.
21018 * Checks if a file is a symlink.
21020 * Returns: %TRUE if the given @info is a symlink.
21025 * g_file_info_get_modification_time:
21026 * @info: a #GFileInfo.
21027 * @result: (out caller-allocates): a #GTimeVal.
21029 * Gets the modification time of the current @info and sets it
21035 * g_file_info_get_name:
21036 * @info: a #GFileInfo.
21038 * Gets the name for a file.
21040 * Returns: a string containing the file name.
21045 * g_file_info_get_size:
21046 * @info: a #GFileInfo.
21048 * Gets the file's size.
21050 * Returns: a #goffset containing the file's size.
21055 * g_file_info_get_sort_order:
21056 * @info: a #GFileInfo.
21058 * Gets the value of the sort_order attribute from the #GFileInfo.
21059 * See %G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER.
21061 * Returns: a #gint32 containing the value of the "standard::sort_order" attribute.
21066 * g_file_info_get_symbolic_icon:
21067 * @info: a #GFileInfo.
21069 * Gets the symbolic icon for a file.
21071 * Returns: (transfer none): #GIcon for the given @info.
21077 * g_file_info_get_symlink_target:
21078 * @info: a #GFileInfo.
21080 * Gets the symlink target for a given #GFileInfo.
21082 * Returns: a string containing the symlink target.
21087 * g_file_info_has_attribute:
21088 * @info: a #GFileInfo.
21089 * @attribute: a file attribute key.
21091 * Checks if a file info structure has an attribute named @attribute.
21093 * Returns: %TRUE if @Ginfo has an attribute named @attribute,
21094 * %FALSE otherwise.
21099 * g_file_info_has_namespace:
21100 * @info: a #GFileInfo.
21101 * @name_space: a file attribute namespace.
21103 * Checks if a file info structure has an attribute in the
21104 * specified @name_space.
21106 * Returns: %TRUE if @Ginfo has an attribute in @name_space,
21107 * %FALSE otherwise.
21113 * g_file_info_list_attributes:
21114 * @info: a #GFileInfo.
21115 * @name_space: a file attribute key's namespace.
21117 * Lists the file info structure's attributes.
21119 * Returns: (nullable) (array zero-terminated=1) (transfer full): a
21120 * null-terminated array of strings of all of the possible attribute
21121 * types for the given @name_space, or %NULL on error.
21128 * Creates a new file info structure.
21130 * Returns: a #GFileInfo.
21135 * g_file_info_remove_attribute:
21136 * @info: a #GFileInfo.
21137 * @attribute: a file attribute key.
21139 * Removes all cases of @attribute from @info if it exists.
21144 * g_file_info_set_attribute:
21145 * @info: a #GFileInfo.
21146 * @attribute: a file attribute key.
21147 * @type: a #GFileAttributeType
21148 * @value_p: pointer to the value
21150 * Sets the @attribute to contain the given value, if possible. To unset the
21151 * attribute, use %G_ATTRIBUTE_TYPE_INVALID for @type.
21156 * g_file_info_set_attribute_boolean:
21157 * @info: a #GFileInfo.
21158 * @attribute: a file attribute key.
21159 * @attr_value: a boolean value.
21161 * Sets the @attribute to contain the given @attr_value,
21167 * g_file_info_set_attribute_byte_string:
21168 * @info: a #GFileInfo.
21169 * @attribute: a file attribute key.
21170 * @attr_value: a byte string.
21172 * Sets the @attribute to contain the given @attr_value,
21178 * g_file_info_set_attribute_int32:
21179 * @info: a #GFileInfo.
21180 * @attribute: a file attribute key.
21181 * @attr_value: a signed 32-bit integer
21183 * Sets the @attribute to contain the given @attr_value,
21189 * g_file_info_set_attribute_int64:
21190 * @info: a #GFileInfo.
21191 * @attribute: attribute name to set.
21192 * @attr_value: int64 value to set attribute to.
21194 * Sets the @attribute to contain the given @attr_value,
21200 * g_file_info_set_attribute_mask:
21201 * @info: a #GFileInfo.
21202 * @mask: a #GFileAttributeMatcher.
21204 * Sets @mask on @info to match specific attribute types.
21209 * g_file_info_set_attribute_object:
21210 * @info: a #GFileInfo.
21211 * @attribute: a file attribute key.
21212 * @attr_value: a #GObject.
21214 * Sets the @attribute to contain the given @attr_value,
21220 * g_file_info_set_attribute_status:
21221 * @info: a #GFileInfo
21222 * @attribute: a file attribute key
21223 * @status: a #GFileAttributeStatus
21225 * Sets the attribute status for an attribute key. This is only
21226 * needed by external code that implement g_file_set_attributes_from_info()
21227 * or similar functions.
21229 * The attribute must exist in @info for this to work. Otherwise %FALSE
21230 * is returned and @info is unchanged.
21232 * Returns: %TRUE if the status was changed, %FALSE if the key was not set.
21238 * g_file_info_set_attribute_string:
21239 * @info: a #GFileInfo.
21240 * @attribute: a file attribute key.
21241 * @attr_value: a UTF-8 string.
21243 * Sets the @attribute to contain the given @attr_value,
21249 * g_file_info_set_attribute_stringv:
21250 * @info: a #GFileInfo.
21251 * @attribute: a file attribute key
21252 * @attr_value: (array) (element-type utf8): a %NULL terminated array of UTF-8 strings.
21254 * Sets the @attribute to contain the given @attr_value,
21262 * g_file_info_set_attribute_uint32:
21263 * @info: a #GFileInfo.
21264 * @attribute: a file attribute key.
21265 * @attr_value: an unsigned 32-bit integer.
21267 * Sets the @attribute to contain the given @attr_value,
21273 * g_file_info_set_attribute_uint64:
21274 * @info: a #GFileInfo.
21275 * @attribute: a file attribute key.
21276 * @attr_value: an unsigned 64-bit integer.
21278 * Sets the @attribute to contain the given @attr_value,
21284 * g_file_info_set_content_type:
21285 * @info: a #GFileInfo.
21286 * @content_type: a content type. See [GContentType][gio-GContentType]
21288 * Sets the content type attribute for a given #GFileInfo.
21289 * See %G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE.
21294 * g_file_info_set_display_name:
21295 * @info: a #GFileInfo.
21296 * @display_name: a string containing a display name.
21298 * Sets the display name for the current #GFileInfo.
21299 * See %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME.
21304 * g_file_info_set_edit_name:
21305 * @info: a #GFileInfo.
21306 * @edit_name: a string containing an edit name.
21308 * Sets the edit name for the current file.
21309 * See %G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME.
21314 * g_file_info_set_file_type:
21315 * @info: a #GFileInfo.
21316 * @type: a #GFileType.
21318 * Sets the file type in a #GFileInfo to @type.
21319 * See %G_FILE_ATTRIBUTE_STANDARD_TYPE.
21324 * g_file_info_set_icon:
21325 * @info: a #GFileInfo.
21328 * Sets the icon for a given #GFileInfo.
21329 * See %G_FILE_ATTRIBUTE_STANDARD_ICON.
21334 * g_file_info_set_is_hidden:
21335 * @info: a #GFileInfo.
21336 * @is_hidden: a #gboolean.
21338 * Sets the "is_hidden" attribute in a #GFileInfo according to @is_hidden.
21339 * See %G_FILE_ATTRIBUTE_STANDARD_IS_HIDDEN.
21344 * g_file_info_set_is_symlink:
21345 * @info: a #GFileInfo.
21346 * @is_symlink: a #gboolean.
21348 * Sets the "is_symlink" attribute in a #GFileInfo according to @is_symlink.
21349 * See %G_FILE_ATTRIBUTE_STANDARD_IS_SYMLINK.
21354 * g_file_info_set_modification_time:
21355 * @info: a #GFileInfo.
21356 * @mtime: a #GTimeVal.
21358 * Sets the %G_FILE_ATTRIBUTE_TIME_MODIFIED attribute in the file
21359 * info to the given time value.
21364 * g_file_info_set_name:
21365 * @info: a #GFileInfo.
21366 * @name: a string containing a name.
21368 * Sets the name attribute for the current #GFileInfo.
21369 * See %G_FILE_ATTRIBUTE_STANDARD_NAME.
21374 * g_file_info_set_size:
21375 * @info: a #GFileInfo.
21376 * @size: a #goffset containing the file's size.
21378 * Sets the %G_FILE_ATTRIBUTE_STANDARD_SIZE attribute in the file info
21379 * to the given size.
21384 * g_file_info_set_sort_order:
21385 * @info: a #GFileInfo.
21386 * @sort_order: a sort order integer.
21388 * Sets the sort order attribute in the file info structure. See
21389 * %G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER.
21394 * g_file_info_set_symbolic_icon:
21395 * @info: a #GFileInfo.
21398 * Sets the symbolic icon for a given #GFileInfo.
21399 * See %G_FILE_ATTRIBUTE_STANDARD_SYMBOLIC_ICON.
21406 * g_file_info_set_symlink_target:
21407 * @info: a #GFileInfo.
21408 * @symlink_target: a static string containing a path to a symlink target.
21410 * Sets the %G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET attribute in the file info
21411 * to the given symlink target.
21416 * g_file_info_unset_attribute_mask:
21417 * @info: #GFileInfo.
21419 * Unsets a mask set by g_file_info_set_attribute_mask(), if one
21425 * g_file_input_stream_query_info:
21426 * @stream: a #GFileInputStream.
21427 * @attributes: a file attribute query string.
21428 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
21429 * @error: a #GError location to store the error occurring, or %NULL to
21432 * Queries a file input stream the given @attributes. This function blocks
21433 * while querying the stream. For the asynchronous (non-blocking) version
21434 * of this function, see g_file_input_stream_query_info_async(). While the
21435 * stream is blocked, the stream will set the pending flag internally, and
21436 * any other operations on the stream will fail with %G_IO_ERROR_PENDING.
21438 * Returns: (transfer full): a #GFileInfo, or %NULL on error.
21443 * g_file_input_stream_query_info_async:
21444 * @stream: a #GFileInputStream.
21445 * @attributes: a file attribute query string.
21446 * @io_priority: the [I/O priority][io-priority] of the request
21447 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
21448 * @callback: (scope async): callback to call when the request is satisfied
21449 * @user_data: (closure): the data to pass to callback function
21451 * Queries the stream information asynchronously.
21452 * When the operation is finished @callback will be called.
21453 * You can then call g_file_input_stream_query_info_finish()
21454 * to get the result of the operation.
21456 * For the synchronous version of this function,
21457 * see g_file_input_stream_query_info().
21459 * If @cancellable is not %NULL, then the operation can be cancelled by
21460 * triggering the cancellable object from another thread. If the operation
21461 * was cancelled, the error %G_IO_ERROR_CANCELLED will be set
21466 * g_file_input_stream_query_info_finish:
21467 * @stream: a #GFileInputStream.
21468 * @result: a #GAsyncResult.
21469 * @error: a #GError location to store the error occurring,
21470 * or %NULL to ignore.
21472 * Finishes an asynchronous info query operation.
21474 * Returns: (transfer full): #GFileInfo.
21479 * g_file_io_stream_get_etag:
21480 * @stream: a #GFileIOStream.
21482 * Gets the entity tag for the file when it has been written.
21483 * This must be called after the stream has been written
21484 * and closed, as the etag can change while writing.
21486 * Returns: the entity tag for the stream.
21492 * g_file_io_stream_query_info:
21493 * @stream: a #GFileIOStream.
21494 * @attributes: a file attribute query string.
21495 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
21496 * @error: a #GError, %NULL to ignore.
21498 * Queries a file io stream for the given @attributes.
21499 * This function blocks while querying the stream. For the asynchronous
21500 * version of this function, see g_file_io_stream_query_info_async().
21501 * While the stream is blocked, the stream will set the pending flag
21502 * internally, and any other operations on the stream will fail with
21503 * %G_IO_ERROR_PENDING.
21505 * Can fail if the stream was already closed (with @error being set to
21506 * %G_IO_ERROR_CLOSED), the stream has pending operations (with @error being
21507 * set to %G_IO_ERROR_PENDING), or if querying info is not supported for
21508 * the stream's interface (with @error being set to %G_IO_ERROR_NOT_SUPPORTED). I
21509 * all cases of failure, %NULL will be returned.
21511 * If @cancellable is not %NULL, then the operation can be cancelled by
21512 * triggering the cancellable object from another thread. If the operation
21513 * was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %NULL will
21516 * Returns: (transfer full): a #GFileInfo for the @stream, or %NULL on error.
21522 * g_file_io_stream_query_info_async:
21523 * @stream: a #GFileIOStream.
21524 * @attributes: a file attribute query string.
21525 * @io_priority: the [I/O priority][gio-GIOScheduler] of the request
21526 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
21527 * @callback: (scope async): callback to call when the request is satisfied
21528 * @user_data: (closure): the data to pass to callback function
21530 * Asynchronously queries the @stream for a #GFileInfo. When completed,
21531 * @callback will be called with a #GAsyncResult which can be used to
21532 * finish the operation with g_file_io_stream_query_info_finish().
21534 * For the synchronous version of this function, see
21535 * g_file_io_stream_query_info().
21542 * g_file_io_stream_query_info_finish:
21543 * @stream: a #GFileIOStream.
21544 * @result: a #GAsyncResult.
21545 * @error: a #GError, %NULL to ignore.
21547 * Finalizes the asynchronous query started
21548 * by g_file_io_stream_query_info_async().
21550 * Returns: (transfer full): A #GFileInfo for the finished query.
21556 * g_file_is_native:
21557 * @file: input #GFile
21559 * Checks to see if a file is native to the platform.
21561 * A native file s one expressed in the platform-native filename format,
21562 * e.g. "C:\Windows" or "/usr/bin/". This does not mean the file is local,
21563 * as it might be on a locally mounted remote filesystem.
21565 * On some systems non-native files may be available using the native
21566 * filesystem via a userspace filesystem (FUSE), in these cases this call
21567 * will return %FALSE, but g_file_get_path() will still return a native path.
21569 * This call does no blocking I/O.
21571 * Returns: %TRUE if @file is native
21576 * g_file_load_contents:
21577 * @file: input #GFile
21578 * @cancellable: optional #GCancellable object, %NULL to ignore
21579 * @contents: (out) (transfer full) (element-type guint8) (array length=length): a location to place the contents of the file
21580 * @length: (out) (allow-none): a location to place the length of the contents of the file,
21581 * or %NULL if the length is not needed
21582 * @etag_out: (out) (allow-none): a location to place the current entity tag for the file,
21583 * or %NULL if the entity tag is not needed
21584 * @error: a #GError, or %NULL
21586 * Loads the content of the file into memory. The data is always
21587 * zero-terminated, but this is not included in the resultant @length.
21588 * The returned @content should be freed with g_free() when no longer
21591 * If @cancellable is not %NULL, then the operation can be cancelled by
21592 * triggering the cancellable object from another thread. If the operation
21593 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
21595 * Returns: %TRUE if the @file's contents were successfully loaded.
21596 * %FALSE if there were errors.
21601 * g_file_load_contents_async:
21602 * @file: input #GFile
21603 * @cancellable: optional #GCancellable object, %NULL to ignore
21604 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
21605 * @user_data: the data to pass to callback function
21607 * Starts an asynchronous load of the @file's contents.
21609 * For more details, see g_file_load_contents() which is
21610 * the synchronous version of this call.
21612 * When the load operation has completed, @callback will be called
21613 * with @user data. To finish the operation, call
21614 * g_file_load_contents_finish() with the #GAsyncResult returned by
21617 * If @cancellable is not %NULL, then the operation can be cancelled by
21618 * triggering the cancellable object from another thread. If the operation
21619 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
21624 * g_file_load_contents_finish:
21625 * @file: input #GFile
21626 * @res: a #GAsyncResult
21627 * @contents: (out) (transfer full) (element-type guint8) (array length=length): a location to place the contents of the file
21628 * @length: (out) (allow-none): a location to place the length of the contents of the file,
21629 * or %NULL if the length is not needed
21630 * @etag_out: (out) (allow-none): a location to place the current entity tag for the file,
21631 * or %NULL if the entity tag is not needed
21632 * @error: a #GError, or %NULL
21634 * Finishes an asynchronous load of the @file's contents.
21635 * The contents are placed in @contents, and @length is set to the
21636 * size of the @contents string. The @content should be freed with
21637 * g_free() when no longer needed. If @etag_out is present, it will be
21638 * set to the new entity tag for the @file.
21640 * Returns: %TRUE if the load was successful. If %FALSE and @error is
21641 * present, it will be set appropriately.
21646 * g_file_load_partial_contents_async: (skip)
21647 * @file: input #GFile
21648 * @cancellable: optional #GCancellable object, %NULL to ignore
21649 * @read_more_callback: a #GFileReadMoreCallback to receive partial data
21650 * and to specify whether further data should be read
21651 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
21652 * @user_data: the data to pass to the callback functions
21654 * Reads the partial contents of a file. A #GFileReadMoreCallback should
21655 * be used to stop reading from the file when appropriate, else this
21656 * function will behave exactly as g_file_load_contents_async(). This
21657 * operation can be finished by g_file_load_partial_contents_finish().
21659 * Users of this function should be aware that @user_data is passed to
21660 * both the @read_more_callback and the @callback.
21662 * If @cancellable is not %NULL, then the operation can be cancelled by
21663 * triggering the cancellable object from another thread. If the operation
21664 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
21669 * g_file_load_partial_contents_finish:
21670 * @file: input #GFile
21671 * @res: a #GAsyncResult
21672 * @contents: (out) (transfer full) (element-type guint8) (array length=length): a location to place the contents of the file
21673 * @length: (out) (allow-none): a location to place the length of the contents of the file,
21674 * or %NULL if the length is not needed
21675 * @etag_out: (out) (allow-none): a location to place the current entity tag for the file,
21676 * or %NULL if the entity tag is not needed
21677 * @error: a #GError, or %NULL
21679 * Finishes an asynchronous partial load operation that was started
21680 * with g_file_load_partial_contents_async(). The data is always
21681 * zero-terminated, but this is not included in the resultant @length.
21682 * The returned @content should be freed with g_free() when no longer
21685 * Returns: %TRUE if the load was successful. If %FALSE and @error is
21686 * present, it will be set appropriately.
21691 * g_file_make_directory:
21692 * @file: input #GFile
21693 * @cancellable: (allow-none): optional #GCancellable object,
21695 * @error: a #GError, or %NULL
21697 * Creates a directory. Note that this will only create a child directory
21698 * of the immediate parent directory of the path or URI given by the #GFile.
21699 * To recursively create directories, see g_file_make_directory_with_parents().
21700 * This function will fail if the parent directory does not exist, setting
21701 * @error to %G_IO_ERROR_NOT_FOUND. If the file system doesn't support
21702 * creating directories, this function will fail, setting @error to
21703 * %G_IO_ERROR_NOT_SUPPORTED.
21705 * For a local #GFile the newly created directory will have the default
21706 * (current) ownership and permissions of the current process.
21708 * If @cancellable is not %NULL, then the operation can be cancelled by
21709 * triggering the cancellable object from another thread. If the operation
21710 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
21712 * Returns: %TRUE on successful creation, %FALSE otherwise.
21717 * g_file_make_directory_async: (virtual make_directory_async)
21718 * @file: input #GFile
21719 * @io_priority: the [I/O priority][io-priority] of the request
21720 * @cancellable: (allow-none): optional #GCancellable object,
21722 * @callback: a #GAsyncReadyCallback to call
21723 * when the request is satisfied
21724 * @user_data: the data to pass to callback function
21726 * Asynchronously creates a directory.
21733 * g_file_make_directory_finish: (virtual make_directory_finish)
21734 * @file: input #GFile
21735 * @result: a #GAsyncResult
21736 * @error: a #GError, or %NULL
21738 * Finishes an asynchronous directory creation, started with
21739 * g_file_make_directory_async().
21741 * Returns: %TRUE on successful directory creation, %FALSE otherwise.
21747 * g_file_make_directory_with_parents:
21748 * @file: input #GFile
21749 * @cancellable: (allow-none): optional #GCancellable object,
21751 * @error: a #GError, or %NULL
21753 * Creates a directory and any parent directories that may not
21754 * exist similar to 'mkdir -p'. If the file system does not support
21755 * creating directories, this function will fail, setting @error to
21756 * %G_IO_ERROR_NOT_SUPPORTED. If the directory itself already exists,
21757 * this function will fail setting @error to %G_IO_ERROR_EXISTS, unlike
21758 * the similar g_mkdir_with_parents().
21760 * For a local #GFile the newly created directories will have the default
21761 * (current) ownership and permissions of the current process.
21763 * If @cancellable is not %NULL, then the operation can be cancelled by
21764 * triggering the cancellable object from another thread. If the operation
21765 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
21767 * Returns: %TRUE if all directories have been successfully created, %FALSE
21774 * g_file_make_symbolic_link:
21775 * @file: a #GFile with the name of the symlink to create
21776 * @symlink_value: a string with the path for the target of the new symlink
21777 * @cancellable: (allow-none): optional #GCancellable object,
21779 * @error: a #GError
21781 * Creates a symbolic link named @file which contains the string
21784 * If @cancellable is not %NULL, then the operation can be cancelled by
21785 * triggering the cancellable object from another thread. If the operation
21786 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
21788 * Returns: %TRUE on the creation of a new symlink, %FALSE otherwise.
21793 * g_file_measure_disk_usage:
21795 * @flags: #GFileMeasureFlags
21796 * @cancellable: (allow-none): optional #GCancellable
21797 * @progress_callback: (allow-none): a #GFileMeasureProgressCallback
21798 * @progress_data: user_data for @progress_callback
21799 * @disk_usage: (allow-none) (out): the number of bytes of disk space used
21800 * @num_dirs: (allow-none) (out): the number of directories encountered
21801 * @num_files: (allow-none) (out): the number of non-directories encountered
21802 * @error: (allow-none): %NULL, or a pointer to a %NULL #GError pointer
21804 * Recursively measures the disk usage of @file.
21806 * This is essentially an analog of the 'du' command, but it also
21807 * reports the number of directories and non-directory files encountered
21808 * (including things like symbolic links).
21810 * By default, errors are only reported against the toplevel file
21811 * itself. Errors found while recursing are silently ignored, unless
21812 * %G_FILE_DISK_USAGE_REPORT_ALL_ERRORS is given in @flags.
21814 * The returned size, @disk_usage, is in bytes and should be formatted
21815 * with g_format_size() in order to get something reasonable for showing
21816 * in a user interface.
21818 * @progress_callback and @progress_data can be given to request
21819 * periodic progress updates while scanning. See the documentation for
21820 * #GFileMeasureProgressCallback for information about when and how the
21821 * callback will be invoked.
21823 * Returns: %TRUE if successful, with the out parameters set.
21824 * %FALSE otherwise, with @error set.
21830 * g_file_measure_disk_usage_async:
21832 * @flags: #GFileMeasureFlags
21833 * @io_priority: the [I/O priority][io-priority] of the request
21834 * @cancellable: (allow-none): optional #GCancellable
21835 * @progress_callback: (allow-none): a #GFileMeasureProgressCallback
21836 * @progress_data: user_data for @progress_callback
21837 * @callback: (allow-none): a #GAsyncReadyCallback to call when complete
21838 * @user_data: the data to pass to callback function
21840 * Recursively measures the disk usage of @file.
21842 * This is the asynchronous version of g_file_measure_disk_usage(). See
21843 * there for more information.
21850 * g_file_measure_disk_usage_finish:
21852 * @result: the #GAsyncResult passed to your #GAsyncReadyCallback
21853 * @disk_usage: (allow-none) (out): the number of bytes of disk space used
21854 * @num_dirs: (allow-none) (out): the number of directories encountered
21855 * @num_files: (allow-none) (out): the number of non-directories encountered
21856 * @error: (allow-none): %NULL, or a pointer to a %NULL #GError pointer
21858 * Collects the results from an earlier call to
21859 * g_file_measure_disk_usage_async(). See g_file_measure_disk_usage() for
21860 * more information.
21862 * Returns: %TRUE if successful, with the out parameters set.
21863 * %FALSE otherwise, with @error set.
21870 * @file: input #GFile
21871 * @flags: a set of #GFileMonitorFlags
21872 * @cancellable: (allow-none): optional #GCancellable object,
21874 * @error: a #GError, or %NULL
21876 * Obtains a file or directory monitor for the given file,
21877 * depending on the type of the file.
21879 * If @cancellable is not %NULL, then the operation can be cancelled by
21880 * triggering the cancellable object from another thread. If the operation
21881 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
21883 * Returns: (transfer full): a #GFileMonitor for the given @file,
21884 * or %NULL on error.
21885 * Free the returned object with g_object_unref().
21891 * g_file_monitor_cancel:
21892 * @monitor: a #GFileMonitor.
21894 * Cancels a file monitor.
21896 * Returns: %TRUE if monitor was cancelled.
21901 * g_file_monitor_directory: (virtual monitor_dir)
21902 * @file: input #GFile
21903 * @flags: a set of #GFileMonitorFlags
21904 * @cancellable: (allow-none): optional #GCancellable object,
21906 * @error: a #GError, or %NULL
21908 * Obtains a directory monitor for the given file.
21909 * This may fail if directory monitoring is not supported.
21911 * If @cancellable is not %NULL, then the operation can be cancelled by
21912 * triggering the cancellable object from another thread. If the operation
21913 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
21915 * It does not make sense for @flags to contain
21916 * %G_FILE_MONITOR_WATCH_HARD_LINKS, since hard links can not be made to
21917 * directories. It is not possible to monitor all the files in a
21918 * directory for changes made via hard links; if you want to do this then
21919 * you must register individual watches with g_file_monitor().
21921 * Returns: (transfer full): a #GFileMonitor for the given @file,
21922 * or %NULL on error.
21923 * Free the returned object with g_object_unref().
21928 * g_file_monitor_emit_event:
21929 * @monitor: a #GFileMonitor.
21930 * @child: a #GFile.
21931 * @other_file: a #GFile.
21932 * @event_type: a set of #GFileMonitorEvent flags.
21934 * Emits the #GFileMonitor::changed signal if a change
21935 * has taken place. Should be called from file monitor
21936 * implementations only.
21938 * The signal will be emitted from an idle handler (in the
21939 * [thread-default main context][g-main-context-push-thread-default]).
21944 * g_file_monitor_file:
21945 * @file: input #GFile
21946 * @flags: a set of #GFileMonitorFlags
21947 * @cancellable: (allow-none): optional #GCancellable object,
21949 * @error: a #GError, or %NULL
21951 * Obtains a file monitor for the given file. If no file notification
21952 * mechanism exists, then regular polling of the file is used.
21954 * If @cancellable is not %NULL, then the operation can be cancelled by
21955 * triggering the cancellable object from another thread. If the operation
21956 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
21958 * If @flags contains %G_FILE_MONITOR_WATCH_HARD_LINKS then the monitor
21959 * will also attempt to report changes made to the file via another
21960 * filename (ie, a hard link). Without this flag, you can only rely on
21961 * changes made through the filename contained in @file to be
21962 * reported. Using this flag may result in an increase in resource
21963 * usage, and may not have any effect depending on the #GFileMonitor
21964 * backend and/or filesystem type.
21966 * Returns: (transfer full): a #GFileMonitor for the given @file,
21967 * or %NULL on error.
21968 * Free the returned object with g_object_unref().
21973 * g_file_monitor_is_cancelled:
21974 * @monitor: a #GFileMonitor
21976 * Returns whether the monitor is canceled.
21978 * Returns: %TRUE if monitor is canceled. %FALSE otherwise.
21983 * g_file_monitor_set_rate_limit:
21984 * @monitor: a #GFileMonitor.
21985 * @limit_msecs: a non-negative integer with the limit in milliseconds
21986 * to poll for changes
21988 * Sets the rate limit to which the @monitor will report
21989 * consecutive change events to the same file.
21994 * g_file_mount_enclosing_volume:
21995 * @location: input #GFile
21996 * @flags: flags affecting the operation
21997 * @mount_operation: (allow-none): a #GMountOperation
21998 * or %NULL to avoid user interaction
21999 * @cancellable: (allow-none): optional #GCancellable object,
22001 * @callback: (allow-none): a #GAsyncReadyCallback to call
22002 * when the request is satisfied, or %NULL
22003 * @user_data: the data to pass to callback function
22005 * Starts a @mount_operation, mounting the volume that contains
22006 * the file @location.
22008 * When this operation has completed, @callback will be called with
22009 * @user_user data, and the operation can be finalized with
22010 * g_file_mount_enclosing_volume_finish().
22012 * If @cancellable is not %NULL, then the operation can be cancelled by
22013 * triggering the cancellable object from another thread. If the operation
22014 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
22019 * g_file_mount_enclosing_volume_finish:
22020 * @location: input #GFile
22021 * @result: a #GAsyncResult
22022 * @error: a #GError, or %NULL
22024 * Finishes a mount operation started by g_file_mount_enclosing_volume().
22026 * Returns: %TRUE if successful. If an error has occurred,
22027 * this function will return %FALSE and set @error
22028 * appropriately if present.
22033 * g_file_mount_mountable:
22034 * @file: input #GFile
22035 * @flags: flags affecting the operation
22036 * @mount_operation: (allow-none): a #GMountOperation,
22037 * or %NULL to avoid user interaction
22038 * @cancellable: (allow-none): optional #GCancellable object,
22040 * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call
22041 * when the request is satisfied, or %NULL
22042 * @user_data: (closure): the data to pass to callback function
22044 * Mounts a file of type G_FILE_TYPE_MOUNTABLE.
22045 * Using @mount_operation, you can request callbacks when, for instance,
22046 * passwords are needed during authentication.
22048 * If @cancellable is not %NULL, then the operation can be cancelled by
22049 * triggering the cancellable object from another thread. If the operation
22050 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
22052 * When the operation is finished, @callback will be called.
22053 * You can then call g_file_mount_mountable_finish() to get
22054 * the result of the operation.
22059 * g_file_mount_mountable_finish:
22060 * @file: input #GFile
22061 * @result: a #GAsyncResult
22062 * @error: a #GError, or %NULL
22064 * Finishes a mount operation. See g_file_mount_mountable() for details.
22066 * Finish an asynchronous mount operation that was started
22067 * with g_file_mount_mountable().
22069 * Returns: (transfer full): a #GFile or %NULL on error.
22070 * Free the returned object with g_object_unref().
22076 * @source: #GFile pointing to the source location
22077 * @destination: #GFile pointing to the destination location
22078 * @flags: set of #GFileCopyFlags
22079 * @cancellable: (allow-none): optional #GCancellable object,
22081 * @progress_callback: (allow-none) (scope call): #GFileProgressCallback
22082 * function for updates
22083 * @progress_callback_data: (closure): gpointer to user data for
22084 * the callback function
22085 * @error: #GError for returning error conditions, or %NULL
22087 * Tries to move the file or directory @source to the location specified
22088 * by @destination. If native move operations are supported then this is
22089 * used, otherwise a copy + delete fallback is used. The native
22090 * implementation may support moving directories (for instance on moves
22091 * inside the same filesystem), but the fallback code does not.
22093 * If the flag #G_FILE_COPY_OVERWRITE is specified an already
22094 * existing @destination file is overwritten.
22096 * If the flag #G_FILE_COPY_NOFOLLOW_SYMLINKS is specified then symlinks
22097 * will be copied as symlinks, otherwise the target of the
22098 * @source symlink will be copied.
22100 * If @cancellable is not %NULL, then the operation can be cancelled by
22101 * triggering the cancellable object from another thread. If the operation
22102 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
22104 * If @progress_callback is not %NULL, then the operation can be monitored
22105 * by setting this to a #GFileProgressCallback function.
22106 * @progress_callback_data will be passed to this function. It is
22107 * guaranteed that this callback will be called after all data has been
22108 * transferred with the total number of bytes copied during the operation.
22110 * If the @source file does not exist, then the %G_IO_ERROR_NOT_FOUND
22111 * error is returned, independent on the status of the @destination.
22113 * If #G_FILE_COPY_OVERWRITE is not specified and the target exists,
22114 * then the error %G_IO_ERROR_EXISTS is returned.
22116 * If trying to overwrite a file over a directory, the %G_IO_ERROR_IS_DIRECTORY
22117 * error is returned. If trying to overwrite a directory with a directory the
22118 * %G_IO_ERROR_WOULD_MERGE error is returned.
22120 * If the source is a directory and the target does not exist, or
22121 * #G_FILE_COPY_OVERWRITE is specified and the target is a file, then
22122 * the %G_IO_ERROR_WOULD_RECURSE error may be returned (if the native
22123 * move operation isn't available).
22125 * Returns: %TRUE on successful move, %FALSE otherwise.
22130 * g_file_new_for_commandline_arg:
22131 * @arg: a command line string
22133 * Creates a #GFile with the given argument from the command line.
22134 * The value of @arg can be either a URI, an absolute path or a
22135 * relative path resolved relative to the current working directory.
22136 * This operation never fails, but the returned object might not
22137 * support any I/O operation if @arg points to a malformed path.
22139 * Note that on Windows, this function expects its argument to be in
22140 * UTF-8 -- not the system code page. This means that you
22141 * should not use this function with string from argv as it is passed
22142 * to main(). g_win32_get_command_line() will return a UTF-8 version of
22143 * the commandline. #GApplication also uses UTF-8 but
22144 * g_application_command_line_create_file_for_arg() may be more useful
22145 * for you there. It is also always possible to use this function with
22146 * #GOptionContext arguments of type %G_OPTION_ARG_FILENAME.
22148 * Returns: (transfer full): a new #GFile.
22149 * Free the returned object with g_object_unref().
22154 * g_file_new_for_commandline_arg_and_cwd:
22155 * @arg: a command line string
22156 * @cwd: the current working directory of the commandline
22158 * Creates a #GFile with the given argument from the command line.
22160 * This function is similar to g_file_new_for_commandline_arg() except
22161 * that it allows for passing the current working directory as an
22162 * argument instead of using the current working directory of the
22165 * This is useful if the commandline argument was given in a context
22166 * other than the invocation of the current process.
22168 * See also g_application_command_line_create_file_for_arg().
22170 * Returns: (transfer full): a new #GFile
22176 * g_file_new_for_path:
22177 * @path: a string containing a relative or absolute path.
22178 * The string must be encoded in the glib filename encoding.
22180 * Constructs a #GFile for a given path. This operation never
22181 * fails, but the returned object might not support any I/O
22182 * operation if @path is malformed.
22184 * Returns: (transfer full): a new #GFile for the given @path.
22185 * Free the returned object with g_object_unref().
22190 * g_file_new_for_uri:
22191 * @uri: a UTF-8 string containing a URI
22193 * Constructs a #GFile for a given URI. This operation never
22194 * fails, but the returned object might not support any I/O
22195 * operation if @uri is malformed or if the uri type is
22198 * Returns: (transfer full): a new #GFile for the given @uri.
22199 * Free the returned object with g_object_unref().
22205 * @tmpl: (type filename) (allow-none): Template for the file
22206 * name, as in g_file_open_tmp(), or %NULL for a default template
22207 * @iostream: (out): on return, a #GFileIOStream for the created file
22208 * @error: a #GError, or %NULL
22210 * Opens a file in the preferred directory for temporary files (as
22211 * returned by g_get_tmp_dir()) and returns a #GFile and
22212 * #GFileIOStream pointing to it.
22214 * @tmpl should be a string in the GLib file name encoding
22215 * containing a sequence of six 'X' characters, and containing no
22216 * directory components. If it is %NULL, a default template is used.
22218 * Unlike the other #GFile constructors, this will return %NULL if
22219 * a temporary file could not be created.
22221 * Returns: (transfer full): a new #GFile.
22222 * Free the returned object with g_object_unref().
22228 * g_file_open_readwrite:
22229 * @file: #GFile to open
22230 * @cancellable: (allow-none): a #GCancellable
22231 * @error: a #GError, or %NULL
22233 * Opens an existing file for reading and writing. The result is
22234 * a #GFileIOStream that can be used to read and write the contents
22237 * If @cancellable is not %NULL, then the operation can be cancelled
22238 * by triggering the cancellable object from another thread. If the
22239 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
22242 * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will
22243 * be returned. If the file is a directory, the %G_IO_ERROR_IS_DIRECTORY
22244 * error will be returned. Other errors are possible too, and depend on
22245 * what kind of filesystem the file is on. Note that in many non-local
22246 * file cases read and write streams are not supported, so make sure you
22247 * really need to do read and write streaming, rather than just opening
22248 * for reading or writing.
22250 * Returns: (transfer full): #GFileIOStream or %NULL on error.
22251 * Free the returned object with g_object_unref().
22257 * g_file_open_readwrite_async:
22258 * @file: input #GFile
22259 * @io_priority: the [I/O priority][io-priority] of the request
22260 * @cancellable: (allow-none): optional #GCancellable object,
22262 * @callback: (scope async): a #GAsyncReadyCallback to call
22263 * when the request is satisfied
22264 * @user_data: (closure): the data to pass to callback function
22266 * Asynchronously opens @file for reading and writing.
22268 * For more details, see g_file_open_readwrite() which is
22269 * the synchronous version of this call.
22271 * When the operation is finished, @callback will be called.
22272 * You can then call g_file_open_readwrite_finish() to get
22273 * the result of the operation.
22280 * g_file_open_readwrite_finish:
22281 * @file: input #GFile
22282 * @res: a #GAsyncResult
22283 * @error: a #GError, or %NULL
22285 * Finishes an asynchronous file read operation started with
22286 * g_file_open_readwrite_async().
22288 * Returns: (transfer full): a #GFileIOStream or %NULL on error.
22289 * Free the returned object with g_object_unref().
22295 * g_file_output_stream_get_etag:
22296 * @stream: a #GFileOutputStream.
22298 * Gets the entity tag for the file when it has been written.
22299 * This must be called after the stream has been written
22300 * and closed, as the etag can change while writing.
22302 * Returns: the entity tag for the stream.
22307 * g_file_output_stream_query_info:
22308 * @stream: a #GFileOutputStream.
22309 * @attributes: a file attribute query string.
22310 * @cancellable: optional #GCancellable object, %NULL to ignore.
22311 * @error: a #GError, %NULL to ignore.
22313 * Queries a file output stream for the given @attributes.
22314 * This function blocks while querying the stream. For the asynchronous
22315 * version of this function, see g_file_output_stream_query_info_async().
22316 * While the stream is blocked, the stream will set the pending flag
22317 * internally, and any other operations on the stream will fail with
22318 * %G_IO_ERROR_PENDING.
22320 * Can fail if the stream was already closed (with @error being set to
22321 * %G_IO_ERROR_CLOSED), the stream has pending operations (with @error being
22322 * set to %G_IO_ERROR_PENDING), or if querying info is not supported for
22323 * the stream's interface (with @error being set to %G_IO_ERROR_NOT_SUPPORTED). In
22324 * all cases of failure, %NULL will be returned.
22326 * If @cancellable is not %NULL, then the operation can be cancelled by
22327 * triggering the cancellable object from another thread. If the operation
22328 * was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %NULL will
22331 * Returns: (transfer full): a #GFileInfo for the @stream, or %NULL on error.
22336 * g_file_output_stream_query_info_async:
22337 * @stream: a #GFileOutputStream.
22338 * @attributes: a file attribute query string.
22339 * @io_priority: the [I/O priority][gio-GIOScheduler] of the request
22340 * @cancellable: optional #GCancellable object, %NULL to ignore.
22341 * @callback: callback to call when the request is satisfied
22342 * @user_data: the data to pass to callback function
22344 * Asynchronously queries the @stream for a #GFileInfo. When completed,
22345 * @callback will be called with a #GAsyncResult which can be used to
22346 * finish the operation with g_file_output_stream_query_info_finish().
22348 * For the synchronous version of this function, see
22349 * g_file_output_stream_query_info().
22354 * g_file_output_stream_query_info_finish:
22355 * @stream: a #GFileOutputStream.
22356 * @result: a #GAsyncResult.
22357 * @error: a #GError, %NULL to ignore.
22359 * Finalizes the asynchronous query started
22360 * by g_file_output_stream_query_info_async().
22362 * Returns: (transfer full): A #GFileInfo for the finished query.
22367 * g_file_parse_name:
22368 * @parse_name: a file name or path to be parsed
22370 * Constructs a #GFile with the given @parse_name (i.e. something
22371 * given by g_file_get_parse_name()). This operation never fails,
22372 * but the returned object might not support any I/O operation if
22373 * the @parse_name cannot be parsed.
22375 * Returns: (transfer full): a new #GFile.
22380 * g_file_poll_mountable:
22381 * @file: input #GFile
22382 * @cancellable: optional #GCancellable object, %NULL to ignore
22383 * @callback: (allow-none): a #GAsyncReadyCallback to call
22384 * when the request is satisfied, or %NULL
22385 * @user_data: the data to pass to callback function
22387 * Polls a file of type #G_FILE_TYPE_MOUNTABLE.
22389 * If @cancellable is not %NULL, then the operation can be cancelled by
22390 * triggering the cancellable object from another thread. If the operation
22391 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
22393 * When the operation is finished, @callback will be called.
22394 * You can then call g_file_mount_mountable_finish() to get
22395 * the result of the operation.
22402 * g_file_poll_mountable_finish:
22403 * @file: input #GFile
22404 * @result: a #GAsyncResult
22405 * @error: a #GError, or %NULL
22407 * Finishes a poll operation. See g_file_poll_mountable() for details.
22409 * Finish an asynchronous poll operation that was polled
22410 * with g_file_poll_mountable().
22412 * Returns: %TRUE if the operation finished successfully. %FALSE
22419 * g_file_query_default_handler:
22420 * @file: a #GFile to open
22421 * @cancellable: optional #GCancellable object, %NULL to ignore
22422 * @error: a #GError, or %NULL
22424 * Returns the #GAppInfo that is registered as the default
22425 * application to handle the file specified by @file.
22427 * If @cancellable is not %NULL, then the operation can be cancelled by
22428 * triggering the cancellable object from another thread. If the operation
22429 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
22431 * Returns: (transfer full): a #GAppInfo if the handle was found,
22432 * %NULL if there were errors.
22433 * When you are done with it, release it with g_object_unref()
22438 * g_file_query_exists:
22439 * @file: input #GFile
22440 * @cancellable: (allow-none): optional #GCancellable object,
22443 * Utility function to check if a particular file exists. This is
22444 * implemented using g_file_query_info() and as such does blocking I/O.
22446 * Note that in many cases it is racy to first check for file existence
22447 * and then execute something based on the outcome of that, because the
22448 * file might have been created or removed in between the operations. The
22449 * general approach to handling that is to not check, but just do the
22450 * operation and handle the errors as they come.
22452 * As an example of race-free checking, take the case of reading a file,
22453 * and if it doesn't exist, creating it. There are two racy versions: read
22454 * it, and on error create it; and: check if it exists, if not create it.
22455 * These can both result in two processes creating the file (with perhaps
22456 * a partially written file as the result). The correct approach is to
22457 * always try to create the file with g_file_create() which will either
22458 * atomically create the file or fail with a %G_IO_ERROR_EXISTS error.
22460 * However, in many cases an existence check is useful in a user interface,
22461 * for instance to make a menu item sensitive/insensitive, so that you don't
22462 * have to fool users that something is possible and then just show an error
22463 * dialog. If you do this, you should make sure to also handle the errors
22464 * that can happen due to races when you execute the operation.
22466 * Returns: %TRUE if the file exists (and can be detected without error),
22467 * %FALSE otherwise (or if cancelled).
22472 * g_file_query_file_type:
22473 * @file: input #GFile
22474 * @flags: a set of #GFileQueryInfoFlags passed to g_file_query_info()
22475 * @cancellable: (allow-none): optional #GCancellable object,
22478 * Utility function to inspect the #GFileType of a file. This is
22479 * implemented using g_file_query_info() and as such does blocking I/O.
22481 * The primary use case of this method is to check if a file is
22482 * a regular file, directory, or symlink.
22484 * Returns: The #GFileType of the file and #G_FILE_TYPE_UNKNOWN
22485 * if the file does not exist
22491 * g_file_query_filesystem_info:
22492 * @file: input #GFile
22493 * @attributes: an attribute query string
22494 * @cancellable: (allow-none): optional #GCancellable object,
22496 * @error: a #GError
22498 * Similar to g_file_query_info(), but obtains information
22499 * about the filesystem the @file is on, rather than the file itself.
22500 * For instance the amount of space available and the type of
22503 * The @attributes value is a string that specifies the attributes
22504 * that should be gathered. It is not an error if it's not possible
22505 * to read a particular requested attribute from a file - it just
22506 * won't be set. @attributes should be a comma-separated list of
22507 * attributes or attribute wildcards. The wildcard "*" means all
22508 * attributes, and a wildcard like "filesystem::*" means all attributes
22509 * in the filesystem namespace. The standard namespace for filesystem
22510 * attributes is "filesystem". Common attributes of interest are
22511 * #G_FILE_ATTRIBUTE_FILESYSTEM_SIZE (the total size of the filesystem
22512 * in bytes), #G_FILE_ATTRIBUTE_FILESYSTEM_FREE (number of bytes available),
22513 * and #G_FILE_ATTRIBUTE_FILESYSTEM_TYPE (type of the filesystem).
22515 * If @cancellable is not %NULL, then the operation can be cancelled
22516 * by triggering the cancellable object from another thread. If the
22517 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
22520 * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will
22521 * be returned. Other errors are possible too, and depend on what
22522 * kind of filesystem the file is on.
22524 * Returns: (transfer full): a #GFileInfo or %NULL if there was an error.
22525 * Free the returned object with g_object_unref().
22530 * g_file_query_filesystem_info_async:
22531 * @file: input #GFile
22532 * @attributes: an attribute query string
22533 * @io_priority: the [I/O priority][io-priority] of the request
22534 * @cancellable: (allow-none): optional #GCancellable object,
22536 * @callback: (scope async): a #GAsyncReadyCallback to call
22537 * when the request is satisfied
22538 * @user_data: (closure): the data to pass to callback function
22540 * Asynchronously gets the requested information about the filesystem
22541 * that the specified @file is on. The result is a #GFileInfo object
22542 * that contains key-value attributes (such as type or size for the
22545 * For more details, see g_file_query_filesystem_info() which is the
22546 * synchronous version of this call.
22548 * When the operation is finished, @callback will be called. You can
22549 * then call g_file_query_info_finish() to get the result of the
22555 * g_file_query_filesystem_info_finish:
22556 * @file: input #GFile
22557 * @res: a #GAsyncResult
22558 * @error: a #GError
22560 * Finishes an asynchronous filesystem info query.
22561 * See g_file_query_filesystem_info_async().
22563 * Returns: (transfer full): #GFileInfo for given @file
22564 * or %NULL on error.
22565 * Free the returned object with g_object_unref().
22570 * g_file_query_info:
22571 * @file: input #GFile
22572 * @attributes: an attribute query string
22573 * @flags: a set of #GFileQueryInfoFlags
22574 * @cancellable: (allow-none): optional #GCancellable object,
22576 * @error: a #GError
22578 * Gets the requested information about specified @file.
22579 * The result is a #GFileInfo object that contains key-value
22580 * attributes (such as the type or size of the file).
22582 * The @attributes value is a string that specifies the file
22583 * attributes that should be gathered. It is not an error if
22584 * it's not possible to read a particular requested attribute
22585 * from a file - it just won't be set. @attributes should be a
22586 * comma-separated list of attributes or attribute wildcards.
22587 * The wildcard "*" means all attributes, and a wildcard like
22588 * "standard::*" means all attributes in the standard namespace.
22589 * An example attribute query be "standard::*,owner::user".
22590 * The standard attributes are available as defines, like
22591 * #G_FILE_ATTRIBUTE_STANDARD_NAME.
22593 * If @cancellable is not %NULL, then the operation can be cancelled
22594 * by triggering the cancellable object from another thread. If the
22595 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
22598 * For symlinks, normally the information about the target of the
22599 * symlink is returned, rather than information about the symlink
22600 * itself. However if you pass #G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS
22601 * in @flags the information about the symlink itself will be returned.
22602 * Also, for symlinks that point to non-existing files the information
22603 * about the symlink itself will be returned.
22605 * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will be
22606 * returned. Other errors are possible too, and depend on what kind of
22607 * filesystem the file is on.
22609 * Returns: (transfer full): a #GFileInfo for the given @file, or %NULL
22610 * on error. Free the returned object with g_object_unref().
22615 * g_file_query_info_async:
22616 * @file: input #GFile
22617 * @attributes: an attribute query string
22618 * @flags: a set of #GFileQueryInfoFlags
22619 * @io_priority: the [I/O priority][io-priority] of the request
22620 * @cancellable: (allow-none): optional #GCancellable object,
22622 * @callback: (scope async): a #GAsyncReadyCallback to call when the
22623 * request is satisfied
22624 * @user_data: (closure): the data to pass to callback function
22626 * Asynchronously gets the requested information about specified @file.
22627 * The result is a #GFileInfo object that contains key-value attributes
22628 * (such as type or size for the file).
22630 * For more details, see g_file_query_info() which is the synchronous
22631 * version of this call.
22633 * When the operation is finished, @callback will be called. You can
22634 * then call g_file_query_info_finish() to get the result of the operation.
22639 * g_file_query_info_finish:
22640 * @file: input #GFile
22641 * @res: a #GAsyncResult
22642 * @error: a #GError
22644 * Finishes an asynchronous file info query.
22645 * See g_file_query_info_async().
22647 * Returns: (transfer full): #GFileInfo for given @file
22648 * or %NULL on error. Free the returned object with
22649 * g_object_unref().
22654 * g_file_query_settable_attributes:
22655 * @file: input #GFile
22656 * @cancellable: (allow-none): optional #GCancellable object,
22658 * @error: a #GError, or %NULL
22660 * Obtain the list of settable attributes for the file.
22662 * Returns the type and full attribute name of all the attributes
22663 * that can be set on this file. This doesn't mean setting it will
22664 * always succeed though, you might get an access failure, or some
22665 * specific file may not support a specific attribute.
22667 * If @cancellable is not %NULL, then the operation can be cancelled by
22668 * triggering the cancellable object from another thread. If the operation
22669 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
22671 * Returns: a #GFileAttributeInfoList describing the settable attributes.
22672 * When you are done with it, release it with
22673 * g_file_attribute_info_list_unref()
22678 * g_file_query_writable_namespaces:
22679 * @file: input #GFile
22680 * @cancellable: (allow-none): optional #GCancellable object,
22682 * @error: a #GError, or %NULL
22684 * Obtain the list of attribute namespaces where new attributes
22685 * can be created by a user. An example of this is extended
22686 * attributes (in the "xattr" namespace).
22688 * If @cancellable is not %NULL, then the operation can be cancelled by
22689 * triggering the cancellable object from another thread. If the operation
22690 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
22692 * Returns: a #GFileAttributeInfoList describing the writable namespaces.
22693 * When you are done with it, release it with
22694 * g_file_attribute_info_list_unref()
22699 * g_file_read: (virtual read_fn)
22700 * @file: #GFile to read
22701 * @cancellable: (allow-none): a #GCancellable
22702 * @error: a #GError, or %NULL
22704 * Opens a file for reading. The result is a #GFileInputStream that
22705 * can be used to read the contents of the file.
22707 * If @cancellable is not %NULL, then the operation can be cancelled by
22708 * triggering the cancellable object from another thread. If the operation
22709 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
22711 * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will be
22712 * returned. If the file is a directory, the %G_IO_ERROR_IS_DIRECTORY
22713 * error will be returned. Other errors are possible too, and depend
22714 * on what kind of filesystem the file is on.
22716 * Returns: (transfer full): #GFileInputStream or %NULL on error.
22717 * Free the returned object with g_object_unref().
22722 * g_file_read_async:
22723 * @file: input #GFile
22724 * @io_priority: the [I/O priority][io-priority] of the request
22725 * @cancellable: (allow-none): optional #GCancellable object,
22727 * @callback: (scope async): a #GAsyncReadyCallback to call
22728 * when the request is satisfied
22729 * @user_data: (closure): the data to pass to callback function
22731 * Asynchronously opens @file for reading.
22733 * For more details, see g_file_read() which is
22734 * the synchronous version of this call.
22736 * When the operation is finished, @callback will be called.
22737 * You can then call g_file_read_finish() to get the result
22738 * of the operation.
22743 * g_file_read_finish:
22744 * @file: input #GFile
22745 * @res: a #GAsyncResult
22746 * @error: a #GError, or %NULL
22748 * Finishes an asynchronous file read operation started with
22749 * g_file_read_async().
22751 * Returns: (transfer full): a #GFileInputStream or %NULL on error.
22752 * Free the returned object with g_object_unref().
22758 * @file: input #GFile
22759 * @etag: (allow-none): an optional [entity tag][gfile-etag]
22760 * for the current #GFile, or #NULL to ignore
22761 * @make_backup: %TRUE if a backup should be created
22762 * @flags: a set of #GFileCreateFlags
22763 * @cancellable: (allow-none): optional #GCancellable object,
22765 * @error: a #GError, or %NULL
22767 * Returns an output stream for overwriting the file, possibly
22768 * creating a backup copy of the file first. If the file doesn't exist,
22769 * it will be created.
22771 * This will try to replace the file in the safest way possible so
22772 * that any errors during the writing will not affect an already
22773 * existing copy of the file. For instance, for local files it
22774 * may write to a temporary file and then atomically rename over
22775 * the destination when the stream is closed.
22777 * By default files created are generally readable by everyone,
22778 * but if you pass #G_FILE_CREATE_PRIVATE in @flags the file
22779 * will be made readable only to the current user, to the level that
22780 * is supported on the target filesystem.
22782 * If @cancellable is not %NULL, then the operation can be cancelled
22783 * by triggering the cancellable object from another thread. If the
22784 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
22787 * If you pass in a non-%NULL @etag value, then this value is
22788 * compared to the current entity tag of the file, and if they differ
22789 * an %G_IO_ERROR_WRONG_ETAG error is returned. This generally means
22790 * that the file has been changed since you last read it. You can get
22791 * the new etag from g_file_output_stream_get_etag() after you've
22792 * finished writing and closed the #GFileOutputStream. When you load
22793 * a new file you can use g_file_input_stream_query_info() to get
22794 * the etag of the file.
22796 * If @make_backup is %TRUE, this function will attempt to make a
22797 * backup of the current file before overwriting it. If this fails
22798 * a %G_IO_ERROR_CANT_CREATE_BACKUP error will be returned. If you
22799 * want to replace anyway, try again with @make_backup set to %FALSE.
22801 * If the file is a directory the %G_IO_ERROR_IS_DIRECTORY error will
22802 * be returned, and if the file is some other form of non-regular file
22803 * then a %G_IO_ERROR_NOT_REGULAR_FILE error will be returned. Some
22804 * file systems don't allow all file names, and may return an
22805 * %G_IO_ERROR_INVALID_FILENAME error, and if the name is to long
22806 * %G_IO_ERROR_FILENAME_TOO_LONG will be returned. Other errors are
22807 * possible too, and depend on what kind of filesystem the file is on.
22809 * Returns: (transfer full): a #GFileOutputStream or %NULL on error.
22810 * Free the returned object with g_object_unref().
22815 * g_file_replace_async:
22816 * @file: input #GFile
22817 * @etag: (allow-none): an [entity tag][gfile-etag] for the current #GFile,
22818 * or %NULL to ignore
22819 * @make_backup: %TRUE if a backup should be created
22820 * @flags: a set of #GFileCreateFlags
22821 * @io_priority: the [I/O priority][io-priority] of the request
22822 * @cancellable: (allow-none): optional #GCancellable object,
22824 * @callback: (scope async): a #GAsyncReadyCallback to call
22825 * when the request is satisfied
22826 * @user_data: (closure): the data to pass to callback function
22828 * Asynchronously overwrites the file, replacing the contents,
22829 * possibly creating a backup copy of the file first.
22831 * For more details, see g_file_replace() which is
22832 * the synchronous version of this call.
22834 * When the operation is finished, @callback will be called.
22835 * You can then call g_file_replace_finish() to get the result
22836 * of the operation.
22841 * g_file_replace_contents:
22842 * @file: input #GFile
22843 * @contents: (element-type guint8) (array length=length): a string containing the new contents for @file
22844 * @length: the length of @contents in bytes
22845 * @etag: (allow-none): the old [entity-tag][gfile-etag] for the document,
22847 * @make_backup: %TRUE if a backup should be created
22848 * @flags: a set of #GFileCreateFlags
22849 * @new_etag: (allow-none) (out): a location to a new [entity tag][gfile-etag]
22850 * for the document. This should be freed with g_free() when no longer
22852 * @cancellable: optional #GCancellable object, %NULL to ignore
22853 * @error: a #GError, or %NULL
22855 * Replaces the contents of @file with @contents of @length bytes.
22857 * If @etag is specified (not %NULL), any existing file must have that etag,
22858 * or the error %G_IO_ERROR_WRONG_ETAG will be returned.
22860 * If @make_backup is %TRUE, this function will attempt to make a backup
22863 * If @cancellable is not %NULL, then the operation can be cancelled by
22864 * triggering the cancellable object from another thread. If the operation
22865 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
22867 * The returned @new_etag can be used to verify that the file hasn't
22868 * changed the next time it is saved over.
22870 * Returns: %TRUE if successful. If an error has occurred, this function
22871 * will return %FALSE and set @error appropriately if present.
22876 * g_file_replace_contents_async:
22877 * @file: input #GFile
22878 * @contents: (element-type guint8) (array length=length): string of contents to replace the file with
22879 * @length: the length of @contents in bytes
22880 * @etag: (allow-none): a new [entity tag][gfile-etag] for the @file, or %NULL
22881 * @make_backup: %TRUE if a backup should be created
22882 * @flags: a set of #GFileCreateFlags
22883 * @cancellable: optional #GCancellable object, %NULL to ignore
22884 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
22885 * @user_data: the data to pass to callback function
22887 * Starts an asynchronous replacement of @file with the given
22888 * @contents of @length bytes. @etag will replace the document's
22889 * current entity tag.
22891 * When this operation has completed, @callback will be called with
22892 * @user_user data, and the operation can be finalized with
22893 * g_file_replace_contents_finish().
22895 * If @cancellable is not %NULL, then the operation can be cancelled by
22896 * triggering the cancellable object from another thread. If the operation
22897 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
22899 * If @make_backup is %TRUE, this function will attempt to
22900 * make a backup of @file.
22902 * Note that no copy of @content will be made, so it must stay valid
22903 * until @callback is called. See g_file_replace_contents_bytes_async()
22904 * for a #GBytes version that will automatically hold a reference to the
22905 * contents (without copying) for the duration of the call.
22910 * g_file_replace_contents_bytes_async:
22911 * @file: input #GFile
22912 * @contents: a #GBytes
22913 * @etag: (allow-none): a new [entity tag][gfile-etag] for the @file, or %NULL
22914 * @make_backup: %TRUE if a backup should be created
22915 * @flags: a set of #GFileCreateFlags
22916 * @cancellable: optional #GCancellable object, %NULL to ignore
22917 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
22918 * @user_data: the data to pass to callback function
22920 * Same as g_file_replace_contents_async() but takes a #GBytes input instead.
22921 * This function will keep a ref on @contents until the operation is done.
22922 * Unlike g_file_replace_contents_async() this allows forgetting about the
22923 * content without waiting for the callback.
22925 * When this operation has completed, @callback will be called with
22926 * @user_user data, and the operation can be finalized with
22927 * g_file_replace_contents_finish().
22934 * g_file_replace_contents_finish:
22935 * @file: input #GFile
22936 * @res: a #GAsyncResult
22937 * @new_etag: (out) (allow-none): a location of a new [entity tag][gfile-etag]
22938 * for the document. This should be freed with g_free() when it is no
22939 * longer needed, or %NULL
22940 * @error: a #GError, or %NULL
22942 * Finishes an asynchronous replace of the given @file. See
22943 * g_file_replace_contents_async(). Sets @new_etag to the new entity
22944 * tag for the document, if present.
22946 * Returns: %TRUE on success, %FALSE on failure.
22951 * g_file_replace_finish:
22952 * @file: input #GFile
22953 * @res: a #GAsyncResult
22954 * @error: a #GError, or %NULL
22956 * Finishes an asynchronous file replace operation started with
22957 * g_file_replace_async().
22959 * Returns: (transfer full): a #GFileOutputStream, or %NULL on error.
22960 * Free the returned object with g_object_unref().
22965 * g_file_replace_readwrite:
22967 * @etag: (allow-none): an optional [entity tag][gfile-etag]
22968 * for the current #GFile, or #NULL to ignore
22969 * @make_backup: %TRUE if a backup should be created
22970 * @flags: a set of #GFileCreateFlags
22971 * @cancellable: (allow-none): optional #GCancellable object,
22973 * @error: return location for a #GError, or %NULL
22975 * Returns an output stream for overwriting the file in readwrite mode,
22976 * possibly creating a backup copy of the file first. If the file doesn't
22977 * exist, it will be created.
22979 * For details about the behaviour, see g_file_replace() which does the
22980 * same thing but returns an output stream only.
22982 * Note that in many non-local file cases read and write streams are not
22983 * supported, so make sure you really need to do read and write streaming,
22984 * rather than just opening for reading or writing.
22986 * Returns: (transfer full): a #GFileIOStream or %NULL on error.
22987 * Free the returned object with g_object_unref().
22993 * g_file_replace_readwrite_async:
22994 * @file: input #GFile
22995 * @etag: (allow-none): an [entity tag][gfile-etag] for the current #GFile,
22996 * or %NULL to ignore
22997 * @make_backup: %TRUE if a backup should be created
22998 * @flags: a set of #GFileCreateFlags
22999 * @io_priority: the [I/O priority][io-priority] of the request
23000 * @cancellable: (allow-none): optional #GCancellable object,
23002 * @callback: (scope async): a #GAsyncReadyCallback to call
23003 * when the request is satisfied
23004 * @user_data: (closure): the data to pass to callback function
23006 * Asynchronously overwrites the file in read-write mode,
23007 * replacing the contents, possibly creating a backup copy
23008 * of the file first.
23010 * For more details, see g_file_replace_readwrite() which is
23011 * the synchronous version of this call.
23013 * When the operation is finished, @callback will be called.
23014 * You can then call g_file_replace_readwrite_finish() to get
23015 * the result of the operation.
23022 * g_file_replace_readwrite_finish:
23023 * @file: input #GFile
23024 * @res: a #GAsyncResult
23025 * @error: a #GError, or %NULL
23027 * Finishes an asynchronous file replace operation started with
23028 * g_file_replace_readwrite_async().
23030 * Returns: (transfer full): a #GFileIOStream, or %NULL on error.
23031 * Free the returned object with g_object_unref().
23037 * g_file_resolve_relative_path:
23038 * @file: input #GFile
23039 * @relative_path: a given relative path string
23041 * Resolves a relative path for @file to an absolute path.
23043 * This call does no blocking I/O.
23045 * Returns: (transfer full): #GFile to the resolved path.
23046 * %NULL if @relative_path is %NULL or if @file is invalid.
23047 * Free the returned object with g_object_unref().
23052 * g_file_set_attribute:
23053 * @file: input #GFile
23054 * @attribute: a string containing the attribute's name
23055 * @type: The type of the attribute
23056 * @value_p: (allow-none): a pointer to the value (or the pointer
23057 * itself if the type is a pointer type)
23058 * @flags: a set of #GFileQueryInfoFlags
23059 * @cancellable: (allow-none): optional #GCancellable object,
23061 * @error: a #GError, or %NULL
23063 * Sets an attribute in the file with attribute name @attribute to @value.
23065 * Some attributes can be unset by setting @attribute to
23066 * %G_FILE_ATTRIBUTE_TYPE_INVALID and @value_p to %NULL.
23068 * If @cancellable is not %NULL, then the operation can be cancelled by
23069 * triggering the cancellable object from another thread. If the operation
23070 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
23072 * Returns: %TRUE if the attribute was set, %FALSE otherwise.
23077 * g_file_set_attribute_byte_string:
23078 * @file: input #GFile
23079 * @attribute: a string containing the attribute's name
23080 * @value: a string containing the attribute's new value
23081 * @flags: a #GFileQueryInfoFlags
23082 * @cancellable: (allow-none): optional #GCancellable object,
23084 * @error: a #GError, or %NULL
23086 * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING to @value.
23087 * If @attribute is of a different type, this operation will fail,
23088 * returning %FALSE.
23090 * If @cancellable is not %NULL, then the operation can be cancelled by
23091 * triggering the cancellable object from another thread. If the operation
23092 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
23094 * Returns: %TRUE if the @attribute was successfully set to @value
23095 * in the @file, %FALSE otherwise.
23100 * g_file_set_attribute_int32:
23101 * @file: input #GFile
23102 * @attribute: a string containing the attribute's name
23103 * @value: a #gint32 containing the attribute's new value
23104 * @flags: a #GFileQueryInfoFlags
23105 * @cancellable: (allow-none): optional #GCancellable object,
23107 * @error: a #GError, or %NULL
23109 * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT32 to @value.
23110 * If @attribute is of a different type, this operation will fail.
23112 * If @cancellable is not %NULL, then the operation can be cancelled by
23113 * triggering the cancellable object from another thread. If the operation
23114 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
23116 * Returns: %TRUE if the @attribute was successfully set to @value
23117 * in the @file, %FALSE otherwise.
23122 * g_file_set_attribute_int64:
23123 * @file: input #GFile
23124 * @attribute: a string containing the attribute's name
23125 * @value: a #guint64 containing the attribute's new value
23126 * @flags: a #GFileQueryInfoFlags
23127 * @cancellable: (allow-none): optional #GCancellable object,
23129 * @error: a #GError, or %NULL
23131 * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT64 to @value.
23132 * If @attribute is of a different type, this operation will fail.
23134 * If @cancellable is not %NULL, then the operation can be cancelled by
23135 * triggering the cancellable object from another thread. If the operation
23136 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
23138 * Returns: %TRUE if the @attribute was successfully set, %FALSE otherwise.
23143 * g_file_set_attribute_string:
23144 * @file: input #GFile
23145 * @attribute: a string containing the attribute's name
23146 * @value: a string containing the attribute's value
23147 * @flags: #GFileQueryInfoFlags
23148 * @cancellable: (allow-none): optional #GCancellable object,
23150 * @error: a #GError, or %NULL
23152 * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_STRING to @value.
23153 * If @attribute is of a different type, this operation will fail.
23155 * If @cancellable is not %NULL, then the operation can be cancelled by
23156 * triggering the cancellable object from another thread. If the operation
23157 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
23159 * Returns: %TRUE if the @attribute was successfully set, %FALSE otherwise.
23164 * g_file_set_attribute_uint32:
23165 * @file: input #GFile
23166 * @attribute: a string containing the attribute's name
23167 * @value: a #guint32 containing the attribute's new value
23168 * @flags: a #GFileQueryInfoFlags
23169 * @cancellable: (allow-none): optional #GCancellable object,
23171 * @error: a #GError, or %NULL
23173 * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT32 to @value.
23174 * If @attribute is of a different type, this operation will fail.
23176 * If @cancellable is not %NULL, then the operation can be cancelled by
23177 * triggering the cancellable object from another thread. If the operation
23178 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
23180 * Returns: %TRUE if the @attribute was successfully set to @value
23181 * in the @file, %FALSE otherwise.
23186 * g_file_set_attribute_uint64:
23187 * @file: input #GFile
23188 * @attribute: a string containing the attribute's name
23189 * @value: a #guint64 containing the attribute's new value
23190 * @flags: a #GFileQueryInfoFlags
23191 * @cancellable: (allow-none): optional #GCancellable object,
23193 * @error: a #GError, or %NULL
23195 * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT64 to @value.
23196 * If @attribute is of a different type, this operation will fail.
23198 * If @cancellable is not %NULL, then the operation can be cancelled by
23199 * triggering the cancellable object from another thread. If the operation
23200 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
23202 * Returns: %TRUE if the @attribute was successfully set to @value
23203 * in the @file, %FALSE otherwise.
23208 * g_file_set_attributes_async:
23209 * @file: input #GFile
23210 * @info: a #GFileInfo
23211 * @flags: a #GFileQueryInfoFlags
23212 * @io_priority: the [I/O priority][io-priority] of the request
23213 * @cancellable: (allow-none): optional #GCancellable object,
23215 * @callback: (scope async): a #GAsyncReadyCallback
23216 * @user_data: (closure): a #gpointer
23218 * Asynchronously sets the attributes of @file with @info.
23220 * For more details, see g_file_set_attributes_from_info(),
23221 * which is the synchronous version of this call.
23223 * When the operation is finished, @callback will be called.
23224 * You can then call g_file_set_attributes_finish() to get
23225 * the result of the operation.
23230 * g_file_set_attributes_finish:
23231 * @file: input #GFile
23232 * @result: a #GAsyncResult
23233 * @info: (out) (transfer full): a #GFileInfo
23234 * @error: a #GError, or %NULL
23236 * Finishes setting an attribute started in g_file_set_attributes_async().
23238 * Returns: %TRUE if the attributes were set correctly, %FALSE otherwise.
23243 * g_file_set_attributes_from_info:
23244 * @file: input #GFile
23245 * @info: a #GFileInfo
23246 * @flags: #GFileQueryInfoFlags
23247 * @cancellable: (allow-none): optional #GCancellable object,
23249 * @error: a #GError, or %NULL
23251 * Tries to set all attributes in the #GFileInfo on the target
23252 * values, not stopping on the first error.
23254 * If there is any error during this operation then @error will
23255 * be set to the first error. Error on particular fields are flagged
23256 * by setting the "status" field in the attribute value to
23257 * %G_FILE_ATTRIBUTE_STATUS_ERROR_SETTING, which means you can
23258 * also detect further errors.
23260 * If @cancellable is not %NULL, then the operation can be cancelled by
23261 * triggering the cancellable object from another thread. If the operation
23262 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
23264 * Returns: %FALSE if there was any error, %TRUE otherwise.
23269 * g_file_set_display_name:
23270 * @file: input #GFile
23271 * @display_name: a string
23272 * @cancellable: (allow-none): optional #GCancellable object,
23274 * @error: a #GError, or %NULL
23276 * Renames @file to the specified display name.
23278 * The display name is converted from UTF-8 to the correct encoding
23279 * for the target filesystem if possible and the @file is renamed to this.
23281 * If you want to implement a rename operation in the user interface the
23282 * edit name (#G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME) should be used as the
23283 * initial value in the rename widget, and then the result after editing
23284 * should be passed to g_file_set_display_name().
23286 * On success the resulting converted filename is returned.
23288 * If @cancellable is not %NULL, then the operation can be cancelled by
23289 * triggering the cancellable object from another thread. If the operation
23290 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
23292 * Returns: (transfer full): a #GFile specifying what @file was renamed to,
23293 * or %NULL if there was an error.
23294 * Free the returned object with g_object_unref().
23299 * g_file_set_display_name_async:
23300 * @file: input #GFile
23301 * @display_name: a string
23302 * @io_priority: the [I/O priority][io-priority] of the request
23303 * @cancellable: (allow-none): optional #GCancellable object,
23305 * @callback: (scope async): a #GAsyncReadyCallback to call
23306 * when the request is satisfied
23307 * @user_data: (closure): the data to pass to callback function
23309 * Asynchronously sets the display name for a given #GFile.
23311 * For more details, see g_file_set_display_name() which is
23312 * the synchronous version of this call.
23314 * When the operation is finished, @callback will be called.
23315 * You can then call g_file_set_display_name_finish() to get
23316 * the result of the operation.
23321 * g_file_set_display_name_finish:
23322 * @file: input #GFile
23323 * @res: a #GAsyncResult
23324 * @error: a #GError, or %NULL
23326 * Finishes setting a display name started with
23327 * g_file_set_display_name_async().
23329 * Returns: (transfer full): a #GFile or %NULL on error.
23330 * Free the returned object with g_object_unref().
23335 * g_file_start_mountable:
23336 * @file: input #GFile
23337 * @flags: flags affecting the operation
23338 * @start_operation: (allow-none): a #GMountOperation, or %NULL to avoid user interaction
23339 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
23340 * @callback: (allow-none): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL
23341 * @user_data: the data to pass to callback function
23343 * Starts a file of type #G_FILE_TYPE_MOUNTABLE.
23344 * Using @start_operation, you can request callbacks when, for instance,
23345 * passwords are needed during authentication.
23347 * If @cancellable is not %NULL, then the operation can be cancelled by
23348 * triggering the cancellable object from another thread. If the operation
23349 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
23351 * When the operation is finished, @callback will be called.
23352 * You can then call g_file_mount_mountable_finish() to get
23353 * the result of the operation.
23360 * g_file_start_mountable_finish:
23361 * @file: input #GFile
23362 * @result: a #GAsyncResult
23363 * @error: a #GError, or %NULL
23365 * Finishes a start operation. See g_file_start_mountable() for details.
23367 * Finish an asynchronous start operation that was started
23368 * with g_file_start_mountable().
23370 * Returns: %TRUE if the operation finished successfully. %FALSE
23377 * g_file_stop_mountable:
23378 * @file: input #GFile
23379 * @flags: flags affecting the operation
23380 * @mount_operation: (allow-none): a #GMountOperation,
23381 * or %NULL to avoid user interaction.
23382 * @cancellable: (allow-none): optional #GCancellable object,
23384 * @callback: (allow-none): a #GAsyncReadyCallback to call
23385 * when the request is satisfied, or %NULL
23386 * @user_data: the data to pass to callback function
23388 * Stops a file of type #G_FILE_TYPE_MOUNTABLE.
23390 * If @cancellable is not %NULL, then the operation can be cancelled by
23391 * triggering the cancellable object from another thread. If the operation
23392 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
23394 * When the operation is finished, @callback will be called.
23395 * You can then call g_file_stop_mountable_finish() to get
23396 * the result of the operation.
23403 * g_file_stop_mountable_finish:
23404 * @file: input #GFile
23405 * @result: a #GAsyncResult
23406 * @error: a #GError, or %NULL
23408 * Finishes an stop operation, see g_file_stop_mountable() for details.
23410 * Finish an asynchronous stop operation that was started
23411 * with g_file_stop_mountable().
23413 * Returns: %TRUE if the operation finished successfully.
23414 * %FALSE otherwise.
23420 * g_file_supports_thread_contexts:
23423 * Checks if @file supports
23424 * [thread-default contexts][g-main-context-push-thread-default-context].
23425 * If this returns %FALSE, you cannot perform asynchronous operations on
23426 * @file in a thread that has a thread-default context.
23428 * Returns: Whether or not @file supports thread-default contexts.
23434 * g_file_trash: (virtual trash)
23435 * @file: #GFile to send to trash
23436 * @cancellable: (allow-none): optional #GCancellable object,
23438 * @error: a #GError, or %NULL
23440 * Sends @file to the "Trashcan", if possible. This is similar to
23441 * deleting it, but the user can recover it before emptying the trashcan.
23442 * Not all file systems support trashing, so this call can return the
23443 * %G_IO_ERROR_NOT_SUPPORTED error.
23445 * If @cancellable is not %NULL, then the operation can be cancelled by
23446 * triggering the cancellable object from another thread. If the operation
23447 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
23449 * Returns: %TRUE on successful trash, %FALSE otherwise.
23454 * g_file_trash_async: (virtual trash_async)
23455 * @file: input #GFile
23456 * @io_priority: the [I/O priority][io-priority] of the request
23457 * @cancellable: (allow-none): optional #GCancellable object,
23459 * @callback: a #GAsyncReadyCallback to call
23460 * when the request is satisfied
23461 * @user_data: the data to pass to callback function
23463 * Asynchronously sends @file to the Trash location, if possible.
23470 * g_file_trash_finish: (virtual trash_finish)
23471 * @file: input #GFile
23472 * @result: a #GAsyncResult
23473 * @error: a #GError, or %NULL
23475 * Finishes an asynchronous file trashing operation, started with
23476 * g_file_trash_async().
23478 * Returns: %TRUE on successful trash, %FALSE otherwise.
23484 * g_file_unmount_mountable:
23485 * @file: input #GFile
23486 * @flags: flags affecting the operation
23487 * @cancellable: (allow-none): optional #GCancellable object,
23489 * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call
23490 * when the request is satisfied, or %NULL
23491 * @user_data: (closure): the data to pass to callback function
23493 * Unmounts a file of type G_FILE_TYPE_MOUNTABLE.
23495 * If @cancellable is not %NULL, then the operation can be cancelled by
23496 * triggering the cancellable object from another thread. If the operation
23497 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
23499 * When the operation is finished, @callback will be called.
23500 * You can then call g_file_unmount_mountable_finish() to get
23501 * the result of the operation.
23503 * Deprecated: 2.22: Use g_file_unmount_mountable_with_operation() instead.
23508 * g_file_unmount_mountable_finish:
23509 * @file: input #GFile
23510 * @result: a #GAsyncResult
23511 * @error: a #GError, or %NULL
23513 * Finishes an unmount operation, see g_file_unmount_mountable() for details.
23515 * Finish an asynchronous unmount operation that was started
23516 * with g_file_unmount_mountable().
23518 * Returns: %TRUE if the operation finished successfully.
23519 * %FALSE otherwise.
23520 * Deprecated: 2.22: Use g_file_unmount_mountable_with_operation_finish()
23526 * g_file_unmount_mountable_with_operation:
23527 * @file: input #GFile
23528 * @flags: flags affecting the operation
23529 * @mount_operation: (allow-none): a #GMountOperation,
23530 * or %NULL to avoid user interaction
23531 * @cancellable: (allow-none): optional #GCancellable object,
23533 * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call
23534 * when the request is satisfied, or %NULL
23535 * @user_data: (closure): the data to pass to callback function
23537 * Unmounts a file of type #G_FILE_TYPE_MOUNTABLE.
23539 * If @cancellable is not %NULL, then the operation can be cancelled by
23540 * triggering the cancellable object from another thread. If the operation
23541 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
23543 * When the operation is finished, @callback will be called.
23544 * You can then call g_file_unmount_mountable_finish() to get
23545 * the result of the operation.
23552 * g_file_unmount_mountable_with_operation_finish:
23553 * @file: input #GFile
23554 * @result: a #GAsyncResult
23555 * @error: a #GError, or %NULL
23557 * Finishes an unmount operation,
23558 * see g_file_unmount_mountable_with_operation() for details.
23560 * Finish an asynchronous unmount operation that was started
23561 * with g_file_unmount_mountable_with_operation().
23563 * Returns: %TRUE if the operation finished successfully.
23564 * %FALSE otherwise.
23570 * g_filename_completer_get_completion_suffix:
23571 * @completer: the filename completer.
23572 * @initial_text: text to be completed.
23574 * Obtains a completion for @initial_text from @completer.
23576 * Returns: a completed string, or %NULL if no completion exists.
23577 * This string is not owned by GIO, so remember to g_free() it
23583 * g_filename_completer_get_completions:
23584 * @completer: the filename completer.
23585 * @initial_text: text to be completed.
23587 * Gets an array of completion strings for a given initial text.
23589 * Returns: (array zero-terminated=1) (transfer full): array of strings with possible completions for @initial_text.
23590 * This array must be freed by g_strfreev() when finished.
23595 * g_filename_completer_new:
23597 * Creates a new filename completer.
23599 * Returns: a #GFilenameCompleter.
23604 * g_filename_completer_set_dirs_only:
23605 * @completer: the filename completer.
23606 * @dirs_only: a #gboolean.
23608 * If @dirs_only is %TRUE, @completer will only
23609 * complete directory names, and not file names.
23614 * g_filter_input_stream_get_base_stream:
23615 * @stream: a #GFilterInputStream.
23617 * Gets the base stream for the filter stream.
23619 * Returns: (transfer none): a #GInputStream.
23624 * g_filter_input_stream_get_close_base_stream:
23625 * @stream: a #GFilterInputStream.
23627 * Returns whether the base stream will be closed when @stream is
23630 * Returns: %TRUE if the base stream will be closed.
23635 * g_filter_input_stream_set_close_base_stream:
23636 * @stream: a #GFilterInputStream.
23637 * @close_base: %TRUE to close the base stream.
23639 * Sets whether the base stream will be closed when @stream is closed.
23644 * g_filter_output_stream_get_base_stream:
23645 * @stream: a #GFilterOutputStream.
23647 * Gets the base stream for the filter stream.
23649 * Returns: (transfer none): a #GOutputStream.
23654 * g_filter_output_stream_get_close_base_stream:
23655 * @stream: a #GFilterOutputStream.
23657 * Returns whether the base stream will be closed when @stream is
23660 * Returns: %TRUE if the base stream will be closed.
23665 * g_filter_output_stream_set_close_base_stream:
23666 * @stream: a #GFilterOutputStream.
23667 * @close_base: %TRUE to close the base stream.
23669 * Sets whether the base stream will be closed when @stream is closed.
23674 * g_icon_deserialize:
23675 * @value: a #GVariant created with g_icon_serialize()
23677 * Deserializes a #GIcon previously serialized using g_icon_serialize().
23679 * Returns: (transfer full): a #GIcon, or %NULL when deserialization fails.
23686 * @icon1: (allow-none): pointer to the first #GIcon.
23687 * @icon2: (allow-none): pointer to the second #GIcon.
23689 * Checks if two icons are equal.
23691 * Returns: %TRUE if @icon1 is equal to @icon2. %FALSE otherwise.
23696 * g_icon_hash: (virtual hash)
23697 * @icon: #gconstpointer to an icon object.
23699 * Gets a hash for an icon.
23701 * Returns: a #guint containing a hash for the @icon, suitable for
23702 * use in a #GHashTable or similar data structure.
23707 * g_icon_new_for_string:
23708 * @str: A string obtained via g_icon_to_string().
23709 * @error: Return location for error.
23711 * Generate a #GIcon instance from @str. This function can fail if
23712 * @str is not valid - see g_icon_to_string() for discussion.
23714 * If your application or library provides one or more #GIcon
23715 * implementations you need to ensure that each #GType is registered
23716 * with the type system prior to calling g_icon_new_for_string().
23718 * Returns: (transfer full): An object implementing the #GIcon
23719 * interface or %NULL if @error is set.
23725 * g_icon_serialize:
23728 * Serializes a #GIcon into a #GVariant. An equivalent #GIcon can be retrieved
23729 * back by calling g_icon_deserialize() on the returned value.
23730 * As serialization will avoid using raw icon data when possible, it only
23731 * makes sense to transfer the #GVariant between processes on the same machine,
23732 * (as opposed to over the network), and within the same file system namespace.
23734 * Returns: (transfer full): a #GVariant, or %NULL when serialization fails.
23740 * g_icon_to_string: (virtual to_tokens)
23743 * Generates a textual representation of @icon that can be used for
23744 * serialization such as when passing @icon to a different process or
23745 * saving it to persistent storage. Use g_icon_new_for_string() to
23746 * get @icon back from the returned string.
23748 * The encoding of the returned string is proprietary to #GIcon except
23749 * in the following two cases
23751 * - If @icon is a #GFileIcon, the returned string is a native path
23752 * (such as `/path/to/my icon.png`) without escaping
23753 * if the #GFile for @icon is a native file. If the file is not
23754 * native, the returned string is the result of g_file_get_uri()
23755 * (such as `sftp://path/to/my%20icon.png`).
23757 * - If @icon is a #GThemedIcon with exactly one name, the encoding is
23758 * simply the name (such as `network-server`).
23760 * Returns: (nullable): An allocated NUL-terminated UTF8 string or
23761 * %NULL if @icon can't be serialized. Use g_free() to free.
23767 * g_inet_address_equal:
23768 * @address: A #GInetAddress.
23769 * @other_address: Another #GInetAddress.
23771 * Checks if two #GInetAddress instances are equal, e.g. the same address.
23773 * Returns: %TRUE if @address and @other_address are equal, %FALSE otherwise.
23779 * g_inet_address_get_family:
23780 * @address: a #GInetAddress
23782 * Gets @address's family
23784 * Returns: @address's family
23790 * g_inet_address_get_is_any:
23791 * @address: a #GInetAddress
23793 * Tests whether @address is the "any" address for its family.
23795 * Returns: %TRUE if @address is the "any" address for its family.
23801 * g_inet_address_get_is_link_local:
23802 * @address: a #GInetAddress
23804 * Tests whether @address is a link-local address (that is, if it
23805 * identifies a host on a local network that is not connected to the
23808 * Returns: %TRUE if @address is a link-local address.
23814 * g_inet_address_get_is_loopback:
23815 * @address: a #GInetAddress
23817 * Tests whether @address is the loopback address for its family.
23819 * Returns: %TRUE if @address is the loopback address for its family.
23825 * g_inet_address_get_is_mc_global:
23826 * @address: a #GInetAddress
23828 * Tests whether @address is a global multicast address.
23830 * Returns: %TRUE if @address is a global multicast address.
23836 * g_inet_address_get_is_mc_link_local:
23837 * @address: a #GInetAddress
23839 * Tests whether @address is a link-local multicast address.
23841 * Returns: %TRUE if @address is a link-local multicast address.
23847 * g_inet_address_get_is_mc_node_local:
23848 * @address: a #GInetAddress
23850 * Tests whether @address is a node-local multicast address.
23852 * Returns: %TRUE if @address is a node-local multicast address.
23858 * g_inet_address_get_is_mc_org_local:
23859 * @address: a #GInetAddress
23861 * Tests whether @address is an organization-local multicast address.
23863 * Returns: %TRUE if @address is an organization-local multicast address.
23869 * g_inet_address_get_is_mc_site_local:
23870 * @address: a #GInetAddress
23872 * Tests whether @address is a site-local multicast address.
23874 * Returns: %TRUE if @address is a site-local multicast address.
23880 * g_inet_address_get_is_multicast:
23881 * @address: a #GInetAddress
23883 * Tests whether @address is a multicast address.
23885 * Returns: %TRUE if @address is a multicast address.
23891 * g_inet_address_get_is_site_local:
23892 * @address: a #GInetAddress
23894 * Tests whether @address is a site-local address such as 10.0.0.1
23895 * (that is, the address identifies a host on a local network that can
23896 * not be reached directly from the Internet, but which may have
23897 * outgoing Internet connectivity via a NAT or firewall).
23899 * Returns: %TRUE if @address is a site-local address.
23905 * g_inet_address_get_native_size:
23906 * @address: a #GInetAddress
23908 * Gets the size of the native raw binary address for @address. This
23909 * is the size of the data that you get from g_inet_address_to_bytes().
23911 * Returns: the number of bytes used for the native version of @address.
23917 * g_inet_address_mask_equal:
23918 * @mask: a #GInetAddressMask
23919 * @mask2: another #GInetAddressMask
23921 * Tests if @mask and @mask2 are the same mask.
23923 * Returns: whether @mask and @mask2 are the same mask
23929 * g_inet_address_mask_get_address:
23930 * @mask: a #GInetAddressMask
23932 * Gets @mask's base address
23934 * Returns: (transfer none): @mask's base address
23940 * g_inet_address_mask_get_family:
23941 * @mask: a #GInetAddressMask
23943 * Gets the #GSocketFamily of @mask's address
23945 * Returns: the #GSocketFamily of @mask's address
23951 * g_inet_address_mask_get_length:
23952 * @mask: a #GInetAddressMask
23954 * Gets @mask's length
23956 * Returns: @mask's length
23962 * g_inet_address_mask_matches:
23963 * @mask: a #GInetAddressMask
23964 * @address: a #GInetAddress
23966 * Tests if @address falls within the range described by @mask.
23968 * Returns: whether @address falls within the range described by
23975 * g_inet_address_mask_new:
23976 * @addr: a #GInetAddress
23977 * @length: number of bits of @addr to use
23978 * @error: return location for #GError, or %NULL
23980 * Creates a new #GInetAddressMask representing all addresses whose
23981 * first @length bits match @addr.
23983 * Returns: a new #GInetAddressMask, or %NULL on error
23989 * g_inet_address_mask_new_from_string:
23990 * @mask_string: an IP address or address/length string
23991 * @error: return location for #GError, or %NULL
23993 * Parses @mask_string as an IP address and (optional) length, and
23994 * creates a new #GInetAddressMask. The length, if present, is
23995 * delimited by a "/". If it is not present, then the length is
23996 * assumed to be the full length of the address.
23998 * Returns: a new #GInetAddressMask corresponding to @string, or %NULL
24005 * g_inet_address_mask_to_string:
24006 * @mask: a #GInetAddressMask
24008 * Converts @mask back to its corresponding string form.
24010 * Returns: a string corresponding to @mask.
24016 * g_inet_address_new_any:
24017 * @family: the address family
24019 * Creates a #GInetAddress for the "any" address (unassigned/"don't
24020 * care") for @family.
24022 * Returns: a new #GInetAddress corresponding to the "any" address
24029 * g_inet_address_new_from_bytes:
24030 * @bytes: (array) (element-type guint8): raw address data
24031 * @family: the address family of @bytes
24033 * Creates a new #GInetAddress from the given @family and @bytes.
24034 * @bytes should be 4 bytes for %G_SOCKET_FAMILY_IPV4 and 16 bytes for
24035 * %G_SOCKET_FAMILY_IPV6.
24037 * Returns: a new #GInetAddress corresponding to @family and @bytes.
24043 * g_inet_address_new_from_string:
24044 * @string: a string representation of an IP address
24046 * Parses @string as an IP address and creates a new #GInetAddress.
24048 * Returns: a new #GInetAddress corresponding to @string, or %NULL if
24049 * @string could not be parsed.
24055 * g_inet_address_new_loopback:
24056 * @family: the address family
24058 * Creates a #GInetAddress for the loopback address for @family.
24060 * Returns: a new #GInetAddress corresponding to the loopback address
24067 * g_inet_address_to_bytes: (skip)
24068 * @address: a #GInetAddress
24070 * Gets the raw binary address data from @address.
24072 * Returns: a pointer to an internal array of the bytes in @address,
24073 * which should not be modified, stored, or freed. The size of this
24074 * array can be gotten with g_inet_address_get_native_size().
24080 * g_inet_address_to_string:
24081 * @address: a #GInetAddress
24083 * Converts @address to string form.
24085 * Returns: a representation of @address as a string, which should be
24092 * g_inet_socket_address_get_address:
24093 * @address: a #GInetSocketAddress
24095 * Gets @address's #GInetAddress.
24097 * Returns: (transfer none): the #GInetAddress for @address, which must be
24098 * g_object_ref()'d if it will be stored
24104 * g_inet_socket_address_get_flowinfo:
24105 * @address: a %G_SOCKET_FAMILY_IPV6 #GInetSocketAddress
24107 * Gets the `sin6_flowinfo` field from @address,
24108 * which must be an IPv6 address.
24110 * Returns: the flowinfo field
24116 * g_inet_socket_address_get_port:
24117 * @address: a #GInetSocketAddress
24119 * Gets @address's port.
24121 * Returns: the port for @address
24127 * g_inet_socket_address_get_scope_id:
24128 * @address: a %G_SOCKET_FAMILY_IPV6 #GInetAddress
24130 * Gets the `sin6_scope_id` field from @address,
24131 * which must be an IPv6 address.
24133 * Returns: the scope id field
24139 * g_inet_socket_address_new:
24140 * @address: a #GInetAddress
24141 * @port: a port number
24143 * Creates a new #GInetSocketAddress for @address and @port.
24145 * Returns: a new #GInetSocketAddress
24151 * g_inet_socket_address_new_from_string:
24152 * @address: the string form of an IP address
24153 * @port: a port number
24155 * Creates a new #GInetSocketAddress for @address and @port.
24157 * If @address is an IPv6 address, it can also contain a scope ID
24158 * (separated from the address by a "<literal>%</literal>").
24160 * Returns: a new #GInetSocketAddress, or %NULL if @address cannot be
24168 * @initable: a #GInitable.
24169 * @cancellable: optional #GCancellable object, %NULL to ignore.
24170 * @error: a #GError location to store the error occurring, or %NULL to
24173 * Initializes the object implementing the interface.
24175 * The object must be initialized before any real use after initial
24176 * construction, either with this function or g_async_initable_init_async().
24178 * Implementations may also support cancellation. If @cancellable is not %NULL,
24179 * then initialization can be cancelled by triggering the cancellable object
24180 * from another thread. If the operation was cancelled, the error
24181 * %G_IO_ERROR_CANCELLED will be returned. If @cancellable is not %NULL and
24182 * the object doesn't support cancellable initialization the error
24183 * %G_IO_ERROR_NOT_SUPPORTED will be returned.
24185 * If the object is not initialized, or initialization returns with an
24186 * error, then all operations on the object except g_object_ref() and
24187 * g_object_unref() are considered to be invalid, and have undefined
24188 * behaviour. See the [introduction][ginitable] for more details.
24190 * Implementations of this method must be idempotent, i.e. multiple calls
24191 * to this function with the same argument should return the same results.
24192 * Only the first call initializes the object, further calls return the result
24193 * of the first call. This is so that it's safe to implement the singleton
24194 * pattern in the GObject constructor function.
24196 * Returns: %TRUE if successful. If an error has occurred, this function will
24197 * return %FALSE and set @error appropriately if present.
24204 * @object_type: a #GType supporting #GInitable.
24205 * @cancellable: optional #GCancellable object, %NULL to ignore.
24206 * @error: a #GError location to store the error occurring, or %NULL to
24208 * @first_property_name: (allow-none): the name of the first property, or %NULL if no
24210 * @...: the value if the first property, followed by and other property
24211 * value pairs, and ended by %NULL.
24213 * Helper function for constructing #GInitable object. This is
24214 * similar to g_object_new() but also initializes the object
24215 * and returns %NULL, setting an error on failure.
24217 * Returns: (type GObject.Object) (transfer full): a newly allocated
24218 * #GObject, or %NULL on error
24224 * g_initable_new_valist:
24225 * @object_type: a #GType supporting #GInitable.
24226 * @first_property_name: the name of the first property, followed by
24227 * the value, and other property value pairs, and ended by %NULL.
24228 * @var_args: The var args list generated from @first_property_name.
24229 * @cancellable: optional #GCancellable object, %NULL to ignore.
24230 * @error: a #GError location to store the error occurring, or %NULL to
24233 * Helper function for constructing #GInitable object. This is
24234 * similar to g_object_new_valist() but also initializes the object
24235 * and returns %NULL, setting an error on failure.
24237 * Returns: (type GObject.Object) (transfer full): a newly allocated
24238 * #GObject, or %NULL on error
24245 * @object_type: a #GType supporting #GInitable.
24246 * @n_parameters: the number of parameters in @parameters
24247 * @parameters: (array length=n_parameters): the parameters to use to construct the object
24248 * @cancellable: optional #GCancellable object, %NULL to ignore.
24249 * @error: a #GError location to store the error occurring, or %NULL to
24252 * Helper function for constructing #GInitable object. This is
24253 * similar to g_object_newv() but also initializes the object
24254 * and returns %NULL, setting an error on failure.
24256 * Returns: (type GObject.Object) (transfer full): a newly allocated
24257 * #GObject, or %NULL on error
24263 * g_input_stream_async_read_is_via_threads:
24264 * @stream: input stream
24266 * Checks if an input stream's read_async function uses threads.
24268 * Returns: %TRUE if @stream's read_async function uses threads.
24273 * g_input_stream_clear_pending:
24274 * @stream: input stream
24276 * Clears the pending flag on @stream.
24281 * g_input_stream_close:
24282 * @stream: A #GInputStream.
24283 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
24284 * @error: location to store the error occurring, or %NULL to ignore
24286 * Closes the stream, releasing resources related to it.
24288 * Once the stream is closed, all other operations will return %G_IO_ERROR_CLOSED.
24289 * Closing a stream multiple times will not return an error.
24291 * Streams will be automatically closed when the last reference
24292 * is dropped, but you might want to call this function to make sure
24293 * resources are released as early as possible.
24295 * Some streams might keep the backing store of the stream (e.g. a file descriptor)
24296 * open after the stream is closed. See the documentation for the individual
24297 * stream for details.
24299 * On failure the first error that happened will be reported, but the close
24300 * operation will finish as much as possible. A stream that failed to
24301 * close will still return %G_IO_ERROR_CLOSED for all operations. Still, it
24302 * is important to check and report the error to the user.
24304 * If @cancellable is not %NULL, then the operation can be cancelled by
24305 * triggering the cancellable object from another thread. If the operation
24306 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
24307 * Cancelling a close will still leave the stream closed, but some streams
24308 * can use a faster close that doesn't block to e.g. check errors.
24310 * Returns: %TRUE on success, %FALSE on failure
24315 * g_input_stream_close_async:
24316 * @stream: A #GInputStream.
24317 * @io_priority: the [I/O priority][io-priority] of the request
24318 * @cancellable: (allow-none): optional cancellable object
24319 * @callback: (scope async): callback to call when the request is satisfied
24320 * @user_data: (closure): the data to pass to callback function
24322 * Requests an asynchronous closes of the stream, releasing resources related to it.
24323 * When the operation is finished @callback will be called.
24324 * You can then call g_input_stream_close_finish() to get the result of the
24327 * For behaviour details see g_input_stream_close().
24329 * The asyncronous methods have a default fallback that uses threads to implement
24330 * asynchronicity, so they are optional for inheriting classes. However, if you
24331 * override one you must override all.
24336 * g_input_stream_close_finish:
24337 * @stream: a #GInputStream.
24338 * @result: a #GAsyncResult.
24339 * @error: a #GError location to store the error occurring, or %NULL to
24342 * Finishes closing a stream asynchronously, started from g_input_stream_close_async().
24344 * Returns: %TRUE if the stream was closed successfully.
24349 * g_input_stream_has_pending:
24350 * @stream: input stream.
24352 * Checks if an input stream has pending actions.
24354 * Returns: %TRUE if @stream has pending actions.
24359 * g_input_stream_is_closed:
24360 * @stream: input stream.
24362 * Checks if an input stream is closed.
24364 * Returns: %TRUE if the stream is closed.
24369 * g_input_stream_read:
24370 * @stream: a #GInputStream.
24371 * @buffer: (array length=count) (element-type guint8): a buffer to
24372 * read data into (which should be at least count bytes long).
24373 * @count: the number of bytes that will be read from the stream
24374 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
24375 * @error: location to store the error occurring, or %NULL to ignore
24377 * Tries to read @count bytes from the stream into the buffer starting at
24378 * @buffer. Will block during this read.
24380 * If count is zero returns zero and does nothing. A value of @count
24381 * larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
24383 * On success, the number of bytes read into the buffer is returned.
24384 * It is not an error if this is not the same as the requested size, as it
24385 * can happen e.g. near the end of a file. Zero is returned on end of file
24386 * (or if @count is zero), but never otherwise.
24388 * The returned @buffer is not a nul-terminated string, it can contain nul bytes
24389 * at any position, and this function doesn't nul-terminate the @buffer.
24391 * If @cancellable is not %NULL, then the operation can be cancelled by
24392 * triggering the cancellable object from another thread. If the operation
24393 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
24394 * operation was partially finished when the operation was cancelled the
24395 * partial result will be returned, without an error.
24397 * On error -1 is returned and @error is set accordingly.
24399 * Returns: Number of bytes read, or -1 on error, or 0 on end of file.
24404 * g_input_stream_read_all:
24405 * @stream: a #GInputStream.
24406 * @buffer: (array length=count) (element-type guint8): a buffer to
24407 * read data into (which should be at least count bytes long).
24408 * @count: the number of bytes that will be read from the stream
24409 * @bytes_read: (out): location to store the number of bytes that was read from the stream
24410 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
24411 * @error: location to store the error occurring, or %NULL to ignore
24413 * Tries to read @count bytes from the stream into the buffer starting at
24414 * @buffer. Will block during this read.
24416 * This function is similar to g_input_stream_read(), except it tries to
24417 * read as many bytes as requested, only stopping on an error or end of stream.
24419 * On a successful read of @count bytes, or if we reached the end of the
24420 * stream, %TRUE is returned, and @bytes_read is set to the number of bytes
24421 * read into @buffer.
24423 * If there is an error during the operation %FALSE is returned and @error
24424 * is set to indicate the error status, @bytes_read is updated to contain
24425 * the number of bytes read into @buffer before the error occurred.
24427 * Returns: %TRUE on success, %FALSE if there was an error
24432 * g_input_stream_read_async:
24433 * @stream: A #GInputStream.
24434 * @buffer: (array length=count) (element-type guint8): a buffer to
24435 * read data into (which should be at least count bytes long).
24436 * @count: the number of bytes that will be read from the stream
24437 * @io_priority: the [I/O priority][io-priority]
24439 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
24440 * @callback: (scope async): callback to call when the request is satisfied
24441 * @user_data: (closure): the data to pass to callback function
24443 * Request an asynchronous read of @count bytes from the stream into the buffer
24444 * starting at @buffer. When the operation is finished @callback will be called.
24445 * You can then call g_input_stream_read_finish() to get the result of the
24448 * During an async request no other sync and async calls are allowed on @stream, and will
24449 * result in %G_IO_ERROR_PENDING errors.
24451 * A value of @count larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
24453 * On success, the number of bytes read into the buffer will be passed to the
24454 * callback. It is not an error if this is not the same as the requested size, as it
24455 * can happen e.g. near the end of a file, but generally we try to read
24456 * as many bytes as requested. Zero is returned on end of file
24457 * (or if @count is zero), but never otherwise.
24459 * Any outstanding i/o request with higher priority (lower numerical value) will
24460 * be executed before an outstanding request with lower priority. Default
24461 * priority is %G_PRIORITY_DEFAULT.
24463 * The asyncronous methods have a default fallback that uses threads to implement
24464 * asynchronicity, so they are optional for inheriting classes. However, if you
24465 * override one you must override all.
24470 * g_input_stream_read_bytes:
24471 * @stream: a #GInputStream.
24472 * @count: maximum number of bytes that will be read from the stream. Common
24473 * values include 4096 and 8192.
24474 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
24475 * @error: location to store the error occurring, or %NULL to ignore
24477 * Like g_input_stream_read(), this tries to read @count bytes from
24478 * the stream in a blocking fashion. However, rather than reading into
24479 * a user-supplied buffer, this will create a new #GBytes containing
24480 * the data that was read. This may be easier to use from language
24483 * If count is zero, returns a zero-length #GBytes and does nothing. A
24484 * value of @count larger than %G_MAXSSIZE will cause a
24485 * %G_IO_ERROR_INVALID_ARGUMENT error.
24487 * On success, a new #GBytes is returned. It is not an error if the
24488 * size of this object is not the same as the requested size, as it
24489 * can happen e.g. near the end of a file. A zero-length #GBytes is
24490 * returned on end of file (or if @count is zero), but never
24493 * If @cancellable is not %NULL, then the operation can be cancelled by
24494 * triggering the cancellable object from another thread. If the operation
24495 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
24496 * operation was partially finished when the operation was cancelled the
24497 * partial result will be returned, without an error.
24499 * On error %NULL is returned and @error is set accordingly.
24501 * Returns: a new #GBytes, or %NULL on error
24507 * g_input_stream_read_bytes_async:
24508 * @stream: A #GInputStream.
24509 * @count: the number of bytes that will be read from the stream
24510 * @io_priority: the [I/O priority][io-priority] of the request
24511 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
24512 * @callback: (scope async): callback to call when the request is satisfied
24513 * @user_data: (closure): the data to pass to callback function
24515 * Request an asynchronous read of @count bytes from the stream into a
24516 * new #GBytes. When the operation is finished @callback will be
24517 * called. You can then call g_input_stream_read_bytes_finish() to get the
24518 * result of the operation.
24520 * During an async request no other sync and async calls are allowed
24521 * on @stream, and will result in %G_IO_ERROR_PENDING errors.
24523 * A value of @count larger than %G_MAXSSIZE will cause a
24524 * %G_IO_ERROR_INVALID_ARGUMENT error.
24526 * On success, the new #GBytes will be passed to the callback. It is
24527 * not an error if this is smaller than the requested size, as it can
24528 * happen e.g. near the end of a file, but generally we try to read as
24529 * many bytes as requested. Zero is returned on end of file (or if
24530 * @count is zero), but never otherwise.
24532 * Any outstanding I/O request with higher priority (lower numerical
24533 * value) will be executed before an outstanding request with lower
24534 * priority. Default priority is %G_PRIORITY_DEFAULT.
24541 * g_input_stream_read_bytes_finish:
24542 * @stream: a #GInputStream.
24543 * @result: a #GAsyncResult.
24544 * @error: a #GError location to store the error occurring, or %NULL to
24547 * Finishes an asynchronous stream read-into-#GBytes operation.
24549 * Returns: the newly-allocated #GBytes, or %NULL on error
24555 * g_input_stream_read_finish:
24556 * @stream: a #GInputStream.
24557 * @result: a #GAsyncResult.
24558 * @error: a #GError location to store the error occurring, or %NULL to
24561 * Finishes an asynchronous stream read operation.
24563 * Returns: number of bytes read in, or -1 on error, or 0 on end of file.
24568 * g_input_stream_set_pending:
24569 * @stream: input stream
24570 * @error: a #GError location to store the error occurring, or %NULL to
24573 * Sets @stream to have actions pending. If the pending flag is
24574 * already set or @stream is closed, it will return %FALSE and set
24577 * Returns: %TRUE if pending was previously unset and is now set.
24582 * g_input_stream_skip:
24583 * @stream: a #GInputStream.
24584 * @count: the number of bytes that will be skipped from the stream
24585 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
24586 * @error: location to store the error occurring, or %NULL to ignore
24588 * Tries to skip @count bytes from the stream. Will block during the operation.
24590 * This is identical to g_input_stream_read(), from a behaviour standpoint,
24591 * but the bytes that are skipped are not returned to the user. Some
24592 * streams have an implementation that is more efficient than reading the data.
24594 * This function is optional for inherited classes, as the default implementation
24595 * emulates it using read.
24597 * If @cancellable is not %NULL, then the operation can be cancelled by
24598 * triggering the cancellable object from another thread. If the operation
24599 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
24600 * operation was partially finished when the operation was cancelled the
24601 * partial result will be returned, without an error.
24603 * Returns: Number of bytes skipped, or -1 on error
24608 * g_input_stream_skip_async:
24609 * @stream: A #GInputStream.
24610 * @count: the number of bytes that will be skipped from the stream
24611 * @io_priority: the [I/O priority][io-priority] of the request
24612 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
24613 * @callback: (scope async): callback to call when the request is satisfied
24614 * @user_data: (closure): the data to pass to callback function
24616 * Request an asynchronous skip of @count bytes from the stream.
24617 * When the operation is finished @callback will be called.
24618 * You can then call g_input_stream_skip_finish() to get the result
24619 * of the operation.
24621 * During an async request no other sync and async calls are allowed,
24622 * and will result in %G_IO_ERROR_PENDING errors.
24624 * A value of @count larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
24626 * On success, the number of bytes skipped will be passed to the callback.
24627 * It is not an error if this is not the same as the requested size, as it
24628 * can happen e.g. near the end of a file, but generally we try to skip
24629 * as many bytes as requested. Zero is returned on end of file
24630 * (or if @count is zero), but never otherwise.
24632 * Any outstanding i/o request with higher priority (lower numerical value)
24633 * will be executed before an outstanding request with lower priority.
24634 * Default priority is %G_PRIORITY_DEFAULT.
24636 * The asynchronous methods have a default fallback that uses threads to
24637 * implement asynchronicity, so they are optional for inheriting classes.
24638 * However, if you override one, you must override all.
24643 * g_input_stream_skip_finish:
24644 * @stream: a #GInputStream.
24645 * @result: a #GAsyncResult.
24646 * @error: a #GError location to store the error occurring, or %NULL to
24649 * Finishes a stream skip operation.
24651 * Returns: the size of the bytes skipped, or %-1 on error.
24656 * g_io_error_from_errno:
24657 * @err_no: Error number as defined in errno.h.
24659 * Converts errno.h error codes into GIO error codes. The fallback
24660 * value %G_IO_ERROR_FAILED is returned for error codes not currently
24661 * handled (but note that future GLib releases may return a more
24662 * specific value instead).
24664 * Returns: #GIOErrorEnum value for the given errno.h error number.
24669 * g_io_error_from_win32_error:
24670 * @error_code: Windows error number.
24672 * Converts some common error codes (as returned from GetLastError()
24673 * or WSAGetLastError()) into GIO error codes. The fallback value
24674 * %G_IO_ERROR_FAILED is returned for error codes not currently
24675 * handled (but note that future GLib releases may return a more
24676 * specific value instead).
24678 * You can use g_win32_error_message() to get a localized string
24679 * corresponding to @error_code. (But note that unlike g_strerror(),
24680 * g_win32_error_message() returns a string that must be freed.)
24682 * Returns: #GIOErrorEnum value for the given error number.
24688 * g_io_error_quark:
24690 * Gets the GIO Error Quark.
24692 * Returns: a #GQuark.
24697 * g_io_extension_get_name:
24698 * @extension: a #GIOExtension
24700 * Gets the name under which @extension was registered.
24702 * Note that the same type may be registered as extension
24703 * for multiple extension points, under different names.
24705 * Returns: the name of @extension.
24710 * g_io_extension_get_priority:
24711 * @extension: a #GIOExtension
24713 * Gets the priority with which @extension was registered.
24715 * Returns: the priority of @extension
24720 * g_io_extension_get_type:
24721 * @extension: a #GIOExtension
24723 * Gets the type associated with @extension.
24725 * Returns: the type of @extension
24730 * g_io_extension_point_get_extension_by_name:
24731 * @extension_point: a #GIOExtensionPoint
24732 * @name: the name of the extension to get
24734 * Finds a #GIOExtension for an extension point by name.
24736 * Returns: (transfer none): the #GIOExtension for @extension_point that has the
24737 * given name, or %NULL if there is no extension with that name
24742 * g_io_extension_point_get_extensions:
24743 * @extension_point: a #GIOExtensionPoint
24745 * Gets a list of all extensions that implement this extension point.
24746 * The list is sorted by priority, beginning with the highest priority.
24748 * Returns: (element-type GIOExtension) (transfer none): a #GList of
24749 * #GIOExtensions. The list is owned by GIO and should not be
24755 * g_io_extension_point_get_required_type:
24756 * @extension_point: a #GIOExtensionPoint
24758 * Gets the required type for @extension_point.
24760 * Returns: the #GType that all implementations must have,
24761 * or #G_TYPE_INVALID if the extension point has no required type
24766 * g_io_extension_point_implement:
24767 * @extension_point_name: the name of the extension point
24768 * @type: the #GType to register as extension
24769 * @extension_name: the name for the extension
24770 * @priority: the priority for the extension
24772 * Registers @type as extension for the extension point with name
24773 * @extension_point_name.
24775 * If @type has already been registered as an extension for this
24776 * extension point, the existing #GIOExtension object is returned.
24778 * Returns: (transfer none): a #GIOExtension object for #GType
24783 * g_io_extension_point_lookup:
24784 * @name: the name of the extension point
24786 * Looks up an existing extension point.
24788 * Returns: (transfer none): the #GIOExtensionPoint, or %NULL if there
24789 * is no registered extension point with the given name.
24794 * g_io_extension_point_register:
24795 * @name: The name of the extension point
24797 * Registers an extension point.
24799 * Returns: (transfer none): the new #GIOExtensionPoint. This object is
24800 * owned by GIO and should not be freed.
24805 * g_io_extension_point_set_required_type:
24806 * @extension_point: a #GIOExtensionPoint
24807 * @type: the #GType to require
24809 * Sets the required type for @extension_point to @type.
24810 * All implementations must henceforth have this type.
24815 * g_io_extension_ref_class:
24816 * @extension: a #GIOExtension
24818 * Gets a reference to the class for the type that is
24819 * associated with @extension.
24821 * Returns: (transfer full): the #GTypeClass for the type of @extension
24827 * @filename: filename of the shared library module.
24829 * Creates a new GIOModule that will load the specific
24830 * shared library when in use.
24832 * Returns: a #GIOModule from given @filename,
24833 * or %NULL on error.
24838 * g_io_module_scope_block:
24839 * @scope: a module loading scope
24840 * @basename: the basename to block
24842 * Block modules with the given @basename from being loaded when
24843 * this scope is used with g_io_modules_scan_all_in_directory_with_scope()
24844 * or g_io_modules_load_all_in_directory_with_scope().
24851 * g_io_module_scope_free:
24852 * @scope: a module loading scope
24854 * Free a module scope.
24861 * g_io_module_scope_new:
24862 * @flags: flags for the new scope
24864 * Create a new scope for loading of IO modules. A scope can be used for
24865 * blocking duplicate modules, or blocking a module you don't want to load.
24867 * Specify the %G_IO_MODULE_SCOPE_BLOCK_DUPLICATES flag to block modules
24868 * which have the same base name as a module that has already been seen
24871 * Returns: (transfer full): the new module scope
24877 * g_io_modules_load_all_in_directory:
24878 * @dirname: pathname for a directory containing modules to load.
24880 * Loads all the modules in the specified directory.
24882 * If don't require all modules to be initialized (and thus registering
24883 * all gtypes) then you can use g_io_modules_scan_all_in_directory()
24884 * which allows delayed/lazy loading of modules.
24886 * Returns: (element-type GIOModule) (transfer full): a list of #GIOModules loaded
24887 * from the directory,
24888 * All the modules are loaded into memory, if you want to
24889 * unload them (enabling on-demand loading) you must call
24890 * g_type_module_unuse() on all the modules. Free the list
24891 * with g_list_free().
24896 * g_io_modules_load_all_in_directory_with_scope:
24897 * @dirname: pathname for a directory containing modules to load.
24898 * @scope: a scope to use when scanning the modules.
24900 * Loads all the modules in the specified directory.
24902 * If don't require all modules to be initialized (and thus registering
24903 * all gtypes) then you can use g_io_modules_scan_all_in_directory()
24904 * which allows delayed/lazy loading of modules.
24906 * Returns: (element-type GIOModule) (transfer full): a list of #GIOModules loaded
24907 * from the directory,
24908 * All the modules are loaded into memory, if you want to
24909 * unload them (enabling on-demand loading) you must call
24910 * g_type_module_unuse() on all the modules. Free the list
24911 * with g_list_free().
24917 * g_io_modules_scan_all_in_directory:
24918 * @dirname: pathname for a directory containing modules to scan.
24920 * Scans all the modules in the specified directory, ensuring that
24921 * any extension point implemented by a module is registered.
24923 * This may not actually load and initialize all the types in each
24924 * module, some modules may be lazily loaded and initialized when
24925 * an extension point it implementes is used with e.g.
24926 * g_io_extension_point_get_extensions() or
24927 * g_io_extension_point_get_extension_by_name().
24929 * If you need to guarantee that all types are loaded in all the modules,
24930 * use g_io_modules_load_all_in_directory().
24937 * g_io_modules_scan_all_in_directory_with_scope:
24938 * @dirname: pathname for a directory containing modules to scan.
24939 * @scope: a scope to use when scanning the modules
24941 * Scans all the modules in the specified directory, ensuring that
24942 * any extension point implemented by a module is registered.
24944 * This may not actually load and initialize all the types in each
24945 * module, some modules may be lazily loaded and initialized when
24946 * an extension point it implementes is used with e.g.
24947 * g_io_extension_point_get_extensions() or
24948 * g_io_extension_point_get_extension_by_name().
24950 * If you need to guarantee that all types are loaded in all the modules,
24951 * use g_io_modules_load_all_in_directory().
24958 * g_io_scheduler_cancel_all_jobs:
24960 * Cancels all cancellable I/O jobs.
24962 * A job is cancellable if a #GCancellable was passed into
24963 * g_io_scheduler_push_job().
24965 * Deprecated: You should never call this function, since you don't
24966 * know how other libraries in your program might be making use of
24972 * g_io_scheduler_job_send_to_mainloop:
24973 * @job: a #GIOSchedulerJob
24974 * @func: a #GSourceFunc callback that will be called in the original thread
24975 * @user_data: data to pass to @func
24976 * @notify: (allow-none): a #GDestroyNotify for @user_data, or %NULL
24978 * Used from an I/O job to send a callback to be run in the thread
24979 * that the job was started from, waiting for the result (and thus
24980 * blocking the I/O job).
24982 * Returns: The return value of @func
24983 * Deprecated: Use g_main_context_invoke().
24988 * g_io_scheduler_job_send_to_mainloop_async:
24989 * @job: a #GIOSchedulerJob
24990 * @func: a #GSourceFunc callback that will be called in the original thread
24991 * @user_data: data to pass to @func
24992 * @notify: (allow-none): a #GDestroyNotify for @user_data, or %NULL
24994 * Used from an I/O job to send a callback to be run asynchronously in
24995 * the thread that the job was started from. The callback will be run
24996 * when the main loop is available, but at that time the I/O job might
24997 * have finished. The return value from the callback is ignored.
24999 * Note that if you are passing the @user_data from g_io_scheduler_push_job()
25000 * on to this function you have to ensure that it is not freed before
25001 * @func is called, either by passing %NULL as @notify to
25002 * g_io_scheduler_push_job() or by using refcounting for @user_data.
25004 * Deprecated: Use g_main_context_invoke().
25009 * g_io_scheduler_push_job:
25010 * @job_func: a #GIOSchedulerJobFunc.
25011 * @user_data: data to pass to @job_func
25012 * @notify: (allow-none): a #GDestroyNotify for @user_data, or %NULL
25013 * @io_priority: the [I/O priority][io-priority]
25015 * @cancellable: optional #GCancellable object, %NULL to ignore.
25017 * Schedules the I/O job to run in another thread.
25019 * @notify will be called on @user_data after @job_func has returned,
25020 * regardless whether the job was cancelled or has run to completion.
25022 * If @cancellable is not %NULL, it can be used to cancel the I/O job
25023 * by calling g_cancellable_cancel() or by calling
25024 * g_io_scheduler_cancel_all_jobs().
25026 * Deprecated: use #GThreadPool or g_task_run_in_thread()
25031 * g_io_stream_clear_pending:
25032 * @stream: a #GIOStream
25034 * Clears the pending flag on @stream.
25041 * g_io_stream_close:
25042 * @stream: a #GIOStream
25043 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
25044 * @error: location to store the error occurring, or %NULL to ignore
25046 * Closes the stream, releasing resources related to it. This will also
25047 * closes the individual input and output streams, if they are not already
25050 * Once the stream is closed, all other operations will return
25051 * %G_IO_ERROR_CLOSED. Closing a stream multiple times will not
25054 * Closing a stream will automatically flush any outstanding buffers
25057 * Streams will be automatically closed when the last reference
25058 * is dropped, but you might want to call this function to make sure
25059 * resources are released as early as possible.
25061 * Some streams might keep the backing store of the stream (e.g. a file
25062 * descriptor) open after the stream is closed. See the documentation for
25063 * the individual stream for details.
25065 * On failure the first error that happened will be reported, but the
25066 * close operation will finish as much as possible. A stream that failed
25067 * to close will still return %G_IO_ERROR_CLOSED for all operations.
25068 * Still, it is important to check and report the error to the user,
25069 * otherwise there might be a loss of data as all data might not be written.
25071 * If @cancellable is not NULL, then the operation can be cancelled by
25072 * triggering the cancellable object from another thread. If the operation
25073 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
25074 * Cancelling a close will still leave the stream closed, but some streams
25075 * can use a faster close that doesn't block to e.g. check errors.
25077 * The default implementation of this method just calls close on the
25078 * individual input/output streams.
25080 * Returns: %TRUE on success, %FALSE on failure
25086 * g_io_stream_close_async:
25087 * @stream: a #GIOStream
25088 * @io_priority: the io priority of the request
25089 * @cancellable: (allow-none): optional cancellable object
25090 * @callback: (scope async): callback to call when the request is satisfied
25091 * @user_data: (closure): the data to pass to callback function
25093 * Requests an asynchronous close of the stream, releasing resources
25094 * related to it. When the operation is finished @callback will be
25095 * called. You can then call g_io_stream_close_finish() to get
25096 * the result of the operation.
25098 * For behaviour details see g_io_stream_close().
25100 * The asynchronous methods have a default fallback that uses threads
25101 * to implement asynchronicity, so they are optional for inheriting
25102 * classes. However, if you override one you must override all.
25109 * g_io_stream_close_finish:
25110 * @stream: a #GIOStream
25111 * @result: a #GAsyncResult
25112 * @error: a #GError location to store the error occurring, or %NULL to
25117 * Returns: %TRUE if stream was successfully closed, %FALSE otherwise.
25123 * g_io_stream_get_input_stream:
25124 * @stream: a #GIOStream
25126 * Gets the input stream for this object. This is used
25129 * Returns: (transfer none): a #GInputStream, owned by the #GIOStream.
25136 * g_io_stream_get_output_stream:
25137 * @stream: a #GIOStream
25139 * Gets the output stream for this object. This is used for
25142 * Returns: (transfer none): a #GOutputStream, owned by the #GIOStream.
25149 * g_io_stream_has_pending:
25150 * @stream: a #GIOStream
25152 * Checks if a stream has pending actions.
25154 * Returns: %TRUE if @stream has pending actions.
25160 * g_io_stream_is_closed:
25161 * @stream: a #GIOStream
25163 * Checks if a stream is closed.
25165 * Returns: %TRUE if the stream is closed.
25171 * g_io_stream_set_pending:
25172 * @stream: a #GIOStream
25173 * @error: a #GError location to store the error occurring, or %NULL to
25176 * Sets @stream to have actions pending. If the pending flag is
25177 * already set or @stream is closed, it will return %FALSE and set
25180 * Returns: %TRUE if pending was previously unset and is now set.
25186 * g_io_stream_splice_async:
25187 * @stream1: a #GIOStream.
25188 * @stream2: a #GIOStream.
25189 * @flags: a set of #GIOStreamSpliceFlags.
25190 * @io_priority: the io priority of the request.
25191 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
25192 * @callback: (scope async): a #GAsyncReadyCallback.
25193 * @user_data: (closure): user data passed to @callback.
25195 * Asyncronously splice the output stream of @stream1 to the input stream of
25196 * @stream2, and splice the output stream of @stream2 to the input stream of
25199 * When the operation is finished @callback will be called.
25200 * You can then call g_io_stream_splice_finish() to get the
25201 * result of the operation.
25208 * g_io_stream_splice_finish:
25209 * @result: a #GAsyncResult.
25210 * @error: a #GError location to store the error occurring, or %NULL to
25213 * Finishes an asynchronous io stream splice operation.
25215 * Returns: %TRUE on success, %FALSE otherwise.
25221 * g_keyfile_settings_backend_new:
25222 * @filename: the filename of the keyfile
25223 * @root_path: the path under which all settings keys appear
25224 * @root_group: (allow-none): the group name corresponding to
25225 * @root_path, or %NULL
25227 * Creates a keyfile-backed #GSettingsBackend.
25229 * The filename of the keyfile to use is given by @filename.
25231 * All settings read to or written from the backend must fall under the
25232 * path given in @root_path (which must start and end with a slash and
25233 * not contain two consecutive slashes). @root_path may be "/".
25235 * If @root_group is non-%NULL then it specifies the name of the keyfile
25236 * group used for keys that are written directly below @root_path. For
25237 * example, if @root_path is "/apps/example/" and @root_group is
25238 * "toplevel", then settings the key "/apps/example/enabled" to a value
25239 * of %TRUE will cause the following to appear in the keyfile:
25246 * If @root_group is %NULL then it is not permitted to store keys
25247 * directly below the @root_path.
25249 * For keys not stored directly below @root_path (ie: in a sub-path),
25250 * the name of the subpath (with the final slash stripped) is used as
25251 * the name of the keyfile group. To continue the example, if
25252 * "/apps/example/profiles/default/font-size" were set to
25253 * 12 then the following would appear in the keyfile:
25256 * [profiles/default]
25260 * The backend will refuse writes (and return writability as being
25261 * %FALSE) for keys outside of @root_path and, in the event that
25262 * @root_group is %NULL, also for keys directly under @root_path.
25263 * Writes will also be refused if the backend detects that it has the
25264 * inability to rewrite the keyfile (ie: the containing directory is not
25267 * There is no checking done for your key namespace clashing with the
25268 * syntax of the key file format. For example, if you have '[' or ']'
25269 * characters in your path names or '=' in your key names you may be in
25272 * Returns: (transfer full): a keyfile-backed #GSettingsBackend
25277 * g_loadable_icon_load:
25278 * @icon: a #GLoadableIcon.
25279 * @size: an integer.
25280 * @type: (out) (optional): a location to store the type of the loaded
25281 * icon, %NULL to ignore.
25282 * @cancellable: (allow-none): optional #GCancellable object, %NULL to
25284 * @error: a #GError location to store the error occurring, or %NULL
25287 * Loads a loadable icon. For the asynchronous version of this function,
25288 * see g_loadable_icon_load_async().
25290 * Returns: (transfer full): a #GInputStream to read the icon from.
25295 * g_loadable_icon_load_async:
25296 * @icon: a #GLoadableIcon.
25297 * @size: an integer.
25298 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
25299 * @callback: (scope async): a #GAsyncReadyCallback to call when the
25300 * request is satisfied
25301 * @user_data: (closure): the data to pass to callback function
25303 * Loads an icon asynchronously. To finish this function, see
25304 * g_loadable_icon_load_finish(). For the synchronous, blocking
25305 * version of this function, see g_loadable_icon_load().
25310 * g_loadable_icon_load_finish:
25311 * @icon: a #GLoadableIcon.
25312 * @res: a #GAsyncResult.
25313 * @type: (out) (optional): a location to store the type of the loaded
25314 * icon, %NULL to ignore.
25315 * @error: a #GError location to store the error occurring, or %NULL to
25318 * Finishes an asynchronous icon load started in g_loadable_icon_load_async().
25320 * Returns: (transfer full): a #GInputStream to read the icon from.
25327 * Returns a new #GVfs handle for a local vfs.
25329 * Returns: a new #GVfs handle.
25334 * g_memory_input_stream_add_bytes:
25335 * @stream: a #GMemoryInputStream
25336 * @bytes: input data
25338 * Appends @bytes to data that can be read from the input stream.
25345 * g_memory_input_stream_add_data:
25346 * @stream: a #GMemoryInputStream
25347 * @data: (array length=len) (element-type guint8) (transfer full): input data
25348 * @len: length of the data, may be -1 if @data is a nul-terminated string
25349 * @destroy: (allow-none): function that is called to free @data, or %NULL
25351 * Appends @data to data that can be read from the input stream
25356 * g_memory_input_stream_new:
25358 * Creates a new empty #GMemoryInputStream.
25360 * Returns: a new #GInputStream
25365 * g_memory_input_stream_new_from_bytes:
25366 * @bytes: a #GBytes
25368 * Creates a new #GMemoryInputStream with data from the given @bytes.
25370 * Returns: new #GInputStream read from @bytes
25376 * g_memory_input_stream_new_from_data:
25377 * @data: (array length=len) (element-type guint8) (transfer full): input data
25378 * @len: length of the data, may be -1 if @data is a nul-terminated string
25379 * @destroy: (allow-none): function that is called to free @data, or %NULL
25381 * Creates a new #GMemoryInputStream with data in memory of a given size.
25383 * Returns: new #GInputStream read from @data of @len bytes.
25388 * g_memory_output_stream_get_data:
25389 * @ostream: a #GMemoryOutputStream
25391 * Gets any loaded data from the @ostream.
25393 * Note that the returned pointer may become invalid on the next
25394 * write or truncate operation on the stream.
25396 * Returns: (transfer none): pointer to the stream's data
25401 * g_memory_output_stream_get_data_size:
25402 * @ostream: a #GMemoryOutputStream
25404 * Returns the number of bytes from the start up to including the last
25405 * byte written in the stream that has not been truncated away.
25407 * Returns: the number of bytes written to the stream
25413 * g_memory_output_stream_get_size:
25414 * @ostream: a #GMemoryOutputStream
25416 * Gets the size of the currently allocated data area (available from
25417 * g_memory_output_stream_get_data()).
25419 * You probably don't want to use this function on resizable streams.
25420 * See g_memory_output_stream_get_data_size() instead. For resizable
25421 * streams the size returned by this function is an implementation
25422 * detail and may be change at any time in response to operations on the
25425 * If the stream is fixed-sized (ie: no realloc was passed to
25426 * g_memory_output_stream_new()) then this is the maximum size of the
25427 * stream and further writes will return %G_IO_ERROR_NO_SPACE.
25429 * In any case, if you want the number of bytes currently written to the
25430 * stream, use g_memory_output_stream_get_data_size().
25432 * Returns: the number of bytes allocated for the data buffer
25437 * g_memory_output_stream_new: (skip)
25438 * @data: (allow-none): pointer to a chunk of memory to use, or %NULL
25439 * @size: the size of @data
25440 * @realloc_function: (allow-none): a function with realloc() semantics (like g_realloc())
25441 * to be called when @data needs to be grown, or %NULL
25442 * @destroy_function: (allow-none): a function to be called on @data when the stream is
25443 * finalized, or %NULL
25445 * Creates a new #GMemoryOutputStream.
25447 * In most cases this is not the function you want. See
25448 * g_memory_output_stream_new_resizable() instead.
25450 * If @data is non-%NULL, the stream will use that for its internal storage.
25452 * If @realloc_fn is non-%NULL, it will be used for resizing the internal
25453 * storage when necessary and the stream will be considered resizable.
25454 * In that case, the stream will start out being (conceptually) empty.
25455 * @size is used only as a hint for how big @data is. Specifically,
25456 * seeking to the end of a newly-created stream will seek to zero, not
25457 * @size. Seeking past the end of the stream and then writing will
25458 * introduce a zero-filled gap.
25460 * If @realloc_fn is %NULL then the stream is fixed-sized. Seeking to
25461 * the end will seek to @size exactly. Writing past the end will give
25462 * an 'out of space' error. Attempting to seek past the end will fail.
25463 * Unlike the resizable case, seeking to an offset within the stream and
25464 * writing will preserve the bytes passed in as @data before that point
25465 * and will return them as part of g_memory_output_stream_steal_data().
25466 * If you intend to seek you should probably therefore ensure that @data
25467 * is properly initialised.
25469 * It is probably only meaningful to provide @data and @size in the case
25470 * that you want a fixed-sized stream. Put another way: if @realloc_fn
25471 * is non-%NULL then it makes most sense to give @data as %NULL and
25472 * @size as 0 (allowing #GMemoryOutputStream to do the initial
25473 * allocation for itself).
25475 * |[<!-- language="C" -->
25476 * // a stream that can grow
25477 * stream = g_memory_output_stream_new (NULL, 0, realloc, free);
25479 * // another stream that can grow
25480 * stream2 = g_memory_output_stream_new (NULL, 0, g_realloc, g_free);
25482 * // a fixed-size stream
25483 * data = malloc (200);
25484 * stream3 = g_memory_output_stream_new (data, 200, NULL, free);
25487 * Returns: A newly created #GMemoryOutputStream object.
25492 * g_memory_output_stream_new_resizable:
25494 * Creates a new #GMemoryOutputStream, using g_realloc() and g_free()
25495 * for memory allocation.
25502 * g_memory_output_stream_steal_as_bytes:
25503 * @ostream: a #GMemoryOutputStream
25505 * Returns data from the @ostream as a #GBytes. @ostream must be
25506 * closed before calling this function.
25508 * Returns: (transfer full): the stream's data
25514 * g_memory_output_stream_steal_data:
25515 * @ostream: a #GMemoryOutputStream
25517 * Gets any loaded data from the @ostream. Ownership of the data
25518 * is transferred to the caller; when no longer needed it must be
25519 * freed using the free function set in @ostream's
25520 * #GMemoryOutputStream:destroy-function property.
25522 * @ostream must be closed before calling this function.
25524 * Returns: (transfer full): the stream's data
25530 * g_memory_settings_backend_new:
25532 * Creates a memory-backed #GSettingsBackend.
25534 * This backend allows changes to settings, but does not write them
25535 * to any backing storage, so the next time you run your application,
25536 * the memory backend will start out with the default values again.
25538 * Returns: (transfer full): a newly created #GSettingsBackend
25546 * @label: (allow-none): the section label, or %NULL
25547 * @detailed_action: (allow-none): the detailed action string, or %NULL
25549 * Convenience function for appending a normal menu item to the end of
25550 * @menu. Combine g_menu_item_new() and g_menu_insert_item() for a more
25551 * flexible alternative.
25558 * g_menu_append_item:
25560 * @item: a #GMenuItem to append
25562 * Appends @item to the end of @menu.
25564 * See g_menu_insert_item() for more information.
25571 * g_menu_append_section:
25573 * @label: (allow-none): the section label, or %NULL
25574 * @section: a #GMenuModel with the items of the section
25576 * Convenience function for appending a section menu item to the end of
25577 * @menu. Combine g_menu_item_new_section() and g_menu_insert_item() for a
25578 * more flexible alternative.
25585 * g_menu_append_submenu:
25587 * @label: (allow-none): the section label, or %NULL
25588 * @submenu: a #GMenuModel with the items of the submenu
25590 * Convenience function for appending a submenu menu item to the end of
25591 * @menu. Combine g_menu_item_new_submenu() and g_menu_insert_item() for a
25592 * more flexible alternative.
25599 * g_menu_attribute_iter_get_name:
25600 * @iter: a #GMenuAttributeIter
25602 * Gets the name of the attribute at the current iterator position, as
25605 * The iterator is not advanced.
25607 * Returns: the name of the attribute
25613 * g_menu_attribute_iter_get_next:
25614 * @iter: a #GMenuAttributeIter
25615 * @out_name: (out) (allow-none) (transfer none): the type of the attribute
25616 * @value: (out) (allow-none) (transfer full): the attribute value
25618 * This function combines g_menu_attribute_iter_next() with
25619 * g_menu_attribute_iter_get_name() and g_menu_attribute_iter_get_value().
25621 * First the iterator is advanced to the next (possibly first) attribute.
25622 * If that fails, then %FALSE is returned and there are no other
25625 * If successful, @name and @value are set to the name and value of the
25626 * attribute that has just been advanced to. At this point,
25627 * g_menu_attribute_iter_get_name() and g_menu_attribute_iter_get_value() will
25628 * return the same values again.
25630 * The value returned in @name remains valid for as long as the iterator
25631 * remains at the current position. The value returned in @value must
25632 * be unreffed using g_variant_unref() when it is no longer in use.
25634 * Returns: %TRUE on success, or %FALSE if there is no additional
25641 * g_menu_attribute_iter_get_value:
25642 * @iter: a #GMenuAttributeIter
25644 * Gets the value of the attribute at the current iterator position.
25646 * The iterator is not advanced.
25648 * Returns: (transfer full): the value of the current attribute
25654 * g_menu_attribute_iter_next:
25655 * @iter: a #GMenuAttributeIter
25657 * Attempts to advance the iterator to the next (possibly first)
25660 * %TRUE is returned on success, or %FALSE if there are no more
25663 * You must call this function when you first acquire the iterator
25664 * to advance it to the first attribute (and determine if the first
25665 * attribute exists at all).
25667 * Returns: %TRUE on success, or %FALSE when there are no more attributes
25676 * Marks @menu as frozen.
25678 * After the menu is frozen, it is an error to attempt to make any
25679 * changes to it. In effect this means that the #GMenu API must no
25682 * This function causes g_menu_model_is_mutable() to begin returning
25683 * %FALSE, which has some positive performance implications.
25692 * @position: the position at which to insert the item
25693 * @label: (allow-none): the section label, or %NULL
25694 * @detailed_action: (allow-none): the detailed action string, or %NULL
25696 * Convenience function for inserting a normal menu item into @menu.
25697 * Combine g_menu_item_new() and g_menu_insert_item() for a more flexible
25705 * g_menu_insert_item:
25707 * @position: the position at which to insert the item
25708 * @item: the #GMenuItem to insert
25710 * Inserts @item into @menu.
25712 * The "insertion" is actually done by copying all of the attribute and
25713 * link values of @item and using them to form a new item within @menu.
25714 * As such, @item itself is not really inserted, but rather, a menu item
25715 * that is exactly the same as the one presently described by @item.
25717 * This means that @item is essentially useless after the insertion
25718 * occurs. Any changes you make to it are ignored unless it is inserted
25719 * again (at which point its updated values will be copied).
25721 * You should probably just free @item once you're done.
25723 * There are many convenience functions to take care of common cases.
25724 * See g_menu_insert(), g_menu_insert_section() and
25725 * g_menu_insert_submenu() as well as "prepend" and "append" variants of
25726 * each of these functions.
25733 * g_menu_insert_section:
25735 * @position: the position at which to insert the item
25736 * @label: (allow-none): the section label, or %NULL
25737 * @section: a #GMenuModel with the items of the section
25739 * Convenience function for inserting a section menu item into @menu.
25740 * Combine g_menu_item_new_section() and g_menu_insert_item() for a more
25741 * flexible alternative.
25748 * g_menu_insert_submenu:
25750 * @position: the position at which to insert the item
25751 * @label: (allow-none): the section label, or %NULL
25752 * @submenu: a #GMenuModel with the items of the submenu
25754 * Convenience function for inserting a submenu menu item into @menu.
25755 * Combine g_menu_item_new_submenu() and g_menu_insert_item() for a more
25756 * flexible alternative.
25763 * g_menu_item_get_attribute:
25764 * @menu_item: a #GMenuItem
25765 * @attribute: the attribute name to query
25766 * @format_string: a #GVariant format string
25767 * @...: positional parameters, as per @format_string
25769 * Queries the named @attribute on @menu_item.
25771 * If the attribute exists and matches the #GVariantType corresponding
25772 * to @format_string then @format_string is used to deconstruct the
25773 * value into the positional parameters and %TRUE is returned.
25775 * If the attribute does not exist, or it does exist but has the wrong
25776 * type, then the positional parameters are ignored and %FALSE is
25779 * Returns: %TRUE if the named attribute was found with the expected
25786 * g_menu_item_get_attribute_value:
25787 * @menu_item: a #GMenuItem
25788 * @attribute: the attribute name to query
25789 * @expected_type: (allow-none): the expected type of the attribute
25791 * Queries the named @attribute on @menu_item.
25793 * If @expected_type is specified and the attribute does not have this
25794 * type, %NULL is returned. %NULL is also returned if the attribute
25795 * simply does not exist.
25797 * Returns: (transfer full): the attribute value, or %NULL
25803 * g_menu_item_get_link:
25804 * @menu_item: a #GMenuItem
25805 * @link: the link name to query
25807 * Queries the named @link on @menu_item.
25809 * Returns: (transfer full): the link, or %NULL
25816 * @label: (allow-none): the section label, or %NULL
25817 * @detailed_action: (allow-none): the detailed action string, or %NULL
25819 * Creates a new #GMenuItem.
25821 * If @label is non-%NULL it is used to set the "label" attribute of the
25824 * If @detailed_action is non-%NULL it is used to set the "action" and
25825 * possibly the "target" attribute of the new item. See
25826 * g_menu_item_set_detailed_action() for more information.
25828 * Returns: a new #GMenuItem
25834 * g_menu_item_new_from_model:
25835 * @model: a #GMenuModel
25836 * @item_index: the index of an item in @model
25838 * Creates a #GMenuItem as an exact copy of an existing menu item in a
25841 * @item_index must be valid (ie: be sure to call
25842 * g_menu_model_get_n_items() first).
25844 * Returns: a new #GMenuItem.
25850 * g_menu_item_new_section:
25851 * @label: (allow-none): the section label, or %NULL
25852 * @section: a #GMenuModel with the items of the section
25854 * Creates a new #GMenuItem representing a section.
25856 * This is a convenience API around g_menu_item_new() and
25857 * g_menu_item_set_section().
25859 * The effect of having one menu appear as a section of another is
25860 * exactly as it sounds: the items from @section become a direct part of
25861 * the menu that @menu_item is added to.
25863 * Visual separation is typically displayed between two non-empty
25864 * sections. If @label is non-%NULL then it will be encorporated into
25865 * this visual indication. This allows for labeled subsections of a
25868 * As a simple example, consider a typical "Edit" menu from a simple
25869 * program. It probably contains an "Undo" and "Redo" item, followed by
25870 * a separator, followed by "Cut", "Copy" and "Paste".
25872 * This would be accomplished by creating three #GMenu instances. The
25873 * first would be populated with the "Undo" and "Redo" items, and the
25874 * second with the "Cut", "Copy" and "Paste" items. The first and
25875 * second menus would then be added as submenus of the third. In XML
25876 * format, this would look something like the following:
25878 * <menu id='edit-menu'>
25880 * <item label='Undo'/>
25881 * <item label='Redo'/>
25884 * <item label='Cut'/>
25885 * <item label='Copy'/>
25886 * <item label='Paste'/>
25891 * The following example is exactly equivalent. It is more illustrative
25892 * of the exact relationship between the menus and items (keeping in
25893 * mind that the 'link' element defines a new menu that is linked to the
25894 * containing one). The style of the second example is more verbose and
25895 * difficult to read (and therefore not recommended except for the
25896 * purpose of understanding what is really going on).
25898 * <menu id='edit-menu'>
25900 * <link name='section'>
25901 * <item label='Undo'/>
25902 * <item label='Redo'/>
25906 * <link name='section'>
25907 * <item label='Cut'/>
25908 * <item label='Copy'/>
25909 * <item label='Paste'/>
25915 * Returns: a new #GMenuItem
25921 * g_menu_item_new_submenu:
25922 * @label: (allow-none): the section label, or %NULL
25923 * @submenu: a #GMenuModel with the items of the submenu
25925 * Creates a new #GMenuItem representing a submenu.
25927 * This is a convenience API around g_menu_item_new() and
25928 * g_menu_item_set_submenu().
25930 * Returns: a new #GMenuItem
25936 * g_menu_item_set_action_and_target:
25937 * @menu_item: a #GMenuItem
25938 * @action: (allow-none): the name of the action for this item
25939 * @format_string: (allow-none): a GVariant format string
25940 * @...: positional parameters, as per @format_string
25942 * Sets or unsets the "action" and "target" attributes of @menu_item.
25944 * If @action is %NULL then both the "action" and "target" attributes
25945 * are unset (and @format_string is ignored along with the positional
25948 * If @action is non-%NULL then the "action" attribute is set.
25949 * @format_string is then inspected. If it is non-%NULL then the proper
25950 * position parameters are collected to create a #GVariant instance to
25951 * use as the target value. If it is %NULL then the positional
25952 * parameters are ignored and the "target" attribute is unset.
25954 * See also g_menu_item_set_action_and_target_value() for an equivalent
25955 * call that directly accepts a #GVariant. See
25956 * g_menu_item_set_detailed_action() for a more convenient version that
25957 * works with string-typed targets.
25959 * See also g_menu_item_set_action_and_target_value() for a
25960 * description of the semantics of the action and target attributes.
25967 * g_menu_item_set_action_and_target_value:
25968 * @menu_item: a #GMenuItem
25969 * @action: (allow-none): the name of the action for this item
25970 * @target_value: (allow-none): a #GVariant to use as the action target
25972 * Sets or unsets the "action" and "target" attributes of @menu_item.
25974 * If @action is %NULL then both the "action" and "target" attributes
25975 * are unset (and @target_value is ignored).
25977 * If @action is non-%NULL then the "action" attribute is set. The
25978 * "target" attribute is then set to the value of @target_value if it is
25979 * non-%NULL or unset otherwise.
25981 * Normal menu items (ie: not submenu, section or other custom item
25982 * types) are expected to have the "action" attribute set to identify
25983 * the action that they are associated with. The state type of the
25984 * action help to determine the disposition of the menu item. See
25985 * #GAction and #GActionGroup for an overview of actions.
25987 * In general, clicking on the menu item will result in activation of
25988 * the named action with the "target" attribute given as the parameter
25989 * to the action invocation. If the "target" attribute is not set then
25990 * the action is invoked with no parameter.
25992 * If the action has no state then the menu item is usually drawn as a
25993 * plain menu item (ie: with no additional decoration).
25995 * If the action has a boolean state then the menu item is usually drawn
25996 * as a toggle menu item (ie: with a checkmark or equivalent
25997 * indication). The item should be marked as 'toggled' or 'checked'
25998 * when the boolean state is %TRUE.
26000 * If the action has a string state then the menu item is usually drawn
26001 * as a radio menu item (ie: with a radio bullet or equivalent
26002 * indication). The item should be marked as 'selected' when the string
26003 * state is equal to the value of the @target property.
26005 * See g_menu_item_set_action_and_target() or
26006 * g_menu_item_set_detailed_action() for two equivalent calls that are
26007 * probably more convenient for most uses.
26014 * g_menu_item_set_attribute:
26015 * @menu_item: a #GMenuItem
26016 * @attribute: the attribute to set
26017 * @format_string: (allow-none): a #GVariant format string, or %NULL
26018 * @...: positional parameters, as per @format_string
26020 * Sets or unsets an attribute on @menu_item.
26022 * The attribute to set or unset is specified by @attribute. This
26023 * can be one of the standard attribute names %G_MENU_ATTRIBUTE_LABEL,
26024 * %G_MENU_ATTRIBUTE_ACTION, %G_MENU_ATTRIBUTE_TARGET, or a custom
26026 * Attribute names are restricted to lowercase characters, numbers
26027 * and '-'. Furthermore, the names must begin with a lowercase character,
26028 * must not end with a '-', and must not contain consecutive dashes.
26030 * If @format_string is non-%NULL then the proper position parameters
26031 * are collected to create a #GVariant instance to use as the attribute
26032 * value. If it is %NULL then the positional parameterrs are ignored
26033 * and the named attribute is unset.
26035 * See also g_menu_item_set_attribute_value() for an equivalent call
26036 * that directly accepts a #GVariant.
26043 * g_menu_item_set_attribute_value:
26044 * @menu_item: a #GMenuItem
26045 * @attribute: the attribute to set
26046 * @value: (allow-none): a #GVariant to use as the value, or %NULL
26048 * Sets or unsets an attribute on @menu_item.
26050 * The attribute to set or unset is specified by @attribute. This
26051 * can be one of the standard attribute names %G_MENU_ATTRIBUTE_LABEL,
26052 * %G_MENU_ATTRIBUTE_ACTION, %G_MENU_ATTRIBUTE_TARGET, or a custom
26054 * Attribute names are restricted to lowercase characters, numbers
26055 * and '-'. Furthermore, the names must begin with a lowercase character,
26056 * must not end with a '-', and must not contain consecutive dashes.
26058 * must consist only of lowercase
26059 * ASCII characters, digits and '-'.
26061 * If @value is non-%NULL then it is used as the new value for the
26062 * attribute. If @value is %NULL then the attribute is unset. If
26063 * the @value #GVariant is floating, it is consumed.
26065 * See also g_menu_item_set_attribute() for a more convenient way to do
26073 * g_menu_item_set_detailed_action:
26074 * @menu_item: a #GMenuItem
26075 * @detailed_action: the "detailed" action string
26077 * Sets the "action" and possibly the "target" attribute of @menu_item.
26079 * The format of @detailed_action is the same format parsed by
26080 * g_action_parse_detailed_name().
26082 * See g_menu_item_set_action_and_target() or
26083 * g_menu_item_set_action_and_target_value() for more flexible (but
26084 * slightly less convenient) alternatives.
26086 * See also g_menu_item_set_action_and_target_value() for a description of
26087 * the semantics of the action and target attributes.
26094 * g_menu_item_set_icon:
26095 * @menu_item: a #GMenuItem
26096 * @icon: a #GIcon, or %NULL
26098 * Sets (or unsets) the icon on @menu_item.
26100 * This call is the same as calling g_icon_serialize() and using the
26101 * result as the value to g_menu_item_set_attribute_value() for
26102 * %G_MENU_ATTRIBUTE_ICON.
26104 * This API is only intended for use with "noun" menu items; things like
26105 * bookmarks or applications in an "Open With" menu. Don't use it on
26106 * menu items corresponding to verbs (eg: stock icons for 'Save' or
26109 * If @icon is %NULL then the icon is unset.
26116 * g_menu_item_set_label:
26117 * @menu_item: a #GMenuItem
26118 * @label: (allow-none): the label to set, or %NULL to unset
26120 * Sets or unsets the "label" attribute of @menu_item.
26122 * If @label is non-%NULL it is used as the label for the menu item. If
26123 * it is %NULL then the label attribute is unset.
26130 * g_menu_item_set_link:
26131 * @menu_item: a #GMenuItem
26132 * @link: type of link to establish or unset
26133 * @model: (allow-none): the #GMenuModel to link to (or %NULL to unset)
26135 * Creates a link from @menu_item to @model if non-%NULL, or unsets it.
26137 * Links are used to establish a relationship between a particular menu
26138 * item and another menu. For example, %G_MENU_LINK_SUBMENU is used to
26139 * associate a submenu with a particular menu item, and %G_MENU_LINK_SECTION
26140 * is used to create a section. Other types of link can be used, but there
26141 * is no guarantee that clients will be able to make sense of them.
26142 * Link types are restricted to lowercase characters, numbers
26143 * and '-'. Furthermore, the names must begin with a lowercase character,
26144 * must not end with a '-', and must not contain consecutive dashes.
26151 * g_menu_item_set_section:
26152 * @menu_item: a #GMenuItem
26153 * @section: (allow-none): a #GMenuModel, or %NULL
26155 * Sets or unsets the "section" link of @menu_item to @section.
26157 * The effect of having one menu appear as a section of another is
26158 * exactly as it sounds: the items from @section become a direct part of
26159 * the menu that @menu_item is added to. See g_menu_item_new_section()
26160 * for more information about what it means for a menu item to be a
26168 * g_menu_item_set_submenu:
26169 * @menu_item: a #GMenuItem
26170 * @submenu: (allow-none): a #GMenuModel, or %NULL
26172 * Sets or unsets the "submenu" link of @menu_item to @submenu.
26174 * If @submenu is non-%NULL, it is linked to. If it is %NULL then the
26177 * The effect of having one menu appear as a submenu of another is
26178 * exactly as it sounds.
26185 * g_menu_link_iter_get_name:
26186 * @iter: a #GMenuLinkIter
26188 * Gets the name of the link at the current iterator position.
26190 * The iterator is not advanced.
26192 * Returns: the type of the link
26198 * g_menu_link_iter_get_next:
26199 * @iter: a #GMenuLinkIter
26200 * @out_link: (out) (allow-none) (transfer none): the name of the link
26201 * @value: (out) (allow-none) (transfer full): the linked #GMenuModel
26203 * This function combines g_menu_link_iter_next() with
26204 * g_menu_link_iter_get_name() and g_menu_link_iter_get_value().
26206 * First the iterator is advanced to the next (possibly first) link.
26207 * If that fails, then %FALSE is returned and there are no other effects.
26209 * If successful, @out_link and @value are set to the name and #GMenuModel
26210 * of the link that has just been advanced to. At this point,
26211 * g_menu_link_iter_get_name() and g_menu_link_iter_get_value() will return the
26212 * same values again.
26214 * The value returned in @out_link remains valid for as long as the iterator
26215 * remains at the current position. The value returned in @value must
26216 * be unreffed using g_object_unref() when it is no longer in use.
26218 * Returns: %TRUE on success, or %FALSE if there is no additional link
26224 * g_menu_link_iter_get_value:
26225 * @iter: a #GMenuLinkIter
26227 * Gets the linked #GMenuModel at the current iterator position.
26229 * The iterator is not advanced.
26231 * Returns: (transfer full): the #GMenuModel that is linked to
26237 * g_menu_link_iter_next:
26238 * @iter: a #GMenuLinkIter
26240 * Attempts to advance the iterator to the next (possibly first)
26243 * %TRUE is returned on success, or %FALSE if there are no more links.
26245 * You must call this function when you first acquire the iterator to
26246 * advance it to the first link (and determine if the first link exists
26249 * Returns: %TRUE on success, or %FALSE when there are no more links
26255 * g_menu_model_get_item_attribute:
26256 * @model: a #GMenuModel
26257 * @item_index: the index of the item
26258 * @attribute: the attribute to query
26259 * @format_string: a #GVariant format string
26260 * @...: positional parameters, as per @format_string
26262 * Queries item at position @item_index in @model for the attribute
26263 * specified by @attribute.
26265 * If the attribute exists and matches the #GVariantType corresponding
26266 * to @format_string then @format_string is used to deconstruct the
26267 * value into the positional parameters and %TRUE is returned.
26269 * If the attribute does not exist, or it does exist but has the wrong
26270 * type, then the positional parameters are ignored and %FALSE is
26273 * This function is a mix of g_menu_model_get_item_attribute_value() and
26274 * g_variant_get(), followed by a g_variant_unref(). As such,
26275 * @format_string must make a complete copy of the data (since the
26276 * #GVariant may go away after the call to g_variant_unref()). In
26277 * particular, no '&' characters are allowed in @format_string.
26279 * Returns: %TRUE if the named attribute was found with the expected
26286 * g_menu_model_get_item_attribute_value:
26287 * @model: a #GMenuModel
26288 * @item_index: the index of the item
26289 * @attribute: the attribute to query
26290 * @expected_type: (allow-none): the expected type of the attribute, or
26293 * Queries the item at position @item_index in @model for the attribute
26294 * specified by @attribute.
26296 * If @expected_type is non-%NULL then it specifies the expected type of
26297 * the attribute. If it is %NULL then any type will be accepted.
26299 * If the attribute exists and matches @expected_type (or if the
26300 * expected type is unspecified) then the value is returned.
26302 * If the attribute does not exist, or does not match the expected type
26303 * then %NULL is returned.
26305 * Returns: (transfer full): the value of the attribute
26311 * g_menu_model_get_item_link:
26312 * @model: a #GMenuModel
26313 * @item_index: the index of the item
26314 * @link: the link to query
26316 * Queries the item at position @item_index in @model for the link
26317 * specified by @link.
26319 * If the link exists, the linked #GMenuModel is returned. If the link
26320 * does not exist, %NULL is returned.
26322 * Returns: (transfer full): the linked #GMenuModel, or %NULL
26328 * g_menu_model_get_n_items:
26329 * @model: a #GMenuModel
26331 * Query the number of items in @model.
26333 * Returns: the number of items
26339 * g_menu_model_is_mutable:
26340 * @model: a #GMenuModel
26342 * Queries if @model is mutable.
26344 * An immutable #GMenuModel will never emit the #GMenuModel::items-changed
26345 * signal. Consumers of the model may make optimisations accordingly.
26347 * Returns: %TRUE if the model is mutable (ie: "items-changed" may be
26354 * g_menu_model_items_changed:
26355 * @model: a #GMenuModel
26356 * @position: the position of the change
26357 * @removed: the number of items removed
26358 * @added: the number of items added
26360 * Requests emission of the #GMenuModel::items-changed signal on @model.
26362 * This function should never be called except by #GMenuModel
26363 * subclasses. Any other calls to this function will very likely lead
26364 * to a violation of the interface of the model.
26366 * The implementation should update its internal representation of the
26367 * menu before emitting the signal. The implementation should further
26368 * expect to receive queries about the new state of the menu (and
26369 * particularly added menu items) while signal handlers are running.
26371 * The implementation must dispatch this call directly from a mainloop
26372 * entry and not in response to calls -- particularly those from the
26373 * #GMenuModel API. Said another way: the menu must not change while
26374 * user code is running without returning to the mainloop.
26381 * g_menu_model_iterate_item_attributes:
26382 * @model: a #GMenuModel
26383 * @item_index: the index of the item
26385 * Creates a #GMenuAttributeIter to iterate over the attributes of
26386 * the item at position @item_index in @model.
26388 * You must free the iterator with g_object_unref() when you are done.
26390 * Returns: (transfer full): a new #GMenuAttributeIter
26396 * g_menu_model_iterate_item_links:
26397 * @model: a #GMenuModel
26398 * @item_index: the index of the item
26400 * Creates a #GMenuLinkIter to iterate over the links of the item at
26401 * position @item_index in @model.
26403 * You must free the iterator with g_object_unref() when you are done.
26405 * Returns: (transfer full): a new #GMenuLinkIter
26413 * Creates a new #GMenu.
26415 * The new menu has no items.
26417 * Returns: a new #GMenu
26425 * @label: (allow-none): the section label, or %NULL
26426 * @detailed_action: (allow-none): the detailed action string, or %NULL
26428 * Convenience function for prepending a normal menu item to the start
26429 * of @menu. Combine g_menu_item_new() and g_menu_insert_item() for a more
26430 * flexible alternative.
26437 * g_menu_prepend_item:
26439 * @item: a #GMenuItem to prepend
26441 * Prepends @item to the start of @menu.
26443 * See g_menu_insert_item() for more information.
26450 * g_menu_prepend_section:
26452 * @label: (allow-none): the section label, or %NULL
26453 * @section: a #GMenuModel with the items of the section
26455 * Convenience function for prepending a section menu item to the start
26456 * of @menu. Combine g_menu_item_new_section() and g_menu_insert_item() for
26457 * a more flexible alternative.
26464 * g_menu_prepend_submenu:
26466 * @label: (allow-none): the section label, or %NULL
26467 * @submenu: a #GMenuModel with the items of the submenu
26469 * Convenience function for prepending a submenu menu item to the start
26470 * of @menu. Combine g_menu_item_new_submenu() and g_menu_insert_item() for
26471 * a more flexible alternative.
26480 * @position: the position of the item to remove
26482 * Removes an item from the menu.
26484 * @position gives the index of the item to remove.
26486 * It is an error if position is not in range the range from 0 to one
26487 * less than the number of items in the menu.
26489 * It is not possible to remove items by identity since items are added
26490 * to the menu simply by copying their links and attributes (ie:
26491 * identity of the item itself is not preserved).
26498 * g_menu_remove_all:
26501 * Removes all items in the menu.
26508 * g_mount_can_eject:
26509 * @mount: a #GMount.
26511 * Checks if @mount can be eject.
26513 * Returns: %TRUE if the @mount can be ejected.
26518 * g_mount_can_unmount:
26519 * @mount: a #GMount.
26521 * Checks if @mount can be mounted.
26523 * Returns: %TRUE if the @mount can be unmounted.
26529 * @mount: a #GMount.
26530 * @flags: flags affecting the unmount if required for eject
26531 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
26532 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
26533 * @user_data: user data passed to @callback.
26535 * Ejects a mount. This is an asynchronous operation, and is
26536 * finished by calling g_mount_eject_finish() with the @mount
26537 * and #GAsyncResult data returned in the @callback.
26539 * Deprecated: 2.22: Use g_mount_eject_with_operation() instead.
26544 * g_mount_eject_finish:
26545 * @mount: a #GMount.
26546 * @result: a #GAsyncResult.
26547 * @error: a #GError location to store the error occurring, or %NULL to
26550 * Finishes ejecting a mount. If any errors occurred during the operation,
26551 * @error will be set to contain the errors and %FALSE will be returned.
26553 * Returns: %TRUE if the mount was successfully ejected. %FALSE otherwise.
26554 * Deprecated: 2.22: Use g_mount_eject_with_operation_finish() instead.
26559 * g_mount_eject_with_operation:
26560 * @mount: a #GMount.
26561 * @flags: flags affecting the unmount if required for eject
26562 * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid
26563 * user interaction.
26564 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
26565 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
26566 * @user_data: user data passed to @callback.
26568 * Ejects a mount. This is an asynchronous operation, and is
26569 * finished by calling g_mount_eject_with_operation_finish() with the @mount
26570 * and #GAsyncResult data returned in the @callback.
26577 * g_mount_eject_with_operation_finish:
26578 * @mount: a #GMount.
26579 * @result: a #GAsyncResult.
26580 * @error: a #GError location to store the error occurring, or %NULL to
26583 * Finishes ejecting a mount. If any errors occurred during the operation,
26584 * @error will be set to contain the errors and %FALSE will be returned.
26586 * Returns: %TRUE if the mount was successfully ejected. %FALSE otherwise.
26592 * g_mount_get_default_location:
26593 * @mount: a #GMount.
26595 * Gets the default location of @mount. The default location of the given
26596 * @mount is a path that reflects the main entry point for the user (e.g.
26597 * the home directory, or the root of the volume).
26599 * Returns: (transfer full): a #GFile.
26600 * The returned object should be unreffed with
26601 * g_object_unref() when no longer needed.
26606 * g_mount_get_drive:
26607 * @mount: a #GMount.
26609 * Gets the drive for the @mount.
26611 * This is a convenience method for getting the #GVolume and then
26612 * using that object to get the #GDrive.
26614 * Returns: (transfer full): a #GDrive or %NULL if @mount is not associated with a volume or a drive.
26615 * The returned object should be unreffed with
26616 * g_object_unref() when no longer needed.
26621 * g_mount_get_icon:
26622 * @mount: a #GMount.
26624 * Gets the icon for @mount.
26626 * Returns: (transfer full): a #GIcon.
26627 * The returned object should be unreffed with
26628 * g_object_unref() when no longer needed.
26633 * g_mount_get_name:
26634 * @mount: a #GMount.
26636 * Gets the name of @mount.
26638 * Returns: the name for the given @mount.
26639 * The returned string should be freed with g_free()
26640 * when no longer needed.
26645 * g_mount_get_root:
26646 * @mount: a #GMount.
26648 * Gets the root directory on @mount.
26650 * Returns: (transfer full): a #GFile.
26651 * The returned object should be unreffed with
26652 * g_object_unref() when no longer needed.
26657 * g_mount_get_sort_key:
26658 * @mount: A #GMount.
26660 * Gets the sort key for @mount, if any.
26662 * Returns: Sorting key for @mount or %NULL if no such key is available.
26668 * g_mount_get_symbolic_icon:
26669 * @mount: a #GMount.
26671 * Gets the symbolic icon for @mount.
26673 * Returns: (transfer full): a #GIcon.
26674 * The returned object should be unreffed with
26675 * g_object_unref() when no longer needed.
26681 * g_mount_get_uuid:
26682 * @mount: a #GMount.
26684 * Gets the UUID for the @mount. The reference is typically based on
26685 * the file system UUID for the mount in question and should be
26686 * considered an opaque string. Returns %NULL if there is no UUID
26689 * Returns: the UUID for @mount or %NULL if no UUID can be computed.
26690 * The returned string should be freed with g_free()
26691 * when no longer needed.
26696 * g_mount_get_volume:
26697 * @mount: a #GMount.
26699 * Gets the volume for the @mount.
26701 * Returns: (transfer full): a #GVolume or %NULL if @mount is not associated with a volume.
26702 * The returned object should be unreffed with
26703 * g_object_unref() when no longer needed.
26708 * g_mount_guess_content_type:
26709 * @mount: a #GMount
26710 * @force_rescan: Whether to force a rescan of the content.
26711 * Otherwise a cached result will be used if available
26712 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
26713 * @callback: a #GAsyncReadyCallback
26714 * @user_data: user data passed to @callback
26716 * Tries to guess the type of content stored on @mount. Returns one or
26717 * more textual identifiers of well-known content types (typically
26718 * prefixed with "x-content/"), e.g. x-content/image-dcf for camera
26719 * memory cards. See the
26720 * [shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec)
26721 * specification for more on x-content types.
26723 * This is an asynchronous operation (see
26724 * g_mount_guess_content_type_sync() for the synchronous version), and
26725 * is finished by calling g_mount_guess_content_type_finish() with the
26726 * @mount and #GAsyncResult data returned in the @callback.
26733 * g_mount_guess_content_type_finish:
26734 * @mount: a #GMount
26735 * @result: a #GAsyncResult
26736 * @error: a #GError location to store the error occurring, or %NULL to
26739 * Finishes guessing content types of @mount. If any errors occurred
26740 * during the operation, @error will be set to contain the errors and
26741 * %FALSE will be returned. In particular, you may get an
26742 * %G_IO_ERROR_NOT_SUPPORTED if the mount does not support content
26745 * Returns: (transfer full) (element-type utf8): a %NULL-terminated array of content types or %NULL on error.
26746 * Caller should free this array with g_strfreev() when done with it.
26752 * g_mount_guess_content_type_sync:
26753 * @mount: a #GMount
26754 * @force_rescan: Whether to force a rescan of the content.
26755 * Otherwise a cached result will be used if available
26756 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
26757 * @error: a #GError location to store the error occurring, or %NULL to
26760 * Tries to guess the type of content stored on @mount. Returns one or
26761 * more textual identifiers of well-known content types (typically
26762 * prefixed with "x-content/"), e.g. x-content/image-dcf for camera
26763 * memory cards. See the
26764 * [shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec)
26765 * specification for more on x-content types.
26767 * This is an synchronous operation and as such may block doing IO;
26768 * see g_mount_guess_content_type() for the asynchronous version.
26770 * Returns: (transfer full) (element-type utf8): a %NULL-terminated array of content types or %NULL on error.
26771 * Caller should free this array with g_strfreev() when done with it.
26777 * g_mount_is_shadowed:
26778 * @mount: A #GMount.
26780 * Determines if @mount is shadowed. Applications or libraries should
26781 * avoid displaying @mount in the user interface if it is shadowed.
26783 * A mount is said to be shadowed if there exists one or more user
26784 * visible objects (currently #GMount objects) with a root that is
26785 * inside the root of @mount.
26787 * One application of shadow mounts is when exposing a single file
26788 * system that is used to address several logical volumes. In this
26789 * situation, a #GVolumeMonitor implementation would create two
26790 * #GVolume objects (for example, one for the camera functionality of
26791 * the device and one for a SD card reader on the device) with
26792 * activation URIs `gphoto2://[usb:001,002]/store1/`
26793 * and `gphoto2://[usb:001,002]/store2/`. When the
26794 * underlying mount (with root
26795 * `gphoto2://[usb:001,002]/`) is mounted, said
26796 * #GVolumeMonitor implementation would create two #GMount objects
26797 * (each with their root matching the corresponding volume activation
26798 * root) that would shadow the original mount.
26800 * The proxy monitor in GVfs 2.26 and later, automatically creates and
26801 * manage shadow mounts (and shadows the underlying mount) if the
26802 * activation root on a #GVolume is set.
26804 * Returns: %TRUE if @mount is shadowed.
26810 * g_mount_operation_get_anonymous:
26811 * @op: a #GMountOperation.
26813 * Check to see whether the mount operation is being used
26814 * for an anonymous user.
26816 * Returns: %TRUE if mount operation is anonymous.
26821 * g_mount_operation_get_choice:
26822 * @op: a #GMountOperation.
26824 * Gets a choice from the mount operation.
26826 * Returns: an integer containing an index of the user's choice from
26827 * the choice's list, or %0.
26832 * g_mount_operation_get_domain:
26833 * @op: a #GMountOperation.
26835 * Gets the domain of the mount operation.
26837 * Returns: a string set to the domain.
26842 * g_mount_operation_get_password:
26843 * @op: a #GMountOperation.
26845 * Gets a password from the mount operation.
26847 * Returns: a string containing the password within @op.
26852 * g_mount_operation_get_password_save:
26853 * @op: a #GMountOperation.
26855 * Gets the state of saving passwords for the mount operation.
26857 * Returns: a #GPasswordSave flag.
26862 * g_mount_operation_get_username:
26863 * @op: a #GMountOperation.
26865 * Get the user name from the mount operation.
26867 * Returns: a string containing the user name.
26872 * g_mount_operation_new:
26874 * Creates a new mount operation.
26876 * Returns: a #GMountOperation.
26881 * g_mount_operation_reply:
26882 * @op: a #GMountOperation
26883 * @result: a #GMountOperationResult
26885 * Emits the #GMountOperation::reply signal.
26890 * g_mount_operation_set_anonymous:
26891 * @op: a #GMountOperation.
26892 * @anonymous: boolean value.
26894 * Sets the mount operation to use an anonymous user if @anonymous is %TRUE.
26899 * g_mount_operation_set_choice:
26900 * @op: a #GMountOperation.
26901 * @choice: an integer.
26903 * Sets a default choice for the mount operation.
26908 * g_mount_operation_set_domain:
26909 * @op: a #GMountOperation.
26910 * @domain: the domain to set.
26912 * Sets the mount operation's domain.
26917 * g_mount_operation_set_password:
26918 * @op: a #GMountOperation.
26919 * @password: password to set.
26921 * Sets the mount operation's password to @password.
26926 * g_mount_operation_set_password_save:
26927 * @op: a #GMountOperation.
26928 * @save: a set of #GPasswordSave flags.
26930 * Sets the state of saving passwords for the mount operation.
26935 * g_mount_operation_set_username:
26936 * @op: a #GMountOperation.
26937 * @username: input username.
26939 * Sets the user name within @op to @username.
26945 * @mount: a #GMount.
26946 * @flags: flags affecting the operation
26947 * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid
26948 * user interaction.
26949 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
26950 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
26951 * @user_data: user data passed to @callback.
26953 * Remounts a mount. This is an asynchronous operation, and is
26954 * finished by calling g_mount_remount_finish() with the @mount
26955 * and #GAsyncResults data returned in the @callback.
26957 * Remounting is useful when some setting affecting the operation
26958 * of the volume has been changed, as these may need a remount to
26959 * take affect. While this is semantically equivalent with unmounting
26960 * and then remounting not all backends might need to actually be
26966 * g_mount_remount_finish:
26967 * @mount: a #GMount.
26968 * @result: a #GAsyncResult.
26969 * @error: a #GError location to store the error occurring, or %NULL to
26972 * Finishes remounting a mount. If any errors occurred during the operation,
26973 * @error will be set to contain the errors and %FALSE will be returned.
26975 * Returns: %TRUE if the mount was successfully remounted. %FALSE otherwise.
26981 * @mount: A #GMount.
26983 * Increments the shadow count on @mount. Usually used by
26984 * #GVolumeMonitor implementations when creating a shadow mount for
26985 * @mount, see g_mount_is_shadowed() for more information. The caller
26986 * will need to emit the #GMount::changed signal on @mount manually.
26994 * @mount: a #GMount.
26995 * @flags: flags affecting the operation
26996 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
26997 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
26998 * @user_data: user data passed to @callback.
27000 * Unmounts a mount. This is an asynchronous operation, and is
27001 * finished by calling g_mount_unmount_finish() with the @mount
27002 * and #GAsyncResult data returned in the @callback.
27004 * Deprecated: 2.22: Use g_mount_unmount_with_operation() instead.
27009 * g_mount_unmount_finish:
27010 * @mount: a #GMount.
27011 * @result: a #GAsyncResult.
27012 * @error: a #GError location to store the error occurring, or %NULL to
27015 * Finishes unmounting a mount. If any errors occurred during the operation,
27016 * @error will be set to contain the errors and %FALSE will be returned.
27018 * Returns: %TRUE if the mount was successfully unmounted. %FALSE otherwise.
27019 * Deprecated: 2.22: Use g_mount_unmount_with_operation_finish() instead.
27024 * g_mount_unmount_with_operation:
27025 * @mount: a #GMount.
27026 * @flags: flags affecting the operation
27027 * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid
27028 * user interaction.
27029 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
27030 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
27031 * @user_data: user data passed to @callback.
27033 * Unmounts a mount. This is an asynchronous operation, and is
27034 * finished by calling g_mount_unmount_with_operation_finish() with the @mount
27035 * and #GAsyncResult data returned in the @callback.
27042 * g_mount_unmount_with_operation_finish:
27043 * @mount: a #GMount.
27044 * @result: a #GAsyncResult.
27045 * @error: a #GError location to store the error occurring, or %NULL to
27048 * Finishes unmounting a mount. If any errors occurred during the operation,
27049 * @error will be set to contain the errors and %FALSE will be returned.
27051 * Returns: %TRUE if the mount was successfully unmounted. %FALSE otherwise.
27057 * g_mount_unshadow:
27058 * @mount: A #GMount.
27060 * Decrements the shadow count on @mount. Usually used by
27061 * #GVolumeMonitor implementations when destroying a shadow mount for
27062 * @mount, see g_mount_is_shadowed() for more information. The caller
27063 * will need to emit the #GMount::changed signal on @mount manually.
27070 * g_network_address_get_hostname:
27071 * @addr: a #GNetworkAddress
27073 * Gets @addr's hostname. This might be either UTF-8 or ASCII-encoded,
27074 * depending on what @addr was created with.
27076 * Returns: @addr's hostname
27082 * g_network_address_get_port:
27083 * @addr: a #GNetworkAddress
27085 * Gets @addr's port number
27087 * Returns: @addr's port (which may be 0)
27093 * g_network_address_get_scheme:
27094 * @addr: a #GNetworkAddress
27096 * Gets @addr's scheme
27098 * Returns: @addr's scheme (%NULL if not built from URI)
27104 * g_network_address_new:
27105 * @hostname: the hostname
27108 * Creates a new #GSocketConnectable for connecting to the given
27109 * @hostname and @port.
27111 * Returns: (transfer full) (type GNetworkAddress): the new #GNetworkAddress
27117 * g_network_address_parse:
27118 * @host_and_port: the hostname and optionally a port
27119 * @default_port: the default port if not in @host_and_port
27120 * @error: a pointer to a #GError, or %NULL
27122 * Creates a new #GSocketConnectable for connecting to the given
27123 * @hostname and @port. May fail and return %NULL in case
27124 * parsing @host_and_port fails.
27126 * @host_and_port may be in any of a number of recognised formats; an IPv6
27127 * address, an IPv4 address, or a domain name (in which case a DNS
27128 * lookup is performed). Quoting with [] is supported for all address
27129 * types. A port override may be specified in the usual way with a
27132 * If no port is specified in @host_and_port then @default_port will be
27133 * used as the port number to connect to.
27135 * In general, @host_and_port is expected to be provided by the user
27136 * (allowing them to give the hostname, and a port overide if necessary)
27137 * and @default_port is expected to be provided by the application.
27139 * (The port component of @host_and_port can also be specified as a
27140 * service name rather than as a numeric port, but this functionality
27141 * is deprecated, because it depends on the contents of /etc/services,
27142 * which is generally quite sparse on platforms other than Linux.)
27144 * Returns: (transfer full): the new #GNetworkAddress, or %NULL on error
27150 * g_network_address_parse_uri:
27151 * @uri: the hostname and optionally a port
27152 * @default_port: The default port if none is found in the URI
27153 * @error: a pointer to a #GError, or %NULL
27155 * Creates a new #GSocketConnectable for connecting to the given
27156 * @uri. May fail and return %NULL in case parsing @uri fails.
27158 * Using this rather than g_network_address_new() or
27159 * g_network_address_parse() allows #GSocketClient to determine
27160 * when to use application-specific proxy protocols.
27162 * Returns: (transfer full): the new #GNetworkAddress, or %NULL on error
27168 * g_network_monitor_base_add_network:
27169 * @monitor: the #GNetworkMonitorBase
27170 * @network: a #GInetAddressMask
27172 * Adds @network to @monitor's list of available networks.
27179 * g_network_monitor_base_remove_network:
27180 * @monitor: the #GNetworkMonitorBase
27181 * @network: a #GInetAddressMask
27183 * Removes @network from @monitor's list of available networks.
27190 * g_network_monitor_base_set_networks:
27191 * @monitor: the #GNetworkMonitorBase
27192 * @networks: (array length=length): an array of #GInetAddressMask
27193 * @length: length of @networks
27195 * Drops @monitor's current list of available networks and replaces
27196 * it with @networks.
27201 * g_network_monitor_can_reach:
27202 * @monitor: a #GNetworkMonitor
27203 * @connectable: a #GSocketConnectable
27204 * @cancellable: (allow-none): a #GCancellable, or %NULL
27205 * @error: return location for a #GError, or %NULL
27207 * Attempts to determine whether or not the host pointed to by
27208 * @connectable can be reached, without actually trying to connect to
27211 * This may return %TRUE even when #GNetworkMonitor:network-available
27212 * is %FALSE, if, for example, @monitor can determine that
27213 * @connectable refers to a host on a local network.
27215 * If @monitor believes that an attempt to connect to @connectable
27216 * will succeed, it will return %TRUE. Otherwise, it will return
27217 * %FALSE and set @error to an appropriate error (such as
27218 * %G_IO_ERROR_HOST_UNREACHABLE).
27220 * Note that although this does not attempt to connect to
27221 * @connectable, it may still block for a brief period of time (eg,
27222 * trying to do multicast DNS on the local network), so if you do not
27223 * want to block, you should use g_network_monitor_can_reach_async().
27225 * Returns: %TRUE if @connectable is reachable, %FALSE if not.
27231 * g_network_monitor_can_reach_async:
27232 * @monitor: a #GNetworkMonitor
27233 * @connectable: a #GSocketConnectable
27234 * @cancellable: (allow-none): a #GCancellable, or %NULL
27235 * @callback: (scope async): a #GAsyncReadyCallback to call when the
27236 * request is satisfied
27237 * @user_data: (closure): the data to pass to callback function
27239 * Asynchronously attempts to determine whether or not the host
27240 * pointed to by @connectable can be reached, without actually
27241 * trying to connect to it.
27243 * For more details, see g_network_monitor_can_reach().
27245 * When the operation is finished, @callback will be called.
27246 * You can then call g_network_monitor_can_reach_finish()
27247 * to get the result of the operation.
27252 * g_network_monitor_can_reach_finish:
27253 * @monitor: a #GNetworkMonitor
27254 * @result: a #GAsyncResult
27255 * @error: return location for errors, or %NULL
27257 * Finishes an async network connectivity test.
27258 * See g_network_monitor_can_reach_async().
27260 * Returns: %TRUE if network is reachable, %FALSE if not.
27265 * g_network_monitor_get_default:
27267 * Gets the default #GNetworkMonitor for the system.
27269 * Returns: (transfer none): a #GNetworkMonitor
27275 * g_network_monitor_get_network_available:
27276 * @monitor: the #GNetworkMonitor
27278 * Checks if the network is available. "Available" here means that the
27279 * system has a default route available for at least one of IPv4 or
27280 * IPv6. It does not necessarily imply that the public Internet is
27281 * reachable. See #GNetworkMonitor:network-available for more details.
27283 * Returns: whether the network is available
27289 * g_network_service_get_domain:
27290 * @srv: a #GNetworkService
27292 * Gets the domain that @srv serves. This might be either UTF-8 or
27293 * ASCII-encoded, depending on what @srv was created with.
27295 * Returns: @srv's domain name
27301 * g_network_service_get_protocol:
27302 * @srv: a #GNetworkService
27304 * Gets @srv's protocol name (eg, "tcp").
27306 * Returns: @srv's protocol name
27312 * g_network_service_get_scheme:
27313 * @srv: a #GNetworkService
27315 * Get's the URI scheme used to resolve proxies. By default, the service name
27316 * is used as scheme.
27318 * Returns: @srv's scheme name
27324 * g_network_service_get_service:
27325 * @srv: a #GNetworkService
27327 * Gets @srv's service name (eg, "ldap").
27329 * Returns: @srv's service name
27335 * g_network_service_new:
27336 * @service: the service type to look up (eg, "ldap")
27337 * @protocol: the networking protocol to use for @service (eg, "tcp")
27338 * @domain: the DNS domain to look up the service in
27340 * Creates a new #GNetworkService representing the given @service,
27341 * @protocol, and @domain. This will initially be unresolved; use the
27342 * #GSocketConnectable interface to resolve it.
27344 * Returns: (transfer full) (type GNetworkService): a new #GNetworkService
27350 * g_network_service_set_scheme:
27351 * @srv: a #GNetworkService
27352 * @scheme: a URI scheme
27354 * Set's the URI scheme used to resolve proxies. By default, the service name
27355 * is used as scheme.
27362 * g_networking_init:
27364 * Initializes the platform networking libraries (eg, on Windows, this
27365 * calls WSAStartup()). GLib will call this itself if it is needed, so
27366 * you only need to call it if you directly call system networking
27367 * functions (without calling any GLib networking functions first).
27374 * g_notification_add_button:
27375 * @notification: a #GNotification
27376 * @label: label of the button
27377 * @detailed_action: a detailed action name
27379 * Adds a button to @notification that activates the action in
27380 * @detailed_action when clicked. That action must be an
27381 * application-wide action (starting with "app."). If @detailed_action
27382 * contains a target, the action will be activated with that target as
27385 * See g_action_parse_detailed_name() for a description of the format
27386 * for @detailed_action.
27393 * g_notification_add_button_with_target: (skip)
27394 * @notification: a #GNotification
27395 * @label: label of the button
27396 * @action: an action name
27397 * @target_format: (allow-none): a #GVariant format string, or %NULL
27398 * @...: positional parameters, as determined by @target_format
27400 * Adds a button to @notification that activates @action when clicked.
27401 * @action must be an application-wide action (it must start with "app.").
27403 * If @target_format is given, it is used to collect remaining
27404 * positional parameters into a #GVariant instance, similar to
27405 * g_variant_new(). @action will be activated with that #GVariant as its
27413 * g_notification_add_button_with_target_value: (rename-to g_notification_add_button_with_target)
27414 * @notification: a #GNotification
27415 * @label: label of the button
27416 * @action: an action name
27417 * @target: (allow-none): a #GVariant to use as @action's parameter, or %NULL
27419 * Adds a button to @notification that activates @action when clicked.
27420 * @action must be an application-wide action (it must start with "app.").
27422 * If @target is non-%NULL, @action will be activated with @target as
27430 * g_notification_new:
27431 * @title: the title of the notification
27433 * Creates a new #GNotification with @title as its title.
27435 * After populating @notification with more details, it can be sent to
27436 * the desktop shell with g_application_send_notification(). Changing
27437 * any properties after this call will not have any effect until
27438 * resending @notification.
27440 * Returns: a new #GNotification instance
27446 * g_notification_set_body:
27447 * @notification: a #GNotification
27448 * @body: (allow-none): the new body for @notification, or %NULL
27450 * Sets the body of @notification to @body.
27457 * g_notification_set_default_action:
27458 * @notification: a #GNotification
27459 * @detailed_action: a detailed action name
27461 * Sets the default action of @notification to @detailed_action. This
27462 * action is activated when the notification is clicked on.
27464 * The action in @detailed_action must be an application-wide action (it
27465 * must start with "app."). If @detailed_action contains a target, the
27466 * given action will be activated with that target as its parameter.
27467 * See g_action_parse_detailed_name() for a description of the format
27468 * for @detailed_action.
27470 * When no default action is set, the application that the notification
27471 * was sent on is activated.
27478 * g_notification_set_default_action_and_target: (skip)
27479 * @notification: a #GNotification
27480 * @action: an action name
27481 * @target_format: (allow-none): a #GVariant format string, or %NULL
27482 * @...: positional parameters, as determined by @target_format
27484 * Sets the default action of @notification to @action. This action is
27485 * activated when the notification is clicked on. It must be an
27486 * application-wide action (it must start with "app.").
27488 * If @target_format is given, it is used to collect remaining
27489 * positional parameters into a #GVariant instance, similar to
27490 * g_variant_new(). @action will be activated with that #GVariant as its
27493 * When no default action is set, the application that the notification
27494 * was sent on is activated.
27501 * g_notification_set_default_action_and_target_value: (rename-to g_notification_set_default_action_and_target)
27502 * @notification: a #GNotification
27503 * @action: an action name
27504 * @target: (allow-none): a #GVariant to use as @action's parameter, or %NULL
27506 * Sets the default action of @notification to @action. This action is
27507 * activated when the notification is clicked on. It must be an
27508 * application-wide action (start with "app.").
27510 * If @target is non-%NULL, @action will be activated with @target as
27513 * When no default action is set, the application that the notification
27514 * was sent on is activated.
27521 * g_notification_set_icon:
27522 * @notification: a #GNotification
27523 * @icon: the icon to be shown in @notification, as a #GIcon
27525 * Sets the icon of @notification to @icon.
27532 * g_notification_set_priority:
27533 * @notification: a #GNotification
27534 * @priority: a #GNotificationPriority
27536 * Sets the priority of @notification to @priority. See
27537 * #GNotificationPriority for possible values.
27542 * g_notification_set_title:
27543 * @notification: a #GNotification
27544 * @title: the new title for @notification
27546 * Sets the title of @notification to @title.
27553 * g_notification_set_urgent:
27554 * @notification: a #GNotification
27555 * @urgent: %TRUE if @notification is urgent
27557 * Deprecated in favor of g_notification_set_priority().
27564 * g_null_settings_backend_new:
27566 * Creates a readonly #GSettingsBackend.
27568 * This backend does not allow changes to settings, so all settings
27569 * will always have their default values.
27571 * Returns: (transfer full): a newly created #GSettingsBackend
27577 * g_output_stream_async_write_is_via_threads:
27578 * @stream: a #GOutputStream.
27580 * Checks if an ouput stream's write_async function uses threads.
27582 * Returns: %TRUE if @stream's write_async function uses threads.
27587 * g_output_stream_clear_pending:
27588 * @stream: output stream
27590 * Clears the pending flag on @stream.
27595 * g_output_stream_close:
27596 * @stream: A #GOutputStream.
27597 * @cancellable: (allow-none): optional cancellable object
27598 * @error: location to store the error occurring, or %NULL to ignore
27600 * Closes the stream, releasing resources related to it.
27602 * Once the stream is closed, all other operations will return %G_IO_ERROR_CLOSED.
27603 * Closing a stream multiple times will not return an error.
27605 * Closing a stream will automatically flush any outstanding buffers in the
27608 * Streams will be automatically closed when the last reference
27609 * is dropped, but you might want to call this function to make sure
27610 * resources are released as early as possible.
27612 * Some streams might keep the backing store of the stream (e.g. a file descriptor)
27613 * open after the stream is closed. See the documentation for the individual
27614 * stream for details.
27616 * On failure the first error that happened will be reported, but the close
27617 * operation will finish as much as possible. A stream that failed to
27618 * close will still return %G_IO_ERROR_CLOSED for all operations. Still, it
27619 * is important to check and report the error to the user, otherwise
27620 * there might be a loss of data as all data might not be written.
27622 * If @cancellable is not %NULL, then the operation can be cancelled by
27623 * triggering the cancellable object from another thread. If the operation
27624 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
27625 * Cancelling a close will still leave the stream closed, but there some streams
27626 * can use a faster close that doesn't block to e.g. check errors. On
27627 * cancellation (as with any error) there is no guarantee that all written
27628 * data will reach the target.
27630 * Returns: %TRUE on success, %FALSE on failure
27635 * g_output_stream_close_async:
27636 * @stream: A #GOutputStream.
27637 * @io_priority: the io priority of the request.
27638 * @cancellable: (allow-none): optional cancellable object
27639 * @callback: (scope async): callback to call when the request is satisfied
27640 * @user_data: (closure): the data to pass to callback function
27642 * Requests an asynchronous close of the stream, releasing resources
27643 * related to it. When the operation is finished @callback will be
27644 * called. You can then call g_output_stream_close_finish() to get
27645 * the result of the operation.
27647 * For behaviour details see g_output_stream_close().
27649 * The asyncronous methods have a default fallback that uses threads
27650 * to implement asynchronicity, so they are optional for inheriting
27651 * classes. However, if you override one you must override all.
27656 * g_output_stream_close_finish:
27657 * @stream: a #GOutputStream.
27658 * @result: a #GAsyncResult.
27659 * @error: a #GError location to store the error occurring, or %NULL to
27662 * Closes an output stream.
27664 * Returns: %TRUE if stream was successfully closed, %FALSE otherwise.
27669 * g_output_stream_flush:
27670 * @stream: a #GOutputStream.
27671 * @cancellable: (allow-none): optional cancellable object
27672 * @error: location to store the error occurring, or %NULL to ignore
27674 * Forces a write of all user-space buffered data for the given
27675 * @stream. Will block during the operation. Closing the stream will
27676 * implicitly cause a flush.
27678 * This function is optional for inherited classes.
27680 * If @cancellable is not %NULL, then the operation can be cancelled by
27681 * triggering the cancellable object from another thread. If the operation
27682 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
27684 * Returns: %TRUE on success, %FALSE on error
27689 * g_output_stream_flush_async:
27690 * @stream: a #GOutputStream.
27691 * @io_priority: the io priority of the request.
27692 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
27693 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
27694 * @user_data: (closure): the data to pass to callback function
27696 * Forces an asynchronous write of all user-space buffered data for
27697 * the given @stream.
27698 * For behaviour details see g_output_stream_flush().
27700 * When the operation is finished @callback will be
27701 * called. You can then call g_output_stream_flush_finish() to get the
27702 * result of the operation.
27707 * g_output_stream_flush_finish:
27708 * @stream: a #GOutputStream.
27709 * @result: a GAsyncResult.
27710 * @error: a #GError location to store the error occurring, or %NULL to
27713 * Finishes flushing an output stream.
27715 * Returns: %TRUE if flush operation succeeded, %FALSE otherwise.
27720 * g_output_stream_has_pending:
27721 * @stream: a #GOutputStream.
27723 * Checks if an ouput stream has pending actions.
27725 * Returns: %TRUE if @stream has pending actions.
27730 * g_output_stream_is_closed:
27731 * @stream: a #GOutputStream.
27733 * Checks if an output stream has already been closed.
27735 * Returns: %TRUE if @stream is closed. %FALSE otherwise.
27740 * g_output_stream_is_closing:
27741 * @stream: a #GOutputStream.
27743 * Checks if an output stream is being closed. This can be
27744 * used inside e.g. a flush implementation to see if the
27745 * flush (or other i/o operation) is called from within
27746 * the closing operation.
27748 * Returns: %TRUE if @stream is being closed. %FALSE otherwise.
27754 * g_output_stream_printf:
27755 * @stream: a #GOutputStream.
27756 * @bytes_written: (out): location to store the number of bytes that was
27757 * written to the stream
27758 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
27759 * @error: location to store the error occurring, or %NULL to ignore
27760 * @format: the format string. See the printf() documentation
27761 * @...: the parameters to insert into the format string
27763 * This is a utility function around g_output_stream_write_all(). It
27764 * uses g_strdup_vprintf() to turn @format and @... into a string that
27765 * is then written to @stream.
27767 * See the documentation of g_output_stream_write_all() about the
27768 * behavior of the actual write operation.
27770 * Note that partial writes cannot be properly checked with this
27771 * function due to the variable length of the written string, if you
27772 * need precise control over partial write failures, you need to
27773 * create you own printf()-like wrapper around g_output_stream_write()
27774 * or g_output_stream_write_all().
27777 * Returns: %TRUE on success, %FALSE if there was an error
27782 * g_output_stream_set_pending:
27783 * @stream: a #GOutputStream.
27784 * @error: a #GError location to store the error occurring, or %NULL to
27787 * Sets @stream to have actions pending. If the pending flag is
27788 * already set or @stream is closed, it will return %FALSE and set
27791 * Returns: %TRUE if pending was previously unset and is now set.
27796 * g_output_stream_splice:
27797 * @stream: a #GOutputStream.
27798 * @source: a #GInputStream.
27799 * @flags: a set of #GOutputStreamSpliceFlags.
27800 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
27801 * @error: a #GError location to store the error occurring, or %NULL to
27804 * Splices an input stream into an output stream.
27806 * Returns: a #gssize containing the size of the data spliced, or
27807 * -1 if an error occurred. Note that if the number of bytes
27808 * spliced is greater than %G_MAXSSIZE, then that will be
27809 * returned, and there is no way to determine the actual number
27810 * of bytes spliced.
27815 * g_output_stream_splice_async:
27816 * @stream: a #GOutputStream.
27817 * @source: a #GInputStream.
27818 * @flags: a set of #GOutputStreamSpliceFlags.
27819 * @io_priority: the io priority of the request.
27820 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
27821 * @callback: (scope async): a #GAsyncReadyCallback.
27822 * @user_data: (closure): user data passed to @callback.
27824 * Splices a stream asynchronously.
27825 * When the operation is finished @callback will be called.
27826 * You can then call g_output_stream_splice_finish() to get the
27827 * result of the operation.
27829 * For the synchronous, blocking version of this function, see
27830 * g_output_stream_splice().
27835 * g_output_stream_splice_finish:
27836 * @stream: a #GOutputStream.
27837 * @result: a #GAsyncResult.
27838 * @error: a #GError location to store the error occurring, or %NULL to
27841 * Finishes an asynchronous stream splice operation.
27843 * Returns: a #gssize of the number of bytes spliced. Note that if the
27844 * number of bytes spliced is greater than %G_MAXSSIZE, then that
27845 * will be returned, and there is no way to determine the actual
27846 * number of bytes spliced.
27851 * g_output_stream_vprintf:
27852 * @stream: a #GOutputStream.
27853 * @bytes_written: (out): location to store the number of bytes that was
27854 * written to the stream
27855 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
27856 * @error: location to store the error occurring, or %NULL to ignore
27857 * @format: the format string. See the printf() documentation
27858 * @args: the parameters to insert into the format string
27860 * This is a utility function around g_output_stream_write_all(). It
27861 * uses g_strdup_vprintf() to turn @format and @args into a string that
27862 * is then written to @stream.
27864 * See the documentation of g_output_stream_write_all() about the
27865 * behavior of the actual write operation.
27867 * Note that partial writes cannot be properly checked with this
27868 * function due to the variable length of the written string, if you
27869 * need precise control over partial write failures, you need to
27870 * create you own printf()-like wrapper around g_output_stream_write()
27871 * or g_output_stream_write_all().
27874 * Returns: %TRUE on success, %FALSE if there was an error
27879 * g_output_stream_write: (virtual write_fn)
27880 * @stream: a #GOutputStream.
27881 * @buffer: (array length=count) (element-type guint8): the buffer containing the data to write.
27882 * @count: the number of bytes to write
27883 * @cancellable: (allow-none): optional cancellable object
27884 * @error: location to store the error occurring, or %NULL to ignore
27886 * Tries to write @count bytes from @buffer into the stream. Will block
27887 * during the operation.
27889 * If count is 0, returns 0 and does nothing. A value of @count
27890 * larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
27892 * On success, the number of bytes written to the stream is returned.
27893 * It is not an error if this is not the same as the requested size, as it
27894 * can happen e.g. on a partial I/O error, or if there is not enough
27895 * storage in the stream. All writes block until at least one byte
27896 * is written or an error occurs; 0 is never returned (unless
27899 * If @cancellable is not %NULL, then the operation can be cancelled by
27900 * triggering the cancellable object from another thread. If the operation
27901 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
27902 * operation was partially finished when the operation was cancelled the
27903 * partial result will be returned, without an error.
27905 * On error -1 is returned and @error is set accordingly.
27907 * Returns: Number of bytes written, or -1 on error
27912 * g_output_stream_write_all:
27913 * @stream: a #GOutputStream.
27914 * @buffer: (array length=count) (element-type guint8): the buffer containing the data to write.
27915 * @count: the number of bytes to write
27916 * @bytes_written: (out): location to store the number of bytes that was
27917 * written to the stream
27918 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
27919 * @error: location to store the error occurring, or %NULL to ignore
27921 * Tries to write @count bytes from @buffer into the stream. Will block
27922 * during the operation.
27924 * This function is similar to g_output_stream_write(), except it tries to
27925 * write as many bytes as requested, only stopping on an error.
27927 * On a successful write of @count bytes, %TRUE is returned, and @bytes_written
27928 * is set to @count.
27930 * If there is an error during the operation %FALSE is returned and @error
27931 * is set to indicate the error status, @bytes_written is updated to contain
27932 * the number of bytes written into the stream before the error occurred.
27934 * Returns: %TRUE on success, %FALSE if there was an error
27939 * g_output_stream_write_async:
27940 * @stream: A #GOutputStream.
27941 * @buffer: (array length=count) (element-type guint8): the buffer containing the data to write.
27942 * @count: the number of bytes to write
27943 * @io_priority: the io priority of the request.
27944 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
27945 * @callback: (scope async): callback to call when the request is satisfied
27946 * @user_data: (closure): the data to pass to callback function
27948 * Request an asynchronous write of @count bytes from @buffer into
27949 * the stream. When the operation is finished @callback will be called.
27950 * You can then call g_output_stream_write_finish() to get the result of the
27953 * During an async request no other sync and async calls are allowed,
27954 * and will result in %G_IO_ERROR_PENDING errors.
27956 * A value of @count larger than %G_MAXSSIZE will cause a
27957 * %G_IO_ERROR_INVALID_ARGUMENT error.
27959 * On success, the number of bytes written will be passed to the
27960 * @callback. It is not an error if this is not the same as the
27961 * requested size, as it can happen e.g. on a partial I/O error,
27962 * but generally we try to write as many bytes as requested.
27964 * You are guaranteed that this method will never fail with
27965 * %G_IO_ERROR_WOULD_BLOCK - if @stream can't accept more data, the
27966 * method will just wait until this changes.
27968 * Any outstanding I/O request with higher priority (lower numerical
27969 * value) will be executed before an outstanding request with lower
27970 * priority. Default priority is %G_PRIORITY_DEFAULT.
27972 * The asyncronous methods have a default fallback that uses threads
27973 * to implement asynchronicity, so they are optional for inheriting
27974 * classes. However, if you override one you must override all.
27976 * For the synchronous, blocking version of this function, see
27977 * g_output_stream_write().
27979 * Note that no copy of @buffer will be made, so it must stay valid
27980 * until @callback is called. See g_output_stream_write_bytes_async()
27981 * for a #GBytes version that will automatically hold a reference to
27982 * the contents (without copying) for the duration of the call.
27987 * g_output_stream_write_bytes:
27988 * @stream: a #GOutputStream.
27989 * @bytes: the #GBytes to write
27990 * @cancellable: (allow-none): optional cancellable object
27991 * @error: location to store the error occurring, or %NULL to ignore
27993 * A wrapper function for g_output_stream_write() which takes a
27994 * #GBytes as input. This can be more convenient for use by language
27995 * bindings or in other cases where the refcounted nature of #GBytes
27996 * is helpful over a bare pointer interface.
27998 * However, note that this function may still perform partial writes,
27999 * just like g_output_stream_write(). If that occurs, to continue
28000 * writing, you will need to create a new #GBytes containing just the
28001 * remaining bytes, using g_bytes_new_from_bytes(). Passing the same
28002 * #GBytes instance multiple times potentially can result in duplicated
28003 * data in the output stream.
28005 * Returns: Number of bytes written, or -1 on error
28010 * g_output_stream_write_bytes_async:
28011 * @stream: A #GOutputStream.
28012 * @bytes: The bytes to write
28013 * @io_priority: the io priority of the request.
28014 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
28015 * @callback: (scope async): callback to call when the request is satisfied
28016 * @user_data: (closure): the data to pass to callback function
28018 * This function is similar to g_output_stream_write_async(), but
28019 * takes a #GBytes as input. Due to the refcounted nature of #GBytes,
28020 * this allows the stream to avoid taking a copy of the data.
28022 * However, note that this function may still perform partial writes,
28023 * just like g_output_stream_write_async(). If that occurs, to continue
28024 * writing, you will need to create a new #GBytes containing just the
28025 * remaining bytes, using g_bytes_new_from_bytes(). Passing the same
28026 * #GBytes instance multiple times potentially can result in duplicated
28027 * data in the output stream.
28029 * For the synchronous, blocking version of this function, see
28030 * g_output_stream_write_bytes().
28035 * g_output_stream_write_bytes_finish:
28036 * @stream: a #GOutputStream.
28037 * @result: a #GAsyncResult.
28038 * @error: a #GError location to store the error occurring, or %NULL to
28041 * Finishes a stream write-from-#GBytes operation.
28043 * Returns: a #gssize containing the number of bytes written to the stream.
28048 * g_output_stream_write_finish:
28049 * @stream: a #GOutputStream.
28050 * @result: a #GAsyncResult.
28051 * @error: a #GError location to store the error occurring, or %NULL to
28054 * Finishes a stream write operation.
28056 * Returns: a #gssize containing the number of bytes written to the stream.
28061 * g_permission_acquire:
28062 * @permission: a #GPermission instance
28063 * @cancellable: (allow-none): a #GCancellable, or %NULL
28064 * @error: a pointer to a %NULL #GError, or %NULL
28066 * Attempts to acquire the permission represented by @permission.
28068 * The precise method by which this happens depends on the permission
28069 * and the underlying authentication mechanism. A simple example is
28070 * that a dialog may appear asking the user to enter their password.
28072 * You should check with g_permission_get_can_acquire() before calling
28075 * If the permission is acquired then %TRUE is returned. Otherwise,
28076 * %FALSE is returned and @error is set appropriately.
28078 * This call is blocking, likely for a very long time (in the case that
28079 * user interaction is required). See g_permission_acquire_async() for
28080 * the non-blocking version.
28082 * Returns: %TRUE if the permission was successfully acquired
28088 * g_permission_acquire_async:
28089 * @permission: a #GPermission instance
28090 * @cancellable: (allow-none): a #GCancellable, or %NULL
28091 * @callback: the #GAsyncReadyCallback to call when done
28092 * @user_data: the user data to pass to @callback
28094 * Attempts to acquire the permission represented by @permission.
28096 * This is the first half of the asynchronous version of
28097 * g_permission_acquire().
28104 * g_permission_acquire_finish:
28105 * @permission: a #GPermission instance
28106 * @result: the #GAsyncResult given to the #GAsyncReadyCallback
28107 * @error: a pointer to a %NULL #GError, or %NULL
28109 * Collects the result of attempting to acquire the permission
28110 * represented by @permission.
28112 * This is the second half of the asynchronous version of
28113 * g_permission_acquire().
28115 * Returns: %TRUE if the permission was successfully acquired
28121 * g_permission_get_allowed:
28122 * @permission: a #GPermission instance
28124 * Gets the value of the 'allowed' property. This property is %TRUE if
28125 * the caller currently has permission to perform the action that
28126 * @permission represents the permission to perform.
28128 * Returns: the value of the 'allowed' property
28134 * g_permission_get_can_acquire:
28135 * @permission: a #GPermission instance
28137 * Gets the value of the 'can-acquire' property. This property is %TRUE
28138 * if it is generally possible to acquire the permission by calling
28139 * g_permission_acquire().
28141 * Returns: the value of the 'can-acquire' property
28147 * g_permission_get_can_release:
28148 * @permission: a #GPermission instance
28150 * Gets the value of the 'can-release' property. This property is %TRUE
28151 * if it is generally possible to release the permission by calling
28152 * g_permission_release().
28154 * Returns: the value of the 'can-release' property
28160 * g_permission_impl_update:
28161 * @permission: a #GPermission instance
28162 * @allowed: the new value for the 'allowed' property
28163 * @can_acquire: the new value for the 'can-acquire' property
28164 * @can_release: the new value for the 'can-release' property
28166 * This function is called by the #GPermission implementation to update
28167 * the properties of the permission. You should never call this
28168 * function except from a #GPermission implementation.
28170 * GObject notify signals are generated, as appropriate.
28177 * g_permission_release:
28178 * @permission: a #GPermission instance
28179 * @cancellable: (allow-none): a #GCancellable, or %NULL
28180 * @error: a pointer to a %NULL #GError, or %NULL
28182 * Attempts to release the permission represented by @permission.
28184 * The precise method by which this happens depends on the permission
28185 * and the underlying authentication mechanism. In most cases the
28186 * permission will be dropped immediately without further action.
28188 * You should check with g_permission_get_can_release() before calling
28191 * If the permission is released then %TRUE is returned. Otherwise,
28192 * %FALSE is returned and @error is set appropriately.
28194 * This call is blocking, likely for a very long time (in the case that
28195 * user interaction is required). See g_permission_release_async() for
28196 * the non-blocking version.
28198 * Returns: %TRUE if the permission was successfully released
28204 * g_permission_release_async:
28205 * @permission: a #GPermission instance
28206 * @cancellable: (allow-none): a #GCancellable, or %NULL
28207 * @callback: the #GAsyncReadyCallback to call when done
28208 * @user_data: the user data to pass to @callback
28210 * Attempts to release the permission represented by @permission.
28212 * This is the first half of the asynchronous version of
28213 * g_permission_release().
28220 * g_permission_release_finish:
28221 * @permission: a #GPermission instance
28222 * @result: the #GAsyncResult given to the #GAsyncReadyCallback
28223 * @error: a pointer to a %NULL #GError, or %NULL
28225 * Collects the result of attempting to release the permission
28226 * represented by @permission.
28228 * This is the second half of the asynchronous version of
28229 * g_permission_release().
28231 * Returns: %TRUE if the permission was successfully released
28237 * g_poll_file_monitor_new:
28240 * Polls @file for changes.
28242 * Returns: a new #GFileMonitor for the given #GFile.
28247 * g_pollable_input_stream_can_poll:
28248 * @stream: a #GPollableInputStream.
28250 * Checks if @stream is actually pollable. Some classes may implement
28251 * #GPollableInputStream but have only certain instances of that class
28252 * be pollable. If this method returns %FALSE, then the behavior of
28253 * other #GPollableInputStream methods is undefined.
28255 * For any given stream, the value returned by this method is constant;
28256 * a stream cannot switch from pollable to non-pollable or vice versa.
28258 * Returns: %TRUE if @stream is pollable, %FALSE if not.
28264 * g_pollable_input_stream_create_source:
28265 * @stream: a #GPollableInputStream.
28266 * @cancellable: (allow-none): a #GCancellable, or %NULL
28268 * Creates a #GSource that triggers when @stream can be read, or
28269 * @cancellable is triggered or an error occurs. The callback on the
28270 * source is of the #GPollableSourceFunc type.
28272 * As with g_pollable_input_stream_is_readable(), it is possible that
28273 * the stream may not actually be readable even after the source
28274 * triggers, so you should use g_pollable_input_stream_read_nonblocking()
28275 * rather than g_input_stream_read() from the callback.
28277 * Returns: (transfer full): a new #GSource
28283 * g_pollable_input_stream_is_readable:
28284 * @stream: a #GPollableInputStream.
28286 * Checks if @stream can be read.
28288 * Note that some stream types may not be able to implement this 100%
28289 * reliably, and it is possible that a call to g_input_stream_read()
28290 * after this returns %TRUE would still block. To guarantee
28291 * non-blocking behavior, you should always use
28292 * g_pollable_input_stream_read_nonblocking(), which will return a
28293 * %G_IO_ERROR_WOULD_BLOCK error rather than blocking.
28295 * Returns: %TRUE if @stream is readable, %FALSE if not. If an error
28296 * has occurred on @stream, this will result in
28297 * g_pollable_input_stream_is_readable() returning %TRUE, and the
28298 * next attempt to read will return the error.
28304 * g_pollable_input_stream_read_nonblocking: (virtual read_nonblocking)
28305 * @stream: a #GPollableInputStream
28306 * @buffer: (array length=count) (element-type guint8): a buffer to
28307 * read data into (which should be at least @count bytes long).
28308 * @count: the number of bytes you want to read
28309 * @cancellable: (allow-none): a #GCancellable, or %NULL
28310 * @error: #GError for error reporting, or %NULL to ignore.
28312 * Attempts to read up to @count bytes from @stream into @buffer, as
28313 * with g_input_stream_read(). If @stream is not currently readable,
28314 * this will immediately return %G_IO_ERROR_WOULD_BLOCK, and you can
28315 * use g_pollable_input_stream_create_source() to create a #GSource
28316 * that will be triggered when @stream is readable.
28318 * Note that since this method never blocks, you cannot actually
28319 * use @cancellable to cancel it. However, it will return an error
28320 * if @cancellable has already been cancelled when you call, which
28321 * may happen if you call this method after a source triggers due
28322 * to having been cancelled.
28324 * Returns: the number of bytes read, or -1 on error (including
28325 * %G_IO_ERROR_WOULD_BLOCK).
28330 * g_pollable_output_stream_can_poll:
28331 * @stream: a #GPollableOutputStream.
28333 * Checks if @stream is actually pollable. Some classes may implement
28334 * #GPollableOutputStream but have only certain instances of that
28335 * class be pollable. If this method returns %FALSE, then the behavior
28336 * of other #GPollableOutputStream methods is undefined.
28338 * For any given stream, the value returned by this method is constant;
28339 * a stream cannot switch from pollable to non-pollable or vice versa.
28341 * Returns: %TRUE if @stream is pollable, %FALSE if not.
28347 * g_pollable_output_stream_create_source:
28348 * @stream: a #GPollableOutputStream.
28349 * @cancellable: (allow-none): a #GCancellable, or %NULL
28351 * Creates a #GSource that triggers when @stream can be written, or
28352 * @cancellable is triggered or an error occurs. The callback on the
28353 * source is of the #GPollableSourceFunc type.
28355 * As with g_pollable_output_stream_is_writable(), it is possible that
28356 * the stream may not actually be writable even after the source
28357 * triggers, so you should use g_pollable_output_stream_write_nonblocking()
28358 * rather than g_output_stream_write() from the callback.
28360 * Returns: (transfer full): a new #GSource
28366 * g_pollable_output_stream_is_writable:
28367 * @stream: a #GPollableOutputStream.
28369 * Checks if @stream can be written.
28371 * Note that some stream types may not be able to implement this 100%
28372 * reliably, and it is possible that a call to g_output_stream_write()
28373 * after this returns %TRUE would still block. To guarantee
28374 * non-blocking behavior, you should always use
28375 * g_pollable_output_stream_write_nonblocking(), which will return a
28376 * %G_IO_ERROR_WOULD_BLOCK error rather than blocking.
28378 * Returns: %TRUE if @stream is writable, %FALSE if not. If an error
28379 * has occurred on @stream, this will result in
28380 * g_pollable_output_stream_is_writable() returning %TRUE, and the
28381 * next attempt to write will return the error.
28387 * g_pollable_output_stream_write_nonblocking: (virtual write_nonblocking)
28388 * @stream: a #GPollableOutputStream
28389 * @buffer: (array length=count) (element-type guint8): a buffer to write
28391 * @count: the number of bytes you want to write
28392 * @cancellable: (allow-none): a #GCancellable, or %NULL
28393 * @error: #GError for error reporting, or %NULL to ignore.
28395 * Attempts to write up to @count bytes from @buffer to @stream, as
28396 * with g_output_stream_write(). If @stream is not currently writable,
28397 * this will immediately return %G_IO_ERROR_WOULD_BLOCK, and you can
28398 * use g_pollable_output_stream_create_source() to create a #GSource
28399 * that will be triggered when @stream is writable.
28401 * Note that since this method never blocks, you cannot actually
28402 * use @cancellable to cancel it. However, it will return an error
28403 * if @cancellable has already been cancelled when you call, which
28404 * may happen if you call this method after a source triggers due
28405 * to having been cancelled.
28407 * Returns: the number of bytes written, or -1 on error (including
28408 * %G_IO_ERROR_WOULD_BLOCK).
28413 * g_pollable_source_new:
28414 * @pollable_stream: the stream associated with the new source
28416 * Utility method for #GPollableInputStream and #GPollableOutputStream
28417 * implementations. Creates a new #GSource that expects a callback of
28418 * type #GPollableSourceFunc. The new source does not actually do
28419 * anything on its own; use g_source_add_child_source() to add other
28420 * sources to it to cause it to trigger.
28422 * Returns: (transfer full): the new #GSource.
28428 * g_pollable_source_new_full:
28429 * @pollable_stream: (type GObject): the stream associated with the
28431 * @child_source: (allow-none): optional child source to attach
28432 * @cancellable: (allow-none): optional #GCancellable to attach
28434 * Utility method for #GPollableInputStream and #GPollableOutputStream
28435 * implementations. Creates a new #GSource, as with
28436 * g_pollable_source_new(), but also attaching @child_source (with a
28437 * dummy callback), and @cancellable, if they are non-%NULL.
28439 * Returns: (transfer full): the new #GSource.
28445 * g_pollable_stream_read:
28446 * @stream: a #GInputStream
28447 * @buffer: (array length=count) (element-type guint8): a buffer to
28449 * @count: the number of bytes to read
28450 * @blocking: whether to do blocking I/O
28451 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
28452 * @error: location to store the error occurring, or %NULL to ignore
28454 * Tries to read from @stream, as with g_input_stream_read() (if
28455 * @blocking is %TRUE) or g_pollable_input_stream_read_nonblocking()
28456 * (if @blocking is %FALSE). This can be used to more easily share
28457 * code between blocking and non-blocking implementations of a method.
28459 * If @blocking is %FALSE, then @stream must be a
28460 * #GPollableInputStream for which g_pollable_input_stream_can_poll()
28461 * returns %TRUE, or else the behavior is undefined. If @blocking is
28462 * %TRUE, then @stream does not need to be a #GPollableInputStream.
28464 * Returns: the number of bytes read, or -1 on error.
28470 * g_pollable_stream_write:
28471 * @stream: a #GOutputStream.
28472 * @buffer: (array length=count) (element-type guint8): the buffer
28473 * containing the data to write.
28474 * @count: the number of bytes to write
28475 * @blocking: whether to do blocking I/O
28476 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
28477 * @error: location to store the error occurring, or %NULL to ignore
28479 * Tries to write to @stream, as with g_output_stream_write() (if
28480 * @blocking is %TRUE) or g_pollable_output_stream_write_nonblocking()
28481 * (if @blocking is %FALSE). This can be used to more easily share
28482 * code between blocking and non-blocking implementations of a method.
28484 * If @blocking is %FALSE, then @stream must be a
28485 * #GPollableOutputStream for which
28486 * g_pollable_output_stream_can_poll() returns %TRUE or else the
28487 * behavior is undefined. If @blocking is %TRUE, then @stream does not
28488 * need to be a #GPollableOutputStream.
28490 * Returns: the number of bytes written, or -1 on error.
28496 * g_pollable_stream_write_all:
28497 * @stream: a #GOutputStream.
28498 * @buffer: (array length=count) (element-type guint8): the buffer
28499 * containing the data to write.
28500 * @count: the number of bytes to write
28501 * @blocking: whether to do blocking I/O
28502 * @bytes_written: (out): location to store the number of bytes that was
28503 * written to the stream
28504 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
28505 * @error: location to store the error occurring, or %NULL to ignore
28507 * Tries to write @count bytes to @stream, as with
28508 * g_output_stream_write_all(), but using g_pollable_stream_write()
28509 * rather than g_output_stream_write().
28511 * On a successful write of @count bytes, %TRUE is returned, and
28512 * @bytes_written is set to @count.
28514 * If there is an error during the operation (including
28515 * %G_IO_ERROR_WOULD_BLOCK in the non-blocking case), %FALSE is
28516 * returned and @error is set to indicate the error status,
28517 * @bytes_written is updated to contain the number of bytes written
28518 * into the stream before the error occurred.
28520 * As with g_pollable_stream_write(), if @blocking is %FALSE, then
28521 * @stream must be a #GPollableOutputStream for which
28522 * g_pollable_output_stream_can_poll() returns %TRUE or else the
28523 * behavior is undefined. If @blocking is %TRUE, then @stream does not
28524 * need to be a #GPollableOutputStream.
28526 * Returns: %TRUE on success, %FALSE if there was an error
28532 * g_property_action_new:
28533 * @name: the name of the action to create
28534 * @object: the object that has the property to wrap
28535 * @property_name: the name of the property
28537 * Creates a #GAction corresponding to the value of property
28538 * @property_name on @object.
28540 * The property must be existent and readable and writable (and not
28543 * This function takes a reference on @object and doesn't release it
28544 * until the action is destroyed.
28546 * Returns: a new #GPropertyAction
28552 * g_proxy_address_get_destination_hostname:
28553 * @proxy: a #GProxyAddress
28555 * Gets @proxy's destination hostname; that is, the name of the host
28556 * that will be connected to via the proxy, not the name of the proxy
28559 * Returns: the @proxy's destination hostname
28565 * g_proxy_address_get_destination_port:
28566 * @proxy: a #GProxyAddress
28568 * Gets @proxy's destination port; that is, the port on the
28569 * destination host that will be connected to via the proxy, not the
28570 * port number of the proxy itself.
28572 * Returns: the @proxy's destination port
28578 * g_proxy_address_get_destination_protocol:
28579 * @proxy: a #GProxyAddress
28581 * Gets the protocol that is being spoken to the destination
28582 * server; eg, "http" or "ftp".
28584 * Returns: the @proxy's destination protocol
28590 * g_proxy_address_get_password:
28591 * @proxy: a #GProxyAddress
28593 * Gets @proxy's password.
28595 * Returns: the @proxy's password
28601 * g_proxy_address_get_protocol:
28602 * @proxy: a #GProxyAddress
28604 * Gets @proxy's protocol. eg, "socks" or "http"
28606 * Returns: the @proxy's protocol
28612 * g_proxy_address_get_uri:
28613 * @proxy: a #GProxyAddress
28615 * Gets the proxy URI that @proxy was constructed from.
28617 * Returns: the @proxy's URI, or %NULL if unknown
28623 * g_proxy_address_get_username:
28624 * @proxy: a #GProxyAddress
28626 * Gets @proxy's username.
28628 * Returns: the @proxy's username
28634 * g_proxy_address_new:
28635 * @inetaddr: The proxy server #GInetAddress.
28636 * @port: The proxy server port.
28637 * @protocol: The proxy protocol to support, in lower case (e.g. socks, http).
28638 * @dest_hostname: The destination hostname the proxy should tunnel to.
28639 * @dest_port: The destination port to tunnel to.
28640 * @username: (allow-none): The username to authenticate to the proxy server
28642 * @password: (allow-none): The password to authenticate to the proxy server
28645 * Creates a new #GProxyAddress for @inetaddr with @protocol that should
28646 * tunnel through @dest_hostname and @dest_port.
28648 * (Note that this method doesn't set the #GProxyAddress:uri or
28649 * #GProxyAddress:destination-protocol fields; use g_object_new()
28650 * directly if you want to set those.)
28652 * Returns: a new #GProxyAddress
28659 * @proxy: a #GProxy
28660 * @connection: a #GIOStream
28661 * @proxy_address: a #GProxyAddress
28662 * @cancellable: (allow-none): a #GCancellable
28663 * @error: return #GError
28665 * Given @connection to communicate with a proxy (eg, a
28666 * #GSocketConnection that is connected to the proxy server), this
28667 * does the necessary handshake to connect to @proxy_address, and if
28668 * required, wraps the #GIOStream to handle proxy payload.
28670 * Returns: (transfer full): a #GIOStream that will replace @connection. This might
28671 * be the same as @connection, in which case a reference
28678 * g_proxy_connect_async:
28679 * @proxy: a #GProxy
28680 * @connection: a #GIOStream
28681 * @proxy_address: a #GProxyAddress
28682 * @cancellable: (allow-none): a #GCancellable
28683 * @callback: (scope async): a #GAsyncReadyCallback
28684 * @user_data: (closure): callback data
28686 * Asynchronous version of g_proxy_connect().
28693 * g_proxy_connect_finish:
28694 * @proxy: a #GProxy
28695 * @result: a #GAsyncResult
28696 * @error: return #GError
28698 * See g_proxy_connect().
28700 * Returns: (transfer full): a #GIOStream.
28706 * g_proxy_get_default_for_protocol:
28707 * @protocol: the proxy protocol name (e.g. http, socks, etc)
28709 * Lookup "gio-proxy" extension point for a proxy implementation that supports
28710 * specified protocol.
28712 * Returns: (transfer full): return a #GProxy or NULL if protocol
28713 * is not supported.
28719 * g_proxy_resolver_get_default:
28721 * Gets the default #GProxyResolver for the system.
28723 * Returns: (transfer none): the default #GProxyResolver.
28729 * g_proxy_resolver_is_supported:
28730 * @resolver: a #GProxyResolver
28732 * Checks if @resolver can be used on this system. (This is used
28733 * internally; g_proxy_resolver_get_default() will only return a proxy
28734 * resolver that returns %TRUE for this method.)
28736 * Returns: %TRUE if @resolver is supported.
28742 * g_proxy_resolver_lookup:
28743 * @resolver: a #GProxyResolver
28744 * @uri: a URI representing the destination to connect to
28745 * @cancellable: (allow-none): a #GCancellable, or %NULL
28746 * @error: return location for a #GError, or %NULL
28748 * Looks into the system proxy configuration to determine what proxy,
28749 * if any, to use to connect to @uri. The returned proxy URIs are of
28750 * the form `<protocol>://[user[:password]@]host:port` or
28751 * `direct://`, where <protocol> could be http, rtsp, socks
28752 * or other proxying protocol.
28754 * If you don't know what network protocol is being used on the
28755 * socket, you should use `none` as the URI protocol.
28756 * In this case, the resolver might still return a generic proxy type
28757 * (such as SOCKS), but would not return protocol-specific proxy types
28760 * `direct://` is used when no proxy is needed.
28761 * Direct connection should not be attempted unless it is part of the
28762 * returned array of proxies.
28764 * Returns: (transfer full) (array zero-terminated=1): A
28765 * NULL-terminated array of proxy URIs. Must be freed
28766 * with g_strfreev().
28772 * g_proxy_resolver_lookup_async:
28773 * @resolver: a #GProxyResolver
28774 * @uri: a URI representing the destination to connect to
28775 * @cancellable: (allow-none): a #GCancellable, or %NULL
28776 * @callback: (scope async): callback to call after resolution completes
28777 * @user_data: (closure): data for @callback
28779 * Asynchronous lookup of proxy. See g_proxy_resolver_lookup() for more
28787 * g_proxy_resolver_lookup_finish:
28788 * @resolver: a #GProxyResolver
28789 * @result: the result passed to your #GAsyncReadyCallback
28790 * @error: return location for a #GError, or %NULL
28792 * Call this function to obtain the array of proxy URIs when
28793 * g_proxy_resolver_lookup_async() is complete. See
28794 * g_proxy_resolver_lookup() for more details.
28796 * Returns: (transfer full) (array zero-terminated=1): A
28797 * NULL-terminated array of proxy URIs. Must be freed
28798 * with g_strfreev().
28804 * g_proxy_supports_hostname:
28805 * @proxy: a #GProxy
28807 * Some proxy protocols expect to be passed a hostname, which they
28808 * will resolve to an IP address themselves. Others, like SOCKS4, do
28809 * not allow this. This function will return %FALSE if @proxy is
28810 * implementing such a protocol. When %FALSE is returned, the caller
28811 * should resolve the destination hostname first, and then pass a
28812 * #GProxyAddress containing the stringified IP address to
28813 * g_proxy_connect() or g_proxy_connect_async().
28815 * Returns: %TRUE if hostname resolution is supported.
28821 * g_remote_action_group_activate_action_full:
28822 * @remote: a #GDBusActionGroup
28823 * @action_name: the name of the action to activate
28824 * @parameter: (allow-none): the optional parameter to the activation
28825 * @platform_data: the platform data to send
28827 * Activates the remote action.
28829 * This is the same as g_action_group_activate_action() except that it
28830 * allows for provision of "platform data" to be sent along with the
28831 * activation request. This typically contains details such as the user
28832 * interaction timestamp or startup notification information.
28834 * @platform_data must be non-%NULL and must have the type
28835 * %G_VARIANT_TYPE_VARDICT. If it is floating, it will be consumed.
28842 * g_remote_action_group_change_action_state_full:
28843 * @remote: a #GRemoteActionGroup
28844 * @action_name: the name of the action to change the state of
28845 * @value: the new requested value for the state
28846 * @platform_data: the platform data to send
28848 * Changes the state of a remote action.
28850 * This is the same as g_action_group_change_action_state() except that
28851 * it allows for provision of "platform data" to be sent along with the
28852 * state change request. This typically contains details such as the
28853 * user interaction timestamp or startup notification information.
28855 * @platform_data must be non-%NULL and must have the type
28856 * %G_VARIANT_TYPE_VARDICT. If it is floating, it will be consumed.
28863 * g_resolver_error_quark:
28865 * Gets the #GResolver Error Quark.
28867 * Returns: a #GQuark.
28873 * g_resolver_free_addresses: (skip)
28874 * @addresses: a #GList of #GInetAddress
28876 * Frees @addresses (which should be the return value from
28877 * g_resolver_lookup_by_name() or g_resolver_lookup_by_name_finish()).
28878 * (This is a convenience method; you can also simply free the results
28886 * g_resolver_free_targets: (skip)
28887 * @targets: a #GList of #GSrvTarget
28889 * Frees @targets (which should be the return value from
28890 * g_resolver_lookup_service() or g_resolver_lookup_service_finish()).
28891 * (This is a convenience method; you can also simply free the
28892 * results by hand.)
28899 * g_resolver_get_default:
28901 * Gets the default #GResolver. You should unref it when you are done
28902 * with it. #GResolver may use its reference count as a hint about how
28903 * many threads it should allocate for concurrent DNS resolutions.
28905 * Returns: (transfer full): the default #GResolver.
28911 * g_resolver_lookup_by_address:
28912 * @resolver: a #GResolver
28913 * @address: the address to reverse-resolve
28914 * @cancellable: (allow-none): a #GCancellable, or %NULL
28915 * @error: return location for a #GError, or %NULL
28917 * Synchronously reverse-resolves @address to determine its
28918 * associated hostname.
28920 * If the DNS resolution fails, @error (if non-%NULL) will be set to
28921 * a value from #GResolverError.
28923 * If @cancellable is non-%NULL, it can be used to cancel the
28924 * operation, in which case @error (if non-%NULL) will be set to
28925 * %G_IO_ERROR_CANCELLED.
28927 * Returns: a hostname (either ASCII-only, or in ASCII-encoded
28928 * form), or %NULL on error.
28934 * g_resolver_lookup_by_address_async:
28935 * @resolver: a #GResolver
28936 * @address: the address to reverse-resolve
28937 * @cancellable: (allow-none): a #GCancellable, or %NULL
28938 * @callback: (scope async): callback to call after resolution completes
28939 * @user_data: (closure): data for @callback
28941 * Begins asynchronously reverse-resolving @address to determine its
28942 * associated hostname, and eventually calls @callback, which must
28943 * call g_resolver_lookup_by_address_finish() to get the final result.
28950 * g_resolver_lookup_by_address_finish:
28951 * @resolver: a #GResolver
28952 * @result: the result passed to your #GAsyncReadyCallback
28953 * @error: return location for a #GError, or %NULL
28955 * Retrieves the result of a previous call to
28956 * g_resolver_lookup_by_address_async().
28958 * If the DNS resolution failed, @error (if non-%NULL) will be set to
28959 * a value from #GResolverError. If the operation was cancelled,
28960 * @error will be set to %G_IO_ERROR_CANCELLED.
28962 * Returns: a hostname (either ASCII-only, or in ASCII-encoded
28963 * form), or %NULL on error.
28969 * g_resolver_lookup_by_name:
28970 * @resolver: a #GResolver
28971 * @hostname: the hostname to look up
28972 * @cancellable: (allow-none): a #GCancellable, or %NULL
28973 * @error: return location for a #GError, or %NULL
28975 * Synchronously resolves @hostname to determine its associated IP
28976 * address(es). @hostname may be an ASCII-only or UTF-8 hostname, or
28977 * the textual form of an IP address (in which case this just becomes
28978 * a wrapper around g_inet_address_new_from_string()).
28980 * On success, g_resolver_lookup_by_name() will return a non-empty #GList of
28981 * #GInetAddress, sorted in order of preference and guaranteed to not
28982 * contain duplicates. That is, if using the result to connect to
28983 * @hostname, you should attempt to connect to the first address
28984 * first, then the second if the first fails, etc. If you are using
28985 * the result to listen on a socket, it is appropriate to add each
28986 * result using e.g. g_socket_listener_add_address().
28988 * If the DNS resolution fails, @error (if non-%NULL) will be set to a
28989 * value from #GResolverError and %NULL will be returned.
28991 * If @cancellable is non-%NULL, it can be used to cancel the
28992 * operation, in which case @error (if non-%NULL) will be set to
28993 * %G_IO_ERROR_CANCELLED.
28995 * If you are planning to connect to a socket on the resolved IP
28996 * address, it may be easier to create a #GNetworkAddress and use its
28997 * #GSocketConnectable interface.
28999 * Returns: (element-type GInetAddress) (transfer full): a non-empty #GList
29000 * of #GInetAddress, or %NULL on error. You
29001 * must unref each of the addresses and free the list when you are
29002 * done with it. (You can use g_resolver_free_addresses() to do this.)
29008 * g_resolver_lookup_by_name_async:
29009 * @resolver: a #GResolver
29010 * @hostname: the hostname to look up the address of
29011 * @cancellable: (allow-none): a #GCancellable, or %NULL
29012 * @callback: (scope async): callback to call after resolution completes
29013 * @user_data: (closure): data for @callback
29015 * Begins asynchronously resolving @hostname to determine its
29016 * associated IP address(es), and eventually calls @callback, which
29017 * must call g_resolver_lookup_by_name_finish() to get the result.
29018 * See g_resolver_lookup_by_name() for more details.
29025 * g_resolver_lookup_by_name_finish:
29026 * @resolver: a #GResolver
29027 * @result: the result passed to your #GAsyncReadyCallback
29028 * @error: return location for a #GError, or %NULL
29030 * Retrieves the result of a call to
29031 * g_resolver_lookup_by_name_async().
29033 * If the DNS resolution failed, @error (if non-%NULL) will be set to
29034 * a value from #GResolverError. If the operation was cancelled,
29035 * @error will be set to %G_IO_ERROR_CANCELLED.
29037 * Returns: (element-type GInetAddress) (transfer full): a #GList
29038 * of #GInetAddress, or %NULL on error. See g_resolver_lookup_by_name()
29039 * for more details.
29045 * g_resolver_lookup_records:
29046 * @resolver: a #GResolver
29047 * @rrname: the DNS name to lookup the record for
29048 * @record_type: the type of DNS record to lookup
29049 * @cancellable: (allow-none): a #GCancellable, or %NULL
29050 * @error: return location for a #GError, or %NULL
29052 * Synchronously performs a DNS record lookup for the given @rrname and returns
29053 * a list of records as #GVariant tuples. See #GResolverRecordType for
29054 * information on what the records contain for each @record_type.
29056 * If the DNS resolution fails, @error (if non-%NULL) will be set to
29057 * a value from #GResolverError and %NULL will be returned.
29059 * If @cancellable is non-%NULL, it can be used to cancel the
29060 * operation, in which case @error (if non-%NULL) will be set to
29061 * %G_IO_ERROR_CANCELLED.
29063 * Returns: (element-type GVariant) (transfer full): a non-empty #GList of
29064 * #GVariant, or %NULL on error. You must free each of the records and the list
29065 * when you are done with it. (You can use g_list_free_full() with
29066 * g_variant_unref() to do this.)
29072 * g_resolver_lookup_records_async:
29073 * @resolver: a #GResolver
29074 * @rrname: the DNS name to lookup the record for
29075 * @record_type: the type of DNS record to lookup
29076 * @cancellable: (allow-none): a #GCancellable, or %NULL
29077 * @callback: (scope async): callback to call after resolution completes
29078 * @user_data: (closure): data for @callback
29080 * Begins asynchronously performing a DNS lookup for the given
29081 * @rrname, and eventually calls @callback, which must call
29082 * g_resolver_lookup_records_finish() to get the final result. See
29083 * g_resolver_lookup_records() for more details.
29090 * g_resolver_lookup_records_finish:
29091 * @resolver: a #GResolver
29092 * @result: the result passed to your #GAsyncReadyCallback
29093 * @error: return location for a #GError, or %NULL
29095 * Retrieves the result of a previous call to
29096 * g_resolver_lookup_records_async(). Returns a non-empty list of records as
29097 * #GVariant tuples. See #GResolverRecordType for information on what the
29100 * If the DNS resolution failed, @error (if non-%NULL) will be set to
29101 * a value from #GResolverError. If the operation was cancelled,
29102 * @error will be set to %G_IO_ERROR_CANCELLED.
29104 * Returns: (element-type GVariant) (transfer full): a non-empty #GList of
29105 * #GVariant, or %NULL on error. You must free each of the records and the list
29106 * when you are done with it. (You can use g_list_free_full() with
29107 * g_variant_unref() to do this.)
29113 * g_resolver_lookup_service:
29114 * @resolver: a #GResolver
29115 * @service: the service type to look up (eg, "ldap")
29116 * @protocol: the networking protocol to use for @service (eg, "tcp")
29117 * @domain: the DNS domain to look up the service in
29118 * @cancellable: (allow-none): a #GCancellable, or %NULL
29119 * @error: return location for a #GError, or %NULL
29121 * Synchronously performs a DNS SRV lookup for the given @service and
29122 * @protocol in the given @domain and returns an array of #GSrvTarget.
29123 * @domain may be an ASCII-only or UTF-8 hostname. Note also that the
29124 * @service and @protocol arguments do not include the leading underscore
29125 * that appears in the actual DNS entry.
29127 * On success, g_resolver_lookup_service() will return a non-empty #GList of
29128 * #GSrvTarget, sorted in order of preference. (That is, you should
29129 * attempt to connect to the first target first, then the second if
29130 * the first fails, etc.)
29132 * If the DNS resolution fails, @error (if non-%NULL) will be set to
29133 * a value from #GResolverError and %NULL will be returned.
29135 * If @cancellable is non-%NULL, it can be used to cancel the
29136 * operation, in which case @error (if non-%NULL) will be set to
29137 * %G_IO_ERROR_CANCELLED.
29139 * If you are planning to connect to the service, it is usually easier
29140 * to create a #GNetworkService and use its #GSocketConnectable
29143 * Returns: (element-type GSrvTarget) (transfer full): a non-empty #GList of
29144 * #GSrvTarget, or %NULL on error. You must free each of the targets and the
29145 * list when you are done with it. (You can use g_resolver_free_targets() to do
29152 * g_resolver_lookup_service_async:
29153 * @resolver: a #GResolver
29154 * @service: the service type to look up (eg, "ldap")
29155 * @protocol: the networking protocol to use for @service (eg, "tcp")
29156 * @domain: the DNS domain to look up the service in
29157 * @cancellable: (allow-none): a #GCancellable, or %NULL
29158 * @callback: (scope async): callback to call after resolution completes
29159 * @user_data: (closure): data for @callback
29161 * Begins asynchronously performing a DNS SRV lookup for the given
29162 * @service and @protocol in the given @domain, and eventually calls
29163 * @callback, which must call g_resolver_lookup_service_finish() to
29164 * get the final result. See g_resolver_lookup_service() for more
29172 * g_resolver_lookup_service_finish:
29173 * @resolver: a #GResolver
29174 * @result: the result passed to your #GAsyncReadyCallback
29175 * @error: return location for a #GError, or %NULL
29177 * Retrieves the result of a previous call to
29178 * g_resolver_lookup_service_async().
29180 * If the DNS resolution failed, @error (if non-%NULL) will be set to
29181 * a value from #GResolverError. If the operation was cancelled,
29182 * @error will be set to %G_IO_ERROR_CANCELLED.
29184 * Returns: (element-type GSrvTarget) (transfer full): a non-empty #GList of
29185 * #GSrvTarget, or %NULL on error. See g_resolver_lookup_service() for more
29192 * g_resolver_set_default:
29193 * @resolver: the new default #GResolver
29195 * Sets @resolver to be the application's default resolver (reffing
29196 * @resolver, and unreffing the previous default resolver, if any).
29197 * Future calls to g_resolver_get_default() will return this resolver.
29199 * This can be used if an application wants to perform any sort of DNS
29200 * caching or "pinning"; it can implement its own #GResolver that
29201 * calls the original default resolver for DNS operations, and
29202 * implements its own cache policies on top of that, and then set
29203 * itself as the default resolver for all later code to use.
29210 * g_resource_enumerate_children:
29211 * @resource: A #GResource
29212 * @path: A pathname inside the resource
29213 * @lookup_flags: A #GResourceLookupFlags
29214 * @error: return location for a #GError, or %NULL
29216 * Returns all the names of children at the specified @path in the resource.
29217 * The return result is a %NULL terminated list of strings which should
29218 * be released with g_strfreev().
29220 * @lookup_flags controls the behaviour of the lookup.
29222 * Returns: (array zero-terminated=1) (transfer full): an array of constant strings
29228 * g_resource_error_quark:
29230 * Gets the #GResource Error Quark.
29232 * Returns: a #GQuark
29238 * g_resource_get_info:
29239 * @resource: A #GResource
29240 * @path: A pathname inside the resource
29241 * @lookup_flags: A #GResourceLookupFlags
29242 * @size: (out) (allow-none): a location to place the length of the contents of the file,
29243 * or %NULL if the length is not needed
29244 * @flags: (out) (allow-none): a location to place the flags about the file,
29245 * or %NULL if the length is not needed
29246 * @error: return location for a #GError, or %NULL
29248 * Looks for a file at the specified @path in the resource and
29249 * if found returns information about it.
29251 * @lookup_flags controls the behaviour of the lookup.
29253 * Returns: %TRUE if the file was found. %FALSE if there were errors
29260 * @filename: (type filename): the path of a filename to load, in the GLib filename encoding
29261 * @error: return location for a #GError, or %NULL
29263 * Loads a binary resource bundle and creates a #GResource representation of it, allowing
29264 * you to query it for data.
29266 * If you want to use this resource in the global resource namespace you need
29267 * to register it with g_resources_register().
29269 * Returns: (transfer full): a new #GResource, or %NULL on error
29275 * g_resource_lookup_data:
29276 * @resource: A #GResource
29277 * @path: A pathname inside the resource
29278 * @lookup_flags: A #GResourceLookupFlags
29279 * @error: return location for a #GError, or %NULL
29281 * Looks for a file at the specified @path in the resource and
29282 * returns a #GBytes that lets you directly access the data in
29285 * The data is always followed by a zero byte, so you
29286 * can safely use the data as a C string. However, that byte
29287 * is not included in the size of the GBytes.
29289 * For uncompressed resource files this is a pointer directly into
29290 * the resource bundle, which is typically in some readonly data section
29291 * in the program binary. For compressed files we allocate memory on
29292 * the heap and automatically uncompress the data.
29294 * @lookup_flags controls the behaviour of the lookup.
29296 * Returns: (transfer full): #GBytes or %NULL on error.
29297 * Free the returned object with g_bytes_unref()
29303 * g_resource_new_from_data:
29305 * @error: return location for a #GError, or %NULL
29307 * Creates a GResource from a reference to the binary resource bundle.
29308 * This will keep a reference to @data while the resource lives, so
29309 * the data should not be modified or freed.
29311 * If you want to use this resource in the global resource namespace you need
29312 * to register it with g_resources_register().
29314 * Returns: (transfer full): a new #GResource, or %NULL on error
29320 * g_resource_new_from_table:
29321 * @table: (transfer full): a GvdbTable
29323 * Returns: (transfer full): a new #GResource for @table
29328 * g_resource_open_stream:
29329 * @resource: A #GResource
29330 * @path: A pathname inside the resource
29331 * @lookup_flags: A #GResourceLookupFlags
29332 * @error: return location for a #GError, or %NULL
29334 * Looks for a file at the specified @path in the resource and
29335 * returns a #GInputStream that lets you read the data.
29337 * @lookup_flags controls the behaviour of the lookup.
29339 * Returns: (transfer full): #GInputStream or %NULL on error.
29340 * Free the returned object with g_object_unref()
29347 * @resource: A #GResource
29349 * Atomically increments the reference count of @array by one. This
29350 * function is MT-safe and may be called from any thread.
29352 * Returns: The passed in #GResource
29358 * g_resource_unref:
29359 * @resource: A #GResource
29361 * Atomically decrements the reference count of @resource by one. If the
29362 * reference count drops to 0, all memory allocated by the array is
29363 * released. This function is MT-safe and may be called from any
29371 * g_resources_enumerate_children:
29372 * @path: A pathname inside the resource
29373 * @lookup_flags: A #GResourceLookupFlags
29374 * @error: return location for a #GError, or %NULL
29376 * Returns all the names of children at the specified @path in the set of
29377 * globally registered resources.
29378 * The return result is a %NULL terminated list of strings which should
29379 * be released with g_strfreev().
29381 * @lookup_flags controls the behaviour of the lookup.
29383 * Returns: (array zero-terminated=1) (transfer full): an array of constant strings
29389 * g_resources_get_info:
29390 * @path: A pathname inside the resource
29391 * @lookup_flags: A #GResourceLookupFlags
29392 * @size: (out) (allow-none): a location to place the length of the contents of the file,
29393 * or %NULL if the length is not needed
29394 * @flags: (out) (allow-none): a location to place the flags about the file,
29395 * or %NULL if the length is not needed
29396 * @error: return location for a #GError, or %NULL
29398 * Looks for a file at the specified @path in the set of
29399 * globally registered resources and if found returns information about it.
29401 * @lookup_flags controls the behaviour of the lookup.
29403 * Returns: %TRUE if the file was found. %FALSE if there were errors
29409 * g_resources_lookup_data:
29410 * @path: A pathname inside the resource
29411 * @lookup_flags: A #GResourceLookupFlags
29412 * @error: return location for a #GError, or %NULL
29414 * Looks for a file at the specified @path in the set of
29415 * globally registered resources and returns a #GBytes that
29416 * lets you directly access the data in memory.
29418 * The data is always followed by a zero byte, so you
29419 * can safely use the data as a C string. However, that byte
29420 * is not included in the size of the GBytes.
29422 * For uncompressed resource files this is a pointer directly into
29423 * the resource bundle, which is typically in some readonly data section
29424 * in the program binary. For compressed files we allocate memory on
29425 * the heap and automatically uncompress the data.
29427 * @lookup_flags controls the behaviour of the lookup.
29429 * Returns: (transfer full): #GBytes or %NULL on error.
29430 * Free the returned object with g_bytes_unref()
29436 * g_resources_open_stream:
29437 * @path: A pathname inside the resource
29438 * @lookup_flags: A #GResourceLookupFlags
29439 * @error: return location for a #GError, or %NULL
29441 * Looks for a file at the specified @path in the set of
29442 * globally registered resources and returns a #GInputStream
29443 * that lets you read the data.
29445 * @lookup_flags controls the behaviour of the lookup.
29447 * Returns: (transfer full): #GInputStream or %NULL on error.
29448 * Free the returned object with g_object_unref()
29454 * g_resources_register:
29455 * @resource: A #GResource
29457 * Registers the resource with the process-global set of resources.
29458 * Once a resource is registered the files in it can be accessed
29459 * with the global resource lookup functions like g_resources_lookup_data().
29466 * g_resources_unregister:
29467 * @resource: A #GResource
29469 * Unregisters the resource from the process-global set of resources.
29476 * g_seekable_can_seek:
29477 * @seekable: a #GSeekable.
29479 * Tests if the stream supports the #GSeekableIface.
29481 * Returns: %TRUE if @seekable can be seeked. %FALSE otherwise.
29486 * g_seekable_can_truncate:
29487 * @seekable: a #GSeekable.
29489 * Tests if the stream can be truncated.
29491 * Returns: %TRUE if the stream can be truncated, %FALSE otherwise.
29497 * @seekable: a #GSeekable.
29498 * @offset: a #goffset.
29499 * @type: a #GSeekType.
29500 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
29501 * @error: a #GError location to store the error occurring, or %NULL to
29504 * Seeks in the stream by the given @offset, modified by @type.
29506 * Attempting to seek past the end of the stream will have different
29507 * results depending on if the stream is fixed-sized or resizable. If
29508 * the stream is resizable then seeking past the end and then writing
29509 * will result in zeros filling the empty space. Seeking past the end
29510 * of a resizable stream and reading will result in EOF. Seeking past
29511 * the end of a fixed-sized stream will fail.
29513 * Any operation that would result in a negative offset will fail.
29515 * If @cancellable is not %NULL, then the operation can be cancelled by
29516 * triggering the cancellable object from another thread. If the operation
29517 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
29519 * Returns: %TRUE if successful. If an error
29520 * has occurred, this function will return %FALSE and set @error
29521 * appropriately if present.
29527 * @seekable: a #GSeekable.
29529 * Tells the current position within the stream.
29531 * Returns: the offset from the beginning of the buffer.
29536 * g_seekable_truncate: (virtual truncate_fn)
29537 * @seekable: a #GSeekable.
29538 * @offset: a #goffset.
29539 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
29540 * @error: a #GError location to store the error occurring, or %NULL to
29543 * Truncates a stream with a given #offset.
29545 * If @cancellable is not %NULL, then the operation can be cancelled by
29546 * triggering the cancellable object from another thread. If the operation
29547 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
29548 * operation was partially finished when the operation was cancelled the
29549 * partial result will be returned, without an error.
29551 * Returns: %TRUE if successful. If an error
29552 * has occurred, this function will return %FALSE and set @error
29553 * appropriately if present.
29558 * g_settings_apply:
29559 * @settings: a #GSettings instance
29561 * Applies any changes that have been made to the settings. This
29562 * function does nothing unless @settings is in 'delay-apply' mode;
29563 * see g_settings_delay(). In the normal case settings are always
29564 * applied immediately.
29569 * g_settings_backend_changed:
29570 * @backend: a #GSettingsBackend implementation
29571 * @key: the name of the key
29572 * @origin_tag: the origin tag
29574 * Signals that a single key has possibly changed. Backend
29575 * implementations should call this if a key has possibly changed its
29578 * @key must be a valid key (ie starting with a slash, not containing
29579 * '//', and not ending with a slash).
29581 * The implementation must call this function during any call to
29582 * g_settings_backend_write(), before the call returns (except in the
29583 * case that no keys are actually changed and it cares to detect this
29584 * fact). It may not rely on the existence of a mainloop for
29585 * dispatching the signal later.
29587 * The implementation may call this function at any other time it likes
29588 * in response to other events (such as changes occurring outside of the
29589 * program). These calls may originate from a mainloop or may originate
29590 * in response to any other action (including from calls to
29591 * g_settings_backend_write()).
29593 * In the case that this call is in response to a call to
29594 * g_settings_backend_write() then @origin_tag must be set to the same
29595 * value that was passed to that call.
29602 * g_settings_backend_changed_tree:
29603 * @backend: a #GSettingsBackend implementation
29604 * @tree: a #GTree containing the changes
29605 * @origin_tag: the origin tag
29607 * This call is a convenience wrapper. It gets the list of changes from
29608 * @tree, computes the longest common prefix and calls
29609 * g_settings_backend_changed().
29616 * g_settings_backend_flatten_tree:
29617 * @tree: a #GTree containing the changes
29618 * @path: (out): the location to save the path
29619 * @keys: (out) (transfer container) (array zero-terminated=1): the
29620 * location to save the relative keys
29621 * @values: (out) (allow-none) (transfer container) (array zero-terminated=1):
29622 * the location to save the values, or %NULL
29624 * Calculate the longest common prefix of all keys in a tree and write
29625 * out an array of the key names relative to that prefix and,
29626 * optionally, the value to store at each of those keys.
29628 * You must free the value returned in @path, @keys and @values using
29629 * g_free(). You should not attempt to free or unref the contents of
29630 * @keys or @values.
29637 * g_settings_backend_get_default:
29639 * Returns the default #GSettingsBackend. It is possible to override
29640 * the default by setting the `GSETTINGS_BACKEND` environment variable
29641 * to the name of a settings backend.
29643 * The user gets a reference to the backend.
29645 * Returns: (transfer full): the default #GSettingsBackend
29651 * g_settings_backend_keys_changed:
29652 * @backend: a #GSettingsBackend implementation
29653 * @path: the path containing the changes
29654 * @items: (array zero-terminated=1): the %NULL-terminated list of changed keys
29655 * @origin_tag: the origin tag
29657 * Signals that a list of keys have possibly changed. Backend
29658 * implementations should call this if keys have possibly changed their
29661 * @path must be a valid path (ie starting and ending with a slash and
29662 * not containing '//'). Each string in @items must form a valid key
29663 * name when @path is prefixed to it (ie: each item must not start or
29664 * end with '/' and must not contain '//').
29666 * The meaning of this signal is that any of the key names resulting
29667 * from the contatenation of @path with each item in @items may have
29670 * The same rules for when notifications must occur apply as per
29671 * g_settings_backend_changed(). These two calls can be used
29672 * interchangeably if exactly one item has changed (although in that
29673 * case g_settings_backend_changed() is definitely preferred).
29675 * For efficiency reasons, the implementation should strive for @path to
29676 * be as long as possible (ie: the longest common prefix of all of the
29677 * keys that were changed) but this is not strictly required.
29684 * g_settings_backend_path_changed:
29685 * @backend: a #GSettingsBackend implementation
29686 * @path: the path containing the changes
29687 * @origin_tag: the origin tag
29689 * Signals that all keys below a given path may have possibly changed.
29690 * Backend implementations should call this if an entire path of keys
29691 * have possibly changed their values.
29693 * @path must be a valid path (ie starting and ending with a slash and
29694 * not containing '//').
29696 * The meaning of this signal is that any of the key which has a name
29697 * starting with @path may have changed.
29699 * The same rules for when notifications must occur apply as per
29700 * g_settings_backend_changed(). This call might be an appropriate
29701 * reasponse to a 'reset' call but implementations are also free to
29702 * explicitly list the keys that were affected by that call if they can
29705 * For efficiency reasons, the implementation should strive for @path to
29706 * be as long as possible (ie: the longest common prefix of all of the
29707 * keys that were changed) but this is not strictly required. As an
29708 * example, if this function is called with the path of "/" then every
29709 * single key in the application will be notified of a possible change.
29716 * g_settings_backend_path_writable_changed:
29717 * @backend: a #GSettingsBackend implementation
29718 * @path: the name of the path
29720 * Signals that the writability of all keys below a given path may have
29723 * Since GSettings performs no locking operations for itself, this call
29724 * will always be made in response to external events.
29731 * g_settings_backend_writable_changed:
29732 * @backend: a #GSettingsBackend implementation
29733 * @key: the name of the key
29735 * Signals that the writability of a single key has possibly changed.
29737 * Since GSettings performs no locking operations for itself, this call
29738 * will always be made in response to external events.
29746 * @settings: a #GSettings object
29747 * @key: the key to bind
29748 * @object: (type GObject.Object): a #GObject
29749 * @property: the name of the property to bind
29750 * @flags: flags for the binding
29752 * Create a binding between the @key in the @settings object
29753 * and the property @property of @object.
29755 * The binding uses the default GIO mapping functions to map
29756 * between the settings and property values. These functions
29757 * handle booleans, numeric types and string types in a
29758 * straightforward way. Use g_settings_bind_with_mapping() if
29759 * you need a custom mapping, or map between types that are not
29760 * supported by the default mapping functions.
29762 * Unless the @flags include %G_SETTINGS_BIND_NO_SENSITIVITY, this
29763 * function also establishes a binding between the writability of
29764 * @key and the "sensitive" property of @object (if @object has
29765 * a boolean property by that name). See g_settings_bind_writable()
29766 * for more details about writable bindings.
29768 * Note that the lifecycle of the binding is tied to the object,
29769 * and that you can have only one binding per object property.
29770 * If you bind the same property twice on the same object, the second
29771 * binding overrides the first one.
29778 * g_settings_bind_with_mapping: (skip)
29779 * @settings: a #GSettings object
29780 * @key: the key to bind
29781 * @object: (type GObject.Object): a #GObject
29782 * @property: the name of the property to bind
29783 * @flags: flags for the binding
29784 * @get_mapping: a function that gets called to convert values
29785 * from @settings to @object, or %NULL to use the default GIO mapping
29786 * @set_mapping: a function that gets called to convert values
29787 * from @object to @settings, or %NULL to use the default GIO mapping
29788 * @user_data: data that gets passed to @get_mapping and @set_mapping
29789 * @destroy: #GDestroyNotify function for @user_data
29791 * Create a binding between the @key in the @settings object
29792 * and the property @property of @object.
29794 * The binding uses the provided mapping functions to map between
29795 * settings and property values.
29797 * Note that the lifecycle of the binding is tied to the object,
29798 * and that you can have only one binding per object property.
29799 * If you bind the same property twice on the same object, the second
29800 * binding overrides the first one.
29807 * g_settings_bind_writable:
29808 * @settings: a #GSettings object
29809 * @key: the key to bind
29810 * @object: (type GObject.Object): a #GObject
29811 * @property: the name of a boolean property to bind
29812 * @inverted: whether to 'invert' the value
29814 * Create a binding between the writability of @key in the
29815 * @settings object and the property @property of @object.
29816 * The property must be boolean; "sensitive" or "visible"
29817 * properties of widgets are the most likely candidates.
29819 * Writable bindings are always uni-directional; changes of the
29820 * writability of the setting will be propagated to the object
29821 * property, not the other way.
29823 * When the @inverted argument is %TRUE, the binding inverts the
29824 * value as it passes from the setting to the object, i.e. @property
29825 * will be set to %TRUE if the key is not writable.
29827 * Note that the lifecycle of the binding is tied to the object,
29828 * and that you can have only one binding per object property.
29829 * If you bind the same property twice on the same object, the second
29830 * binding overrides the first one.
29837 * g_settings_create_action:
29838 * @settings: a #GSettings
29839 * @key: the name of a key in @settings
29841 * Creates a #GAction corresponding to a given #GSettings key.
29843 * The action has the same name as the key.
29845 * The value of the key becomes the state of the action and the action
29846 * is enabled when the key is writable. Changing the state of the
29847 * action results in the key being written to. Changes to the value or
29848 * writability of the key cause appropriate change notifications to be
29849 * emitted for the action.
29851 * For boolean-valued keys, action activations take no parameter and
29852 * result in the toggling of the value. For all other types,
29853 * activations take the new value for the key (which must have the
29856 * Returns: (transfer full): a new #GAction
29862 * g_settings_delay:
29863 * @settings: a #GSettings object
29865 * Changes the #GSettings object into 'delay-apply' mode. In this
29866 * mode, changes to @settings are not immediately propagated to the
29867 * backend, but kept locally until g_settings_apply() is called.
29875 * @settings: a #GSettings object
29876 * @key: the key to get the value for
29877 * @format: a #GVariant format string
29878 * @...: arguments as per @format
29880 * Gets the value that is stored at @key in @settings.
29882 * A convenience function that combines g_settings_get_value() with
29885 * It is a programmer error to give a @key that isn't contained in the
29886 * schema for @settings or for the #GVariantType of @format to mismatch
29887 * the type given in the schema.
29894 * g_settings_get_boolean:
29895 * @settings: a #GSettings object
29896 * @key: the key to get the value for
29898 * Gets the value that is stored at @key in @settings.
29900 * A convenience variant of g_settings_get() for booleans.
29902 * It is a programmer error to give a @key that isn't specified as
29903 * having a boolean type in the schema for @settings.
29905 * Returns: a boolean
29911 * g_settings_get_child:
29912 * @settings: a #GSettings object
29913 * @name: the name of the child schema
29915 * Creates a child settings object which has a base path of
29916 * `base-path/@name`, where `base-path` is the base path of
29919 * The schema for the child settings object must have been declared
29920 * in the schema of @settings using a <child> element.
29922 * Returns: (transfer full): a 'child' settings object
29928 * g_settings_get_default_value:
29929 * @settings: a #GSettings object
29930 * @key: the key to get the default value for
29932 * Gets the "default value" of a key.
29934 * This is the value that would be read if g_settings_reset() were to be
29935 * called on the key.
29937 * Note that this may be a different value than returned by
29938 * g_settings_schema_key_get_default_value() if the system administrator
29939 * has provided a default value.
29941 * Comparing the return values of g_settings_get_default_value() and
29942 * g_settings_get_value() is not sufficient for determining if a value
29943 * has been set because the user may have explicitly set the value to
29944 * something that happens to be equal to the default. The difference
29945 * here is that if the default changes in the future, the user's key
29946 * will still be set.
29948 * This function may be useful for adding an indication to a UI of what
29949 * the default value was before the user set it.
29951 * It is a programmer error to give a @key that isn't contained in the
29952 * schema for @settings.
29954 * Returns: (allow-none) (transfer full): the default value
29960 * g_settings_get_double:
29961 * @settings: a #GSettings object
29962 * @key: the key to get the value for
29964 * Gets the value that is stored at @key in @settings.
29966 * A convenience variant of g_settings_get() for doubles.
29968 * It is a programmer error to give a @key that isn't specified as
29969 * having a 'double' type in the schema for @settings.
29971 * Returns: a double
29977 * g_settings_get_enum:
29978 * @settings: a #GSettings object
29979 * @key: the key to get the value for
29981 * Gets the value that is stored in @settings for @key and converts it
29982 * to the enum value that it represents.
29984 * In order to use this function the type of the value must be a string
29985 * and it must be marked in the schema file as an enumerated type.
29987 * It is a programmer error to give a @key that isn't contained in the
29988 * schema for @settings or is not marked as an enumerated type.
29990 * If the value stored in the configuration database is not a valid
29991 * value for the enumerated type then this function will return the
29994 * Returns: the enum value
30000 * g_settings_get_flags:
30001 * @settings: a #GSettings object
30002 * @key: the key to get the value for
30004 * Gets the value that is stored in @settings for @key and converts it
30005 * to the flags value that it represents.
30007 * In order to use this function the type of the value must be an array
30008 * of strings and it must be marked in the schema file as an flags type.
30010 * It is a programmer error to give a @key that isn't contained in the
30011 * schema for @settings or is not marked as a flags type.
30013 * If the value stored in the configuration database is not a valid
30014 * value for the flags type then this function will return the default
30017 * Returns: the flags value
30023 * g_settings_get_has_unapplied:
30024 * @settings: a #GSettings object
30026 * Returns whether the #GSettings object has any unapplied
30027 * changes. This can only be the case if it is in 'delayed-apply' mode.
30029 * Returns: %TRUE if @settings has unapplied changes
30035 * g_settings_get_int:
30036 * @settings: a #GSettings object
30037 * @key: the key to get the value for
30039 * Gets the value that is stored at @key in @settings.
30041 * A convenience variant of g_settings_get() for 32-bit integers.
30043 * It is a programmer error to give a @key that isn't specified as
30044 * having a int32 type in the schema for @settings.
30046 * Returns: an integer
30052 * g_settings_get_mapped:
30053 * @settings: a #GSettings object
30054 * @key: the key to get the value for
30055 * @mapping: (scope call): the function to map the value in the
30056 * settings database to the value used by the application
30057 * @user_data: user data for @mapping
30059 * Gets the value that is stored at @key in @settings, subject to
30060 * application-level validation/mapping.
30062 * You should use this function when the application needs to perform
30063 * some processing on the value of the key (for example, parsing). The
30064 * @mapping function performs that processing. If the function
30065 * indicates that the processing was unsuccessful (due to a parse error,
30066 * for example) then the mapping is tried again with another value.
30068 * This allows a robust 'fall back to defaults' behaviour to be
30069 * implemented somewhat automatically.
30071 * The first value that is tried is the user's setting for the key. If
30072 * the mapping function fails to map this value, other values may be
30073 * tried in an unspecified order (system or site defaults, translated
30074 * schema default values, untranslated schema default values, etc).
30076 * If the mapping function fails for all possible values, one additional
30077 * attempt is made: the mapping function is called with a %NULL value.
30078 * If the mapping function still indicates failure at this point then
30079 * the application will be aborted.
30081 * The result parameter for the @mapping function is pointed to a
30082 * #gpointer which is initially set to %NULL. The same pointer is given
30083 * to each invocation of @mapping. The final value of that #gpointer is
30084 * what is returned by this function. %NULL is valid; it is returned
30085 * just as any other value would be.
30087 * Returns: (transfer full): the result, which may be %NULL
30092 * g_settings_get_range:
30093 * @settings: a #GSettings
30094 * @key: the key to query the range of
30096 * Queries the range of a key.
30099 * Deprecated: 2.40: Use g_settings_schema_key_get_range() instead.
30104 * g_settings_get_string:
30105 * @settings: a #GSettings object
30106 * @key: the key to get the value for
30108 * Gets the value that is stored at @key in @settings.
30110 * A convenience variant of g_settings_get() for strings.
30112 * It is a programmer error to give a @key that isn't specified as
30113 * having a string type in the schema for @settings.
30115 * Returns: a newly-allocated string
30121 * g_settings_get_strv:
30122 * @settings: a #GSettings object
30123 * @key: the key to get the value for
30125 * A convenience variant of g_settings_get() for string arrays.
30127 * It is a programmer error to give a @key that isn't specified as
30128 * having an array of strings type in the schema for @settings.
30130 * Returns: (array zero-terminated=1) (transfer full): a
30131 * newly-allocated, %NULL-terminated array of strings, the value that
30132 * is stored at @key in @settings.
30138 * g_settings_get_uint:
30139 * @settings: a #GSettings object
30140 * @key: the key to get the value for
30142 * Gets the value that is stored at @key in @settings.
30144 * A convenience variant of g_settings_get() for 32-bit unsigned
30147 * It is a programmer error to give a @key that isn't specified as
30148 * having a uint32 type in the schema for @settings.
30150 * Returns: an unsigned integer
30156 * g_settings_get_user_value:
30157 * @settings: a #GSettings object
30158 * @key: the key to get the user value for
30160 * Checks the "user value" of a key, if there is one.
30162 * The user value of a key is the last value that was set by the user.
30164 * After calling g_settings_reset() this function should always return
30165 * %NULL (assuming something is not wrong with the system
30168 * It is possible that g_settings_get_value() will return a different
30169 * value than this function. This can happen in the case that the user
30170 * set a value for a key that was subsequently locked down by the system
30171 * administrator -- this function will return the user's old value.
30173 * This function may be useful for adding a "reset" option to a UI or
30174 * for providing indication that a particular value has been changed.
30176 * It is a programmer error to give a @key that isn't contained in the
30177 * schema for @settings.
30179 * Returns: (allow-none) (transfer full): the user's value, if set
30185 * g_settings_get_value:
30186 * @settings: a #GSettings object
30187 * @key: the key to get the value for
30189 * Gets the value that is stored in @settings for @key.
30191 * It is a programmer error to give a @key that isn't contained in the
30192 * schema for @settings.
30194 * Returns: a new #GVariant
30200 * g_settings_is_writable:
30201 * @settings: a #GSettings object
30202 * @name: the name of a key
30204 * Finds out if a key can be written or not
30206 * Returns: %TRUE if the key @name is writable
30212 * g_settings_list_children:
30213 * @settings: a #GSettings object
30215 * Gets the list of children on @settings.
30217 * The list is exactly the list of strings for which it is not an error
30218 * to call g_settings_get_child().
30220 * For GSettings objects that are lists, this value can change at any
30221 * time and you should connect to the "children-changed" signal to watch
30222 * for those changes. Note that there is a race condition here: you may
30223 * request a child after listing it only for it to have been destroyed
30224 * in the meantime. For this reason, g_settings_get_child() may return
30225 * %NULL even for a child that was listed by this function.
30227 * For GSettings objects that are not lists, you should probably not be
30228 * calling this function from "normal" code (since you should already
30229 * know what children are in your schema). This function may still be
30230 * useful there for introspection reasons, however.
30232 * You should free the return value with g_strfreev() when you are done
30235 * Returns: (transfer full) (element-type utf8): a list of the children on @settings
30240 * g_settings_list_keys:
30241 * @settings: a #GSettings object
30243 * Introspects the list of keys on @settings.
30245 * You should probably not be calling this function from "normal" code
30246 * (since you should already know what keys are in your schema). This
30247 * function is intended for introspection reasons.
30249 * You should free the return value with g_strfreev() when you are done
30252 * Returns: (transfer full) (element-type utf8): a list of the keys on @settings
30257 * g_settings_list_relocatable_schemas:
30259 * Returns: (element-type utf8) (transfer none): a list of relocatable
30260 * #GSettings schemas that are available. The list must not be
30261 * modified or freed.
30263 * Deprecated: 2.40: Use g_settings_schema_source_list_schemas() instead
30268 * g_settings_list_schemas:
30270 * Returns: (element-type utf8) (transfer none): a list of #GSettings
30271 * schemas that are available. The list must not be modified or
30274 * Deprecated: 2.40: Use g_settings_schema_source_list_schemas() instead.
30275 * If you used g_settings_list_schemas() to check for the presence of
30276 * a particular schema, use g_settings_schema_source_lookup() instead
30277 * of your whole loop.
30283 * @schema_id: the id of the schema
30285 * Creates a new #GSettings object with the schema specified by
30288 * Signals on the newly created #GSettings object will be dispatched
30289 * via the thread-default #GMainContext in effect at the time of the
30290 * call to g_settings_new(). The new #GSettings will hold a reference
30291 * on the context. See g_main_context_push_thread_default().
30293 * Returns: a new #GSettings object
30299 * g_settings_new_full:
30300 * @schema: a #GSettingsSchema
30301 * @backend: (allow-none): a #GSettingsBackend
30302 * @path: (allow-none): the path to use
30304 * Creates a new #GSettings object with a given schema, backend and
30307 * It should be extremely rare that you ever want to use this function.
30308 * It is made available for advanced use-cases (such as plugin systems
30309 * that want to provide access to schemas loaded from custom locations,
30312 * At the most basic level, a #GSettings object is a pure composition of
30313 * 4 things: a #GSettingsSchema, a #GSettingsBackend, a path within that
30314 * backend, and a #GMainContext to which signals are dispatched.
30316 * This constructor therefore gives you full control over constructing
30317 * #GSettings instances. The first 4 parameters are given directly as
30318 * @schema, @backend and @path, and the main context is taken from the
30319 * thread-default (as per g_settings_new()).
30321 * If @backend is %NULL then the default backend is used.
30323 * If @path is %NULL then the path from the schema is used. It is an
30324 * error f @path is %NULL and the schema has no path of its own or if
30325 * @path is non-%NULL and not equal to the path that the schema does
30328 * Returns: a new #GSettings object
30334 * g_settings_new_with_backend:
30335 * @schema_id: the id of the schema
30336 * @backend: the #GSettingsBackend to use
30338 * Creates a new #GSettings object with the schema specified by
30339 * @schema_id and a given #GSettingsBackend.
30341 * Creating a #GSettings object with a different backend allows accessing
30342 * settings from a database other than the usual one. For example, it may make
30343 * sense to pass a backend corresponding to the "defaults" settings database on
30344 * the system to get a settings object that modifies the system default
30345 * settings instead of the settings for this user.
30347 * Returns: a new #GSettings object
30353 * g_settings_new_with_backend_and_path:
30354 * @schema_id: the id of the schema
30355 * @backend: the #GSettingsBackend to use
30356 * @path: the path to use
30358 * Creates a new #GSettings object with the schema specified by
30359 * @schema_id and a given #GSettingsBackend and path.
30361 * This is a mix of g_settings_new_with_backend() and
30362 * g_settings_new_with_path().
30364 * Returns: a new #GSettings object
30370 * g_settings_new_with_path:
30371 * @schema_id: the id of the schema
30372 * @path: the path to use
30374 * Creates a new #GSettings object with the relocatable schema specified
30375 * by @schema_id and a given path.
30377 * You only need to do this if you want to directly create a settings
30378 * object with a schema that doesn't have a specified path of its own.
30379 * That's quite rare.
30381 * It is a programmer error to call this function for a schema that
30382 * has an explicitly specified path.
30384 * It is a programmer error if @path is not a valid path. A valid path
30385 * begins and ends with '/' and does not contain two consecutive '/'
30388 * Returns: a new #GSettings object
30394 * g_settings_range_check:
30395 * @settings: a #GSettings
30396 * @key: the key to check
30397 * @value: the value to check
30399 * Checks if the given @value is of the correct type and within the
30400 * permitted range for @key.
30402 * Returns: %TRUE if @value is valid for @key
30404 * Deprecated: 2.40: Use g_settings_schema_key_range_check() instead.
30409 * g_settings_reset:
30410 * @settings: a #GSettings object
30411 * @key: the name of a key
30413 * Resets @key to its default value.
30415 * This call resets the key, as much as possible, to its default value.
30416 * That might the value specified in the schema or the one set by the
30422 * g_settings_revert:
30423 * @settings: a #GSettings instance
30425 * Reverts all non-applied changes to the settings. This function
30426 * does nothing unless @settings is in 'delay-apply' mode; see
30427 * g_settings_delay(). In the normal case settings are always applied
30430 * Change notifications will be emitted for affected keys.
30435 * g_settings_schema_get_id:
30436 * @schema: a #GSettingsSchema
30438 * Get the ID of @schema.
30440 * Returns: (transfer none): the ID
30445 * g_settings_schema_get_key:
30446 * @schema: a #GSettingsSchema
30447 * @name: the name of a key
30449 * Gets the key named @name from @schema.
30451 * It is a programmer error to request a key that does not exist. See
30452 * g_settings_schema_list_keys().
30454 * Returns: (transfer full): the #GSettingsSchemaKey for @name
30460 * g_settings_schema_get_path:
30461 * @schema: a #GSettingsSchema
30463 * Gets the path associated with @schema, or %NULL.
30465 * Schemas may be single-instance or relocatable. Single-instance
30466 * schemas correspond to exactly one set of keys in the backend
30467 * database: those located at the path returned by this function.
30469 * Relocatable schemas can be referenced by other schemas and can
30470 * threfore describe multiple sets of keys at different locations. For
30471 * relocatable schemas, this function will return %NULL.
30473 * Returns: (transfer none): the path of the schema, or %NULL
30479 * g_settings_schema_has_key:
30480 * @schema: a #GSettingsSchema
30481 * @name: the name of a key
30483 * Checks if @schema has a key named @name.
30485 * Returns: %TRUE if such a key exists
30491 * g_settings_schema_key_get_default_value:
30492 * @key: a #GSettingsSchemaKey
30494 * Gets the default value for @key.
30496 * Note that this is the default value according to the schema. System
30497 * administrator defaults and lockdown are not visible via this API.
30499 * Returns: (transfer full): the default value for the key
30505 * g_settings_schema_key_get_description:
30506 * @key: a #GSettingsSchemaKey
30508 * Gets the description for @key.
30510 * If no description has been provided in the schema for @key, returns
30513 * The description can be one sentence to several paragraphs in length.
30514 * Paragraphs are delimited with a double newline. Descriptions can be
30515 * translated and the value returned from this function is is the
30518 * This function is slow. The summary and description information for
30519 * the schemas is not stored in the compiled schema database so this
30520 * function has to parse all of the source XML files in the schema
30523 * Returns: the description for @key, or %NULL
30529 * g_settings_schema_key_get_range:
30530 * @key: a #GSettingsSchemaKey
30532 * Queries the range of a key.
30534 * This function will return a #GVariant that fully describes the range
30535 * of values that are valid for @key.
30537 * The type of #GVariant returned is `(sv)`. The string describes
30538 * the type of range restriction in effect. The type and meaning of
30539 * the value contained in the variant depends on the string.
30541 * If the string is `'type'` then the variant contains an empty array.
30542 * The element type of that empty array is the expected type of value
30543 * and all values of that type are valid.
30545 * If the string is `'enum'` then the variant contains an array
30546 * enumerating the possible values. Each item in the array is
30547 * a possible valid value and no other values are valid.
30549 * If the string is `'flags'` then the variant contains an array. Each
30550 * item in the array is a value that may appear zero or one times in an
30551 * array to be used as the value for this key. For example, if the
30552 * variant contained the array `['x', 'y']` then the valid values for
30553 * the key would be `[]`, `['x']`, `['y']`, `['x', 'y']` and
30556 * Finally, if the string is `'range'` then the variant contains a pair
30557 * of like-typed values -- the minimum and maximum permissible values
30560 * This information should not be used by normal programs. It is
30561 * considered to be a hint for introspection purposes. Normal programs
30562 * should already know what is permitted by their own schema. The
30563 * format may change in any way in the future -- but particularly, new
30564 * forms may be added to the possibilities described above.
30566 * You should free the returned value with g_variant_unref() when it is
30567 * no longer needed.
30569 * Returns: (transfer full): a #GVariant describing the range
30575 * g_settings_schema_key_get_summary:
30576 * @key: a #GSettingsSchemaKey
30578 * Gets the summary for @key.
30580 * If no summary has been provided in the schema for @key, returns
30583 * The summary is a short description of the purpose of the key; usually
30584 * one short sentence. Summaries can be translated and the value
30585 * returned from this function is is the current locale.
30587 * This function is slow. The summary and description information for
30588 * the schemas is not stored in the compiled schema database so this
30589 * function has to parse all of the source XML files in the schema
30592 * Returns: the summary for @key, or %NULL
30598 * g_settings_schema_key_get_value_type:
30599 * @key: a #GSettingsSchemaKey
30601 * Gets the #GVariantType of @key.
30603 * Returns: (transfer none): the type of @key
30609 * g_settings_schema_key_range_check:
30610 * @key: a #GSettingsSchemaKey
30611 * @value: the value to check
30613 * Checks if the given @value is of the correct type and within the
30614 * permitted range for @key.
30616 * It is a programmer error if @value is not of the correct type -- you
30617 * must check for this first.
30619 * Returns: %TRUE if @value is valid for @key
30625 * g_settings_schema_key_ref:
30626 * @key: a #GSettingsSchemaKey
30628 * Increase the reference count of @key, returning a new reference.
30630 * Returns: a new reference to @key
30636 * g_settings_schema_key_unref:
30637 * @key: a #GSettingsSchemaKey
30639 * Decrease the reference count of @key, possibly freeing it.
30646 * g_settings_schema_ref:
30647 * @schema: a #GSettingsSchema
30649 * Increase the reference count of @schema, returning a new reference.
30651 * Returns: a new reference to @schema
30657 * g_settings_schema_source_get_default:
30659 * Gets the default system schema source.
30661 * This function is not required for normal uses of #GSettings but it
30662 * may be useful to authors of plugin management systems or to those who
30663 * want to introspect the content of schemas.
30665 * If no schemas are installed, %NULL will be returned.
30667 * The returned source may actually consist of multiple schema sources
30668 * from different directories, depending on which directories were given
30669 * in `XDG_DATA_DIRS` and `GSETTINGS_SCHEMA_DIR`. For this reason, all
30670 * lookups performed against the default source should probably be done
30673 * Returns: (transfer none): the default schema source
30679 * g_settings_schema_source_list_schemas:
30680 * @source: a #GSettingsSchemaSource
30681 * @recursive: if we should recurse
30682 * @non_relocatable: (out) (transfer full) (array zero-terminated=1): the
30683 * list of non-relocatable schemas
30684 * @relocatable: (out) (transfer full) (array zero-terminated=1): the list
30685 * of relocatable schemas
30687 * Lists the schemas in a given source.
30689 * If @recursive is %TRUE then include parent sources. If %FALSE then
30690 * only include the schemas from one source (ie: one directory). You
30691 * probably want %TRUE.
30693 * Non-relocatable schemas are those for which you can call
30694 * g_settings_new(). Relocatable schemas are those for which you must
30695 * use g_settings_new_with_path().
30697 * Do not call this function from normal programs. This is designed for
30698 * use by database editors, commandline tools, etc.
30705 * g_settings_schema_source_lookup:
30706 * @source: a #GSettingsSchemaSource
30707 * @schema_id: a schema ID
30708 * @recursive: %TRUE if the lookup should be recursive
30710 * Looks up a schema with the identifier @schema_id in @source.
30712 * This function is not required for normal uses of #GSettings but it
30713 * may be useful to authors of plugin management systems or to those who
30714 * want to introspect the content of schemas.
30716 * If the schema isn't found directly in @source and @recursive is %TRUE
30717 * then the parent sources will also be checked.
30719 * If the schema isn't found, %NULL is returned.
30721 * Returns: (nullable) (transfer full): a new #GSettingsSchema
30727 * g_settings_schema_source_new_from_directory:
30728 * @directory: the filename of a directory
30729 * @parent: (allow-none): a #GSettingsSchemaSource, or %NULL
30730 * @trusted: %TRUE, if the directory is trusted
30731 * @error: a pointer to a #GError pointer set to %NULL, or %NULL
30733 * Attempts to create a new schema source corresponding to the contents
30734 * of the given directory.
30736 * This function is not required for normal uses of #GSettings but it
30737 * may be useful to authors of plugin management systems.
30739 * The directory should contain a file called `gschemas.compiled` as
30740 * produced by the [glib-compile-schemas][glib-compile-schemas] tool.
30742 * If @trusted is %TRUE then `gschemas.compiled` is trusted not to be
30743 * corrupted. This assumption has a performance advantage, but can result
30744 * in crashes or inconsistent behaviour in the case of a corrupted file.
30745 * Generally, you should set @trusted to %TRUE for files installed by the
30746 * system and to %FALSE for files in the home directory.
30748 * If @parent is non-%NULL then there are two effects.
30750 * First, if g_settings_schema_source_lookup() is called with the
30751 * @recursive flag set to %TRUE and the schema can not be found in the
30752 * source, the lookup will recurse to the parent.
30754 * Second, any references to other schemas specified within this
30755 * source (ie: `child` or `extends`) references may be resolved
30756 * from the @parent.
30758 * For this second reason, except in very unusual situations, the
30759 * @parent should probably be given as the default schema source, as
30760 * returned by g_settings_schema_source_get_default().
30767 * g_settings_schema_source_ref:
30768 * @source: a #GSettingsSchemaSource
30770 * Increase the reference count of @source, returning a new reference.
30772 * Returns: a new reference to @source
30778 * g_settings_schema_source_unref:
30779 * @source: a #GSettingsSchemaSource
30781 * Decrease the reference count of @source, possibly freeing it.
30788 * g_settings_schema_unref:
30789 * @schema: a #GSettingsSchema
30791 * Decrease the reference count of @schema, possibly freeing it.
30799 * @settings: a #GSettings object
30800 * @key: the name of the key to set
30801 * @format: a #GVariant format string
30802 * @...: arguments as per @format
30804 * Sets @key in @settings to @value.
30806 * A convenience function that combines g_settings_set_value() with
30809 * It is a programmer error to give a @key that isn't contained in the
30810 * schema for @settings or for the #GVariantType of @format to mismatch
30811 * the type given in the schema.
30813 * Returns: %TRUE if setting the key succeeded,
30814 * %FALSE if the key was not writable
30820 * g_settings_set_boolean:
30821 * @settings: a #GSettings object
30822 * @key: the name of the key to set
30823 * @value: the value to set it to
30825 * Sets @key in @settings to @value.
30827 * A convenience variant of g_settings_set() for booleans.
30829 * It is a programmer error to give a @key that isn't specified as
30830 * having a boolean type in the schema for @settings.
30832 * Returns: %TRUE if setting the key succeeded,
30833 * %FALSE if the key was not writable
30839 * g_settings_set_double:
30840 * @settings: a #GSettings object
30841 * @key: the name of the key to set
30842 * @value: the value to set it to
30844 * Sets @key in @settings to @value.
30846 * A convenience variant of g_settings_set() for doubles.
30848 * It is a programmer error to give a @key that isn't specified as
30849 * having a 'double' type in the schema for @settings.
30851 * Returns: %TRUE if setting the key succeeded,
30852 * %FALSE if the key was not writable
30858 * g_settings_set_enum:
30859 * @settings: a #GSettings object
30860 * @key: a key, within @settings
30861 * @value: an enumerated value
30863 * Looks up the enumerated type nick for @value and writes it to @key,
30864 * within @settings.
30866 * It is a programmer error to give a @key that isn't contained in the
30867 * schema for @settings or is not marked as an enumerated type, or for
30868 * @value not to be a valid value for the named type.
30870 * After performing the write, accessing @key directly with
30871 * g_settings_get_string() will return the 'nick' associated with
30874 * Returns: %TRUE, if the set succeeds
30879 * g_settings_set_flags:
30880 * @settings: a #GSettings object
30881 * @key: a key, within @settings
30882 * @value: a flags value
30884 * Looks up the flags type nicks for the bits specified by @value, puts
30885 * them in an array of strings and writes the array to @key, within
30888 * It is a programmer error to give a @key that isn't contained in the
30889 * schema for @settings or is not marked as a flags type, or for @value
30890 * to contain any bits that are not value for the named type.
30892 * After performing the write, accessing @key directly with
30893 * g_settings_get_strv() will return an array of 'nicks'; one for each
30896 * Returns: %TRUE, if the set succeeds
30901 * g_settings_set_int:
30902 * @settings: a #GSettings object
30903 * @key: the name of the key to set
30904 * @value: the value to set it to
30906 * Sets @key in @settings to @value.
30908 * A convenience variant of g_settings_set() for 32-bit integers.
30910 * It is a programmer error to give a @key that isn't specified as
30911 * having a int32 type in the schema for @settings.
30913 * Returns: %TRUE if setting the key succeeded,
30914 * %FALSE if the key was not writable
30920 * g_settings_set_string:
30921 * @settings: a #GSettings object
30922 * @key: the name of the key to set
30923 * @value: the value to set it to
30925 * Sets @key in @settings to @value.
30927 * A convenience variant of g_settings_set() for strings.
30929 * It is a programmer error to give a @key that isn't specified as
30930 * having a string type in the schema for @settings.
30932 * Returns: %TRUE if setting the key succeeded,
30933 * %FALSE if the key was not writable
30939 * g_settings_set_strv:
30940 * @settings: a #GSettings object
30941 * @key: the name of the key to set
30942 * @value: (allow-none) (array zero-terminated=1): the value to set it to, or %NULL
30944 * Sets @key in @settings to @value.
30946 * A convenience variant of g_settings_set() for string arrays. If
30947 * @value is %NULL, then @key is set to be the empty array.
30949 * It is a programmer error to give a @key that isn't specified as
30950 * having an array of strings type in the schema for @settings.
30952 * Returns: %TRUE if setting the key succeeded,
30953 * %FALSE if the key was not writable
30959 * g_settings_set_uint:
30960 * @settings: a #GSettings object
30961 * @key: the name of the key to set
30962 * @value: the value to set it to
30964 * Sets @key in @settings to @value.
30966 * A convenience variant of g_settings_set() for 32-bit unsigned
30969 * It is a programmer error to give a @key that isn't specified as
30970 * having a uint32 type in the schema for @settings.
30972 * Returns: %TRUE if setting the key succeeded,
30973 * %FALSE if the key was not writable
30979 * g_settings_set_value:
30980 * @settings: a #GSettings object
30981 * @key: the name of the key to set
30982 * @value: a #GVariant of the correct type
30984 * Sets @key in @settings to @value.
30986 * It is a programmer error to give a @key that isn't contained in the
30987 * schema for @settings or for @value to have the incorrect type, per
30990 * If @value is floating then this function consumes the reference.
30992 * Returns: %TRUE if setting the key succeeded,
30993 * %FALSE if the key was not writable
31001 * Ensures that all pending operations for the given are complete for
31002 * the default backend.
31004 * Writes made to a #GSettings are handled asynchronously. For this
31005 * reason, it is very unlikely that the changes have it to disk by the
31006 * time g_settings_set() returns.
31008 * This call will block until all of the writes have made it to the
31009 * backend. Since the mainloop is not running, no change notifications
31010 * will be dispatched during this call (but some may be queued by the
31011 * time the call is done).
31016 * g_settings_unbind:
31017 * @object: the object
31018 * @property: the property whose binding is removed
31020 * Removes an existing binding for @property on @object.
31022 * Note that bindings are automatically removed when the
31023 * object is finalized, so it is rarely necessary to call this
31031 * g_simple_action_group_add_entries:
31032 * @simple: a #GSimpleActionGroup
31033 * @entries: (array length=n_entries): a pointer to the first item in
31034 * an array of #GActionEntry structs
31035 * @n_entries: the length of @entries, or -1
31036 * @user_data: the user data for signal connections
31038 * A convenience function for creating multiple #GSimpleAction instances
31039 * and adding them to the action group.
31042 * Deprecated: 2.38: Use g_action_map_add_action_entries()
31047 * g_simple_action_group_insert:
31048 * @simple: a #GSimpleActionGroup
31049 * @action: a #GAction
31051 * Adds an action to the action group.
31053 * If the action group already contains an action with the same name as
31054 * @action then the old action is dropped from the group.
31056 * The action group takes its own reference on @action.
31059 * Deprecated: 2.38: Use g_action_map_add_action()
31064 * g_simple_action_group_lookup:
31065 * @simple: a #GSimpleActionGroup
31066 * @action_name: the name of an action
31068 * Looks up the action with the name @action_name in the group.
31070 * If no such action exists, returns %NULL.
31072 * Returns: (transfer none): a #GAction, or %NULL
31074 * Deprecated: 2.38: Use g_action_map_lookup_action()
31079 * g_simple_action_group_new:
31081 * Creates a new, empty, #GSimpleActionGroup.
31083 * Returns: a new #GSimpleActionGroup
31089 * g_simple_action_group_remove:
31090 * @simple: a #GSimpleActionGroup
31091 * @action_name: the name of the action
31093 * Removes the named action from the action group.
31095 * If no action of this name is in the group then nothing happens.
31098 * Deprecated: 2.38: Use g_action_map_remove_action()
31103 * g_simple_action_new:
31104 * @name: the name of the action
31105 * @parameter_type: (allow-none): the type of parameter to the activate function
31107 * Creates a new action.
31109 * The created action is stateless. See g_simple_action_new_stateful().
31111 * Returns: a new #GSimpleAction
31117 * g_simple_action_new_stateful:
31118 * @name: the name of the action
31119 * @parameter_type: (allow-none): the type of the parameter to the activate function
31120 * @state: the initial state of the action
31122 * Creates a new stateful action.
31124 * @state is the initial state of the action. All future state values
31125 * must have the same #GVariantType as the initial state.
31127 * If the @state GVariant is floating, it is consumed.
31129 * Returns: a new #GSimpleAction
31135 * g_simple_action_set_enabled:
31136 * @simple: a #GSimpleAction
31137 * @enabled: whether the action is enabled
31139 * Sets the action as enabled or not.
31141 * An action must be enabled in order to be activated or in order to
31142 * have its state changed from outside callers.
31144 * This should only be called by the implementor of the action. Users
31145 * of the action should not attempt to modify its enabled flag.
31152 * g_simple_action_set_state:
31153 * @simple: a #GSimpleAction
31154 * @value: the new #GVariant for the state
31156 * Sets the state of the action.
31158 * This directly updates the 'state' property to the given value.
31160 * This should only be called by the implementor of the action. Users
31161 * of the action should not attempt to directly modify the 'state'
31162 * property. Instead, they should call g_action_change_state() to
31163 * request the change.
31165 * If the @value GVariant is floating, it is consumed.
31172 * g_simple_async_report_error_in_idle: (skip)
31173 * @object: (allow-none): a #GObject, or %NULL.
31174 * @callback: a #GAsyncReadyCallback.
31175 * @user_data: user data passed to @callback.
31176 * @domain: a #GQuark containing the error domain (usually #G_IO_ERROR).
31177 * @code: a specific error code.
31178 * @format: a formatted error reporting string.
31179 * @...: a list of variables to fill in @format.
31181 * Reports an error in an asynchronous function in an idle function by
31182 * directly setting the contents of the #GAsyncResult with the given error
31188 * g_simple_async_report_gerror_in_idle:
31189 * @object: (allow-none): a #GObject, or %NULL
31190 * @callback: (scope async): a #GAsyncReadyCallback.
31191 * @user_data: (closure): user data passed to @callback.
31192 * @error: the #GError to report
31194 * Reports an error in an idle function. Similar to
31195 * g_simple_async_report_error_in_idle(), but takes a #GError rather
31196 * than building a new one.
31201 * g_simple_async_report_take_gerror_in_idle: (skip)
31202 * @object: (allow-none): a #GObject, or %NULL
31203 * @callback: a #GAsyncReadyCallback.
31204 * @user_data: user data passed to @callback.
31205 * @error: the #GError to report
31207 * Reports an error in an idle function. Similar to
31208 * g_simple_async_report_gerror_in_idle(), but takes over the caller's
31209 * ownership of @error, so the caller does not have to free it any more.
31216 * g_simple_async_result_complete:
31217 * @simple: a #GSimpleAsyncResult.
31219 * Completes an asynchronous I/O job immediately. Must be called in
31220 * the thread where the asynchronous result was to be delivered, as it
31221 * invokes the callback directly. If you are in a different thread use
31222 * g_simple_async_result_complete_in_idle().
31224 * Calling this function takes a reference to @simple for as long as
31225 * is needed to complete the call.
31230 * g_simple_async_result_complete_in_idle:
31231 * @simple: a #GSimpleAsyncResult.
31233 * Completes an asynchronous function in an idle handler in the
31234 * [thread-default main context][g-main-context-push-thread-default]
31235 * of the thread that @simple was initially created in
31236 * (and re-pushes that context around the invocation of the callback).
31238 * Calling this function takes a reference to @simple for as long as
31239 * is needed to complete the call.
31244 * g_simple_async_result_get_op_res_gboolean:
31245 * @simple: a #GSimpleAsyncResult.
31247 * Gets the operation result boolean from within the asynchronous result.
31249 * Returns: %TRUE if the operation's result was %TRUE, %FALSE
31250 * if the operation's result was %FALSE.
31255 * g_simple_async_result_get_op_res_gpointer: (skip)
31256 * @simple: a #GSimpleAsyncResult.
31258 * Gets a pointer result as returned by the asynchronous function.
31260 * Returns: a pointer from the result.
31265 * g_simple_async_result_get_op_res_gssize:
31266 * @simple: a #GSimpleAsyncResult.
31268 * Gets a gssize from the asynchronous result.
31270 * Returns: a gssize returned from the asynchronous function.
31275 * g_simple_async_result_get_source_tag: (skip)
31276 * @simple: a #GSimpleAsyncResult.
31278 * Gets the source tag for the #GSimpleAsyncResult.
31280 * Returns: a #gpointer to the source object for the #GSimpleAsyncResult.
31285 * g_simple_async_result_is_valid:
31286 * @result: the #GAsyncResult passed to the _finish function.
31287 * @source: (allow-none): the #GObject passed to the _finish function.
31288 * @source_tag: (allow-none): the asynchronous function.
31290 * Ensures that the data passed to the _finish function of an async
31291 * operation is consistent. Three checks are performed.
31293 * First, @result is checked to ensure that it is really a
31294 * #GSimpleAsyncResult. Second, @source is checked to ensure that it
31295 * matches the source object of @result. Third, @source_tag is
31296 * checked to ensure that it is equal to the @source_tag argument given
31297 * to g_simple_async_result_new() (which, by convention, is a pointer
31298 * to the _async function corresponding to the _finish function from
31299 * which this function is called). (Alternatively, if either
31300 * @source_tag or @result's source tag is %NULL, then the source tag
31301 * check is skipped.)
31303 * Returns: #TRUE if all checks passed or #FALSE if any failed.
31309 * g_simple_async_result_new:
31310 * @source_object: (allow-none): a #GObject, or %NULL.
31311 * @callback: (scope async): a #GAsyncReadyCallback.
31312 * @user_data: (closure): user data passed to @callback.
31313 * @source_tag: the asynchronous function.
31315 * Creates a #GSimpleAsyncResult.
31317 * The common convention is to create the #GSimpleAsyncResult in the
31318 * function that starts the asynchronous operation and use that same
31319 * function as the @source_tag.
31321 * If your operation supports cancellation with #GCancellable (which it
31322 * probably should) then you should provide the user's cancellable to
31323 * g_simple_async_result_set_check_cancellable() immediately after
31324 * this function returns.
31326 * Returns: a #GSimpleAsyncResult.
31331 * g_simple_async_result_new_error:
31332 * @source_object: (allow-none): a #GObject, or %NULL.
31333 * @callback: (scope async): a #GAsyncReadyCallback.
31334 * @user_data: (closure): user data passed to @callback.
31335 * @domain: a #GQuark.
31336 * @code: an error code.
31337 * @format: a string with format characters.
31338 * @...: a list of values to insert into @format.
31340 * Creates a new #GSimpleAsyncResult with a set error.
31342 * Returns: a #GSimpleAsyncResult.
31347 * g_simple_async_result_new_from_error:
31348 * @source_object: (allow-none): a #GObject, or %NULL.
31349 * @callback: (scope async): a #GAsyncReadyCallback.
31350 * @user_data: (closure): user data passed to @callback.
31351 * @error: a #GError
31353 * Creates a #GSimpleAsyncResult from an error condition.
31355 * Returns: a #GSimpleAsyncResult.
31360 * g_simple_async_result_new_take_error: (skip)
31361 * @source_object: (allow-none): a #GObject, or %NULL
31362 * @callback: (scope async): a #GAsyncReadyCallback
31363 * @user_data: (closure): user data passed to @callback
31364 * @error: a #GError
31366 * Creates a #GSimpleAsyncResult from an error condition, and takes over the
31367 * caller's ownership of @error, so the caller does not need to free it anymore.
31369 * Returns: a #GSimpleAsyncResult
31375 * g_simple_async_result_propagate_error:
31376 * @simple: a #GSimpleAsyncResult.
31377 * @dest: (out): a location to propagate the error to.
31379 * Propagates an error from within the simple asynchronous result to
31380 * a given destination.
31382 * If the #GCancellable given to a prior call to
31383 * g_simple_async_result_set_check_cancellable() is cancelled then this
31384 * function will return %TRUE with @dest set appropriately.
31386 * Returns: %TRUE if the error was propagated to @dest. %FALSE otherwise.
31391 * g_simple_async_result_run_in_thread: (skip)
31392 * @simple: a #GSimpleAsyncResult.
31393 * @func: a #GSimpleAsyncThreadFunc.
31394 * @io_priority: the io priority of the request.
31395 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
31397 * Runs the asynchronous job in a separate thread and then calls
31398 * g_simple_async_result_complete_in_idle() on @simple to return
31399 * the result to the appropriate main loop.
31401 * Calling this function takes a reference to @simple for as long as
31402 * is needed to run the job and report its completion.
31407 * g_simple_async_result_set_check_cancellable:
31408 * @simple: a #GSimpleAsyncResult
31409 * @check_cancellable: (allow-none): a #GCancellable to check, or %NULL to unset
31411 * Sets a #GCancellable to check before dispatching results.
31413 * This function has one very specific purpose: the provided cancellable
31414 * is checked at the time of g_simple_async_result_propagate_error() If
31415 * it is cancelled, these functions will return an "Operation was
31416 * cancelled" error (%G_IO_ERROR_CANCELLED).
31418 * Implementors of cancellable asynchronous functions should use this in
31419 * order to provide a guarantee to their callers that cancelling an
31420 * async operation will reliably result in an error being returned for
31421 * that operation (even if a positive result for the operation has
31422 * already been sent as an idle to the main context to be dispatched).
31424 * The checking described above is done regardless of any call to the
31425 * unrelated g_simple_async_result_set_handle_cancellation() function.
31432 * g_simple_async_result_set_error: (skip)
31433 * @simple: a #GSimpleAsyncResult.
31434 * @domain: a #GQuark (usually #G_IO_ERROR).
31435 * @code: an error code.
31436 * @format: a formatted error reporting string.
31437 * @...: a list of variables to fill in @format.
31439 * Sets an error within the asynchronous result without a #GError.
31444 * g_simple_async_result_set_error_va: (skip)
31445 * @simple: a #GSimpleAsyncResult.
31446 * @domain: a #GQuark (usually #G_IO_ERROR).
31447 * @code: an error code.
31448 * @format: a formatted error reporting string.
31449 * @args: va_list of arguments.
31451 * Sets an error within the asynchronous result without a #GError.
31452 * Unless writing a binding, see g_simple_async_result_set_error().
31457 * g_simple_async_result_set_from_error:
31458 * @simple: a #GSimpleAsyncResult.
31461 * Sets the result from a #GError.
31466 * g_simple_async_result_set_handle_cancellation:
31467 * @simple: a #GSimpleAsyncResult.
31468 * @handle_cancellation: a #gboolean.
31470 * Sets whether to handle cancellation within the asynchronous operation.
31472 * This function has nothing to do with
31473 * g_simple_async_result_set_check_cancellable(). It only refers to the
31474 * #GCancellable passed to g_simple_async_result_run_in_thread().
31479 * g_simple_async_result_set_op_res_gboolean:
31480 * @simple: a #GSimpleAsyncResult.
31481 * @op_res: a #gboolean.
31483 * Sets the operation result to a boolean within the asynchronous result.
31488 * g_simple_async_result_set_op_res_gpointer: (skip)
31489 * @simple: a #GSimpleAsyncResult.
31490 * @op_res: a pointer result from an asynchronous function.
31491 * @destroy_op_res: a #GDestroyNotify function.
31493 * Sets the operation result within the asynchronous result to a pointer.
31498 * g_simple_async_result_set_op_res_gssize:
31499 * @simple: a #GSimpleAsyncResult.
31500 * @op_res: a #gssize.
31502 * Sets the operation result within the asynchronous result to
31503 * the given @op_res.
31508 * g_simple_async_result_take_error: (skip)
31509 * @simple: a #GSimpleAsyncResult
31510 * @error: a #GError
31512 * Sets the result from @error, and takes over the caller's ownership
31513 * of @error, so the caller does not need to free it any more.
31520 * g_simple_permission_new:
31521 * @allowed: %TRUE if the action is allowed
31523 * Creates a new #GPermission instance that represents an action that is
31524 * either always or never allowed.
31526 * Returns: the #GSimplePermission, as a #GPermission
31532 * g_simple_proxy_resolver_new:
31533 * @default_proxy: (allow-none): the default proxy to use, eg
31534 * "socks://192.168.1.1"
31535 * @ignore_hosts: (allow-none): an optional list of hosts/IP addresses
31536 * to not use a proxy for.
31538 * Creates a new #GSimpleProxyResolver. See
31539 * #GSimpleProxyResolver:default-proxy and
31540 * #GSimpleProxyResolver:ignore-hosts for more details on how the
31541 * arguments are interpreted.
31543 * Returns: (transfer full): a new #GSimpleProxyResolver
31549 * g_simple_proxy_resolver_set_default_proxy:
31550 * @resolver: a #GSimpleProxyResolver
31551 * @default_proxy: the default proxy to use
31553 * Sets the default proxy on @resolver, to be used for any URIs that
31554 * don't match #GSimpleProxyResolver:ignore-hosts or a proxy set
31555 * via g_simple_proxy_resolver_set_uri_proxy().
31557 * If @default_proxy starts with "socks://",
31558 * #GSimpleProxyResolver will treat it as referring to all three of
31559 * the socks5, socks4a, and socks4 proxy types.
31566 * g_simple_proxy_resolver_set_ignore_hosts:
31567 * @resolver: a #GSimpleProxyResolver
31568 * @ignore_hosts: %NULL-terminated list of hosts/IP addresses
31569 * to not use a proxy for
31571 * Sets the list of ignored hosts.
31573 * See #GSimpleProxyResolver:ignore-hosts for more details on how the
31574 * @ignore_hosts argument is interpreted.
31581 * g_simple_proxy_resolver_set_uri_proxy:
31582 * @resolver: a #GSimpleProxyResolver
31583 * @uri_scheme: the URI scheme to add a proxy for
31584 * @proxy: the proxy to use for @uri_scheme
31586 * Adds a URI-scheme-specific proxy to @resolver; URIs whose scheme
31587 * matches @uri_scheme (and which don't match
31588 * #GSimpleProxyResolver:ignore-hosts) will be proxied via @proxy.
31590 * As with #GSimpleProxyResolver:default-proxy, if @proxy starts with
31591 * "socks://", #GSimpleProxyResolver will treat it
31592 * as referring to all three of the socks5, socks4a, and socks4 proxy
31601 * @socket: a #GSocket.
31602 * @cancellable: (allow-none): a %GCancellable or %NULL
31603 * @error: #GError for error reporting, or %NULL to ignore.
31605 * Accept incoming connections on a connection-based socket. This removes
31606 * the first outstanding connection request from the listening socket and
31607 * creates a #GSocket object for it.
31609 * The @socket must be bound to a local address with g_socket_bind() and
31610 * must be listening for incoming connections (g_socket_listen()).
31612 * If there are no outstanding connections then the operation will block
31613 * or return %G_IO_ERROR_WOULD_BLOCK if non-blocking I/O is enabled.
31614 * To be notified of an incoming connection, wait for the %G_IO_IN condition.
31616 * Returns: (transfer full): a new #GSocket, or %NULL on error.
31617 * Free the returned object with g_object_unref().
31623 * g_socket_address_enumerator_next:
31624 * @enumerator: a #GSocketAddressEnumerator
31625 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
31626 * @error: a #GError.
31628 * Retrieves the next #GSocketAddress from @enumerator. Note that this
31629 * may block for some amount of time. (Eg, a #GNetworkAddress may need
31630 * to do a DNS lookup before it can return an address.) Use
31631 * g_socket_address_enumerator_next_async() if you need to avoid
31634 * If @enumerator is expected to yield addresses, but for some reason
31635 * is unable to (eg, because of a DNS error), then the first call to
31636 * g_socket_address_enumerator_next() will return an appropriate error
31637 * in *@error. However, if the first call to
31638 * g_socket_address_enumerator_next() succeeds, then any further
31639 * internal errors (other than @cancellable being triggered) will be
31642 * Returns: (transfer full): a #GSocketAddress (owned by the caller), or %NULL on
31643 * error (in which case *@error will be set) or if there are no
31649 * g_socket_address_enumerator_next_async:
31650 * @enumerator: a #GSocketAddressEnumerator
31651 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
31652 * @callback: (scope async): a #GAsyncReadyCallback to call when the request
31654 * @user_data: (closure): the data to pass to callback function
31656 * Asynchronously retrieves the next #GSocketAddress from @enumerator
31657 * and then calls @callback, which must call
31658 * g_socket_address_enumerator_next_finish() to get the result.
31663 * g_socket_address_enumerator_next_finish:
31664 * @enumerator: a #GSocketAddressEnumerator
31665 * @result: a #GAsyncResult
31666 * @error: a #GError
31668 * Retrieves the result of a completed call to
31669 * g_socket_address_enumerator_next_async(). See
31670 * g_socket_address_enumerator_next() for more information about
31673 * Returns: (transfer full): a #GSocketAddress (owned by the caller), or %NULL on
31674 * error (in which case *@error will be set) or if there are no
31680 * g_socket_address_get_family:
31681 * @address: a #GSocketAddress
31683 * Gets the socket family type of @address.
31685 * Returns: the socket family type of @address
31691 * g_socket_address_get_native_size:
31692 * @address: a #GSocketAddress
31694 * Gets the size of @address's native struct sockaddr.
31695 * You can use this to allocate memory to pass to
31696 * g_socket_address_to_native().
31698 * Returns: the size of the native struct sockaddr that
31699 * @address represents
31705 * g_socket_address_new_from_native:
31706 * @native: a pointer to a struct sockaddr
31707 * @len: the size of the memory location pointed to by @native
31709 * Creates a #GSocketAddress subclass corresponding to the native
31710 * struct sockaddr @native.
31712 * Returns: a new #GSocketAddress if @native could successfully
31713 * be converted, otherwise %NULL
31719 * g_socket_address_to_native:
31720 * @address: a #GSocketAddress
31721 * @dest: a pointer to a memory location that will contain the native
31723 * @destlen: the size of @dest. Must be at least as large as
31724 * g_socket_address_get_native_size()
31725 * @error: #GError for error reporting, or %NULL to ignore
31727 * Converts a #GSocketAddress to a native struct sockaddr, which can
31728 * be passed to low-level functions like connect() or bind().
31730 * If not enough space is available, a %G_IO_ERROR_NO_SPACE error
31731 * is returned. If the address type is not known on the system
31732 * then a %G_IO_ERROR_NOT_SUPPORTED error is returned.
31734 * Returns: %TRUE if @dest was filled in, %FALSE on error
31741 * @socket: a #GSocket.
31742 * @address: a #GSocketAddress specifying the local address.
31743 * @allow_reuse: whether to allow reusing this address
31744 * @error: #GError for error reporting, or %NULL to ignore.
31746 * When a socket is created it is attached to an address family, but it
31747 * doesn't have an address in this family. g_socket_bind() assigns the
31748 * address (sometimes called name) of the socket.
31750 * It is generally required to bind to a local address before you can
31751 * receive connections. (See g_socket_listen() and g_socket_accept() ).
31752 * In certain situations, you may also want to bind a socket that will be
31753 * used to initiate connections, though this is not normally required.
31755 * If @socket is a TCP socket, then @allow_reuse controls the setting
31756 * of the `SO_REUSEADDR` socket option; normally it should be %TRUE for
31757 * server sockets (sockets that you will eventually call
31758 * g_socket_accept() on), and %FALSE for client sockets. (Failing to
31759 * set this flag on a server socket may cause g_socket_bind() to return
31760 * %G_IO_ERROR_ADDRESS_IN_USE if the server program is stopped and then
31761 * immediately restarted.)
31763 * If @socket is a UDP socket, then @allow_reuse determines whether or
31764 * not other UDP sockets can be bound to the same address at the same
31765 * time. In particular, you can have several UDP sockets bound to the
31766 * same address, and they will all receive all of the multicast and
31767 * broadcast packets sent to that address. (The behavior of unicast
31768 * UDP packets to an address with multiple listeners is not defined.)
31770 * Returns: %TRUE on success, %FALSE on error.
31776 * g_socket_check_connect_result:
31777 * @socket: a #GSocket
31778 * @error: #GError for error reporting, or %NULL to ignore.
31780 * Checks and resets the pending connect error for the socket.
31781 * This is used to check for errors when g_socket_connect() is
31782 * used in non-blocking mode.
31784 * Returns: %TRUE if no error, %FALSE otherwise, setting @error to the error
31790 * g_socket_client_add_application_proxy:
31791 * @client: a #GSocketClient
31792 * @protocol: The proxy protocol
31794 * Enable proxy protocols to be handled by the application. When the
31795 * indicated proxy protocol is returned by the #GProxyResolver,
31796 * #GSocketClient will consider this protocol as supported but will
31797 * not try to find a #GProxy instance to handle handshaking. The
31798 * application must check for this case by calling
31799 * g_socket_connection_get_remote_address() on the returned
31800 * #GSocketConnection, and seeing if it's a #GProxyAddress of the
31801 * appropriate type, to determine whether or not it needs to handle
31802 * the proxy handshaking itself.
31804 * This should be used for proxy protocols that are dialects of
31805 * another protocol such as HTTP proxy. It also allows cohabitation of
31806 * proxy protocols that are reused between protocols. A good example
31807 * is HTTP. It can be used to proxy HTTP, FTP and Gopher and can also
31808 * be use as generic socket proxy through the HTTP CONNECT method.
31810 * When the proxy is detected as being an application proxy, TLS handshake
31811 * will be skipped. This is required to let the application do the proxy
31812 * specific handshake.
31817 * g_socket_client_connect:
31818 * @client: a #GSocketClient.
31819 * @connectable: a #GSocketConnectable specifying the remote address.
31820 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
31821 * @error: #GError for error reporting, or %NULL to ignore.
31823 * Tries to resolve the @connectable and make a network connection to it.
31825 * Upon a successful connection, a new #GSocketConnection is constructed
31826 * and returned. The caller owns this new object and must drop their
31827 * reference to it when finished with it.
31829 * The type of the #GSocketConnection object returned depends on the type of
31830 * the underlying socket that is used. For instance, for a TCP/IP connection
31831 * it will be a #GTcpConnection.
31833 * The socket created will be the same family as the address that the
31834 * @connectable resolves to, unless family is set with g_socket_client_set_family()
31835 * or indirectly via g_socket_client_set_local_address(). The socket type
31836 * defaults to %G_SOCKET_TYPE_STREAM but can be set with
31837 * g_socket_client_set_socket_type().
31839 * If a local address is specified with g_socket_client_set_local_address() the
31840 * socket will be bound to this address before connecting.
31842 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
31848 * g_socket_client_connect_async:
31849 * @client: a #GSocketClient
31850 * @connectable: a #GSocketConnectable specifying the remote address.
31851 * @cancellable: (allow-none): a #GCancellable, or %NULL
31852 * @callback: (scope async): a #GAsyncReadyCallback
31853 * @user_data: (closure): user data for the callback
31855 * This is the asynchronous version of g_socket_client_connect().
31857 * When the operation is finished @callback will be
31858 * called. You can then call g_socket_client_connect_finish() to get
31859 * the result of the operation.
31866 * g_socket_client_connect_finish:
31867 * @client: a #GSocketClient.
31868 * @result: a #GAsyncResult.
31869 * @error: a #GError location to store the error occurring, or %NULL to
31872 * Finishes an async connect operation. See g_socket_client_connect_async()
31874 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
31880 * g_socket_client_connect_to_host:
31881 * @client: a #GSocketClient
31882 * @host_and_port: the name and optionally port of the host to connect to
31883 * @default_port: the default port to connect to
31884 * @cancellable: (allow-none): a #GCancellable, or %NULL
31885 * @error: a pointer to a #GError, or %NULL
31887 * This is a helper function for g_socket_client_connect().
31889 * Attempts to create a TCP connection to the named host.
31891 * @host_and_port may be in any of a number of recognized formats; an IPv6
31892 * address, an IPv4 address, or a domain name (in which case a DNS
31893 * lookup is performed). Quoting with [] is supported for all address
31894 * types. A port override may be specified in the usual way with a
31895 * colon. Ports may be given as decimal numbers or symbolic names (in
31896 * which case an /etc/services lookup is performed).
31898 * If no port override is given in @host_and_port then @default_port will be
31899 * used as the port number to connect to.
31901 * In general, @host_and_port is expected to be provided by the user (allowing
31902 * them to give the hostname, and a port override if necessary) and
31903 * @default_port is expected to be provided by the application.
31905 * In the case that an IP address is given, a single connection
31906 * attempt is made. In the case that a name is given, multiple
31907 * connection attempts may be made, in turn and according to the
31908 * number of address records in DNS, until a connection succeeds.
31910 * Upon a successful connection, a new #GSocketConnection is constructed
31911 * and returned. The caller owns this new object and must drop their
31912 * reference to it when finished with it.
31914 * In the event of any failure (DNS error, service not found, no hosts
31915 * connectable) %NULL is returned and @error (if non-%NULL) is set
31918 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
31924 * g_socket_client_connect_to_host_async:
31925 * @client: a #GSocketClient
31926 * @host_and_port: the name and optionally the port of the host to connect to
31927 * @default_port: the default port to connect to
31928 * @cancellable: (allow-none): a #GCancellable, or %NULL
31929 * @callback: (scope async): a #GAsyncReadyCallback
31930 * @user_data: (closure): user data for the callback
31932 * This is the asynchronous version of g_socket_client_connect_to_host().
31934 * When the operation is finished @callback will be
31935 * called. You can then call g_socket_client_connect_to_host_finish() to get
31936 * the result of the operation.
31943 * g_socket_client_connect_to_host_finish:
31944 * @client: a #GSocketClient.
31945 * @result: a #GAsyncResult.
31946 * @error: a #GError location to store the error occurring, or %NULL to
31949 * Finishes an async connect operation. See g_socket_client_connect_to_host_async()
31951 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
31957 * g_socket_client_connect_to_service:
31958 * @client: a #GSocketConnection
31959 * @domain: a domain name
31960 * @service: the name of the service to connect to
31961 * @cancellable: (allow-none): a #GCancellable, or %NULL
31962 * @error: a pointer to a #GError, or %NULL
31964 * Attempts to create a TCP connection to a service.
31966 * This call looks up the SRV record for @service at @domain for the
31967 * "tcp" protocol. It then attempts to connect, in turn, to each of
31968 * the hosts providing the service until either a connection succeeds
31969 * or there are no hosts remaining.
31971 * Upon a successful connection, a new #GSocketConnection is constructed
31972 * and returned. The caller owns this new object and must drop their
31973 * reference to it when finished with it.
31975 * In the event of any failure (DNS error, service not found, no hosts
31976 * connectable) %NULL is returned and @error (if non-%NULL) is set
31979 * Returns: (transfer full): a #GSocketConnection if successful, or %NULL on error
31984 * g_socket_client_connect_to_service_async:
31985 * @client: a #GSocketClient
31986 * @domain: a domain name
31987 * @service: the name of the service to connect to
31988 * @cancellable: (allow-none): a #GCancellable, or %NULL
31989 * @callback: (scope async): a #GAsyncReadyCallback
31990 * @user_data: (closure): user data for the callback
31992 * This is the asynchronous version of
31993 * g_socket_client_connect_to_service().
32000 * g_socket_client_connect_to_service_finish:
32001 * @client: a #GSocketClient.
32002 * @result: a #GAsyncResult.
32003 * @error: a #GError location to store the error occurring, or %NULL to
32006 * Finishes an async connect operation. See g_socket_client_connect_to_service_async()
32008 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
32014 * g_socket_client_connect_to_uri:
32015 * @client: a #GSocketClient
32016 * @uri: A network URI
32017 * @default_port: the default port to connect to
32018 * @cancellable: (allow-none): a #GCancellable, or %NULL
32019 * @error: a pointer to a #GError, or %NULL
32021 * This is a helper function for g_socket_client_connect().
32023 * Attempts to create a TCP connection with a network URI.
32025 * @uri may be any valid URI containing an "authority" (hostname/port)
32026 * component. If a port is not specified in the URI, @default_port
32027 * will be used. TLS will be negotiated if #GSocketClient:tls is %TRUE.
32028 * (#GSocketClient does not know to automatically assume TLS for
32029 * certain URI schemes.)
32031 * Using this rather than g_socket_client_connect() or
32032 * g_socket_client_connect_to_host() allows #GSocketClient to
32033 * determine when to use application-specific proxy protocols.
32035 * Upon a successful connection, a new #GSocketConnection is constructed
32036 * and returned. The caller owns this new object and must drop their
32037 * reference to it when finished with it.
32039 * In the event of any failure (DNS error, service not found, no hosts
32040 * connectable) %NULL is returned and @error (if non-%NULL) is set
32043 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
32049 * g_socket_client_connect_to_uri_async:
32050 * @client: a #GSocketClient
32051 * @uri: a network uri
32052 * @default_port: the default port to connect to
32053 * @cancellable: (allow-none): a #GCancellable, or %NULL
32054 * @callback: (scope async): a #GAsyncReadyCallback
32055 * @user_data: (closure): user data for the callback
32057 * This is the asynchronous version of g_socket_client_connect_to_uri().
32059 * When the operation is finished @callback will be
32060 * called. You can then call g_socket_client_connect_to_uri_finish() to get
32061 * the result of the operation.
32068 * g_socket_client_connect_to_uri_finish:
32069 * @client: a #GSocketClient.
32070 * @result: a #GAsyncResult.
32071 * @error: a #GError location to store the error occurring, or %NULL to
32074 * Finishes an async connect operation. See g_socket_client_connect_to_uri_async()
32076 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
32082 * g_socket_client_get_enable_proxy:
32083 * @client: a #GSocketClient.
32085 * Gets the proxy enable state; see g_socket_client_set_enable_proxy()
32087 * Returns: whether proxying is enabled
32093 * g_socket_client_get_family:
32094 * @client: a #GSocketClient.
32096 * Gets the socket family of the socket client.
32098 * See g_socket_client_set_family() for details.
32100 * Returns: a #GSocketFamily
32106 * g_socket_client_get_local_address:
32107 * @client: a #GSocketClient.
32109 * Gets the local address of the socket client.
32111 * See g_socket_client_set_local_address() for details.
32113 * Returns: (transfer none): a #GSocketAddress or %NULL. Do not free.
32119 * g_socket_client_get_protocol:
32120 * @client: a #GSocketClient
32122 * Gets the protocol name type of the socket client.
32124 * See g_socket_client_set_protocol() for details.
32126 * Returns: a #GSocketProtocol
32132 * g_socket_client_get_proxy_resolver:
32133 * @client: a #GSocketClient.
32135 * Gets the #GProxyResolver being used by @client. Normally, this will
32136 * be the resolver returned by g_proxy_resolver_get_default(), but you
32137 * can override it with g_socket_client_set_proxy_resolver().
32139 * Returns: (transfer none): The #GProxyResolver being used by
32146 * g_socket_client_get_socket_type:
32147 * @client: a #GSocketClient.
32149 * Gets the socket type of the socket client.
32151 * See g_socket_client_set_socket_type() for details.
32153 * Returns: a #GSocketFamily
32159 * g_socket_client_get_timeout:
32160 * @client: a #GSocketClient
32162 * Gets the I/O timeout time for sockets created by @client.
32164 * See g_socket_client_set_timeout() for details.
32166 * Returns: the timeout in seconds
32172 * g_socket_client_get_tls:
32173 * @client: a #GSocketClient.
32175 * Gets whether @client creates TLS connections. See
32176 * g_socket_client_set_tls() for details.
32178 * Returns: whether @client uses TLS
32184 * g_socket_client_get_tls_validation_flags:
32185 * @client: a #GSocketClient.
32187 * Gets the TLS validation flags used creating TLS connections via
32190 * Returns: the TLS validation flags
32196 * g_socket_client_new:
32198 * Creates a new #GSocketClient with the default options.
32200 * Returns: a #GSocketClient.
32201 * Free the returned object with g_object_unref().
32207 * g_socket_client_set_enable_proxy:
32208 * @client: a #GSocketClient.
32209 * @enable: whether to enable proxies
32211 * Sets whether or not @client attempts to make connections via a
32212 * proxy server. When enabled (the default), #GSocketClient will use a
32213 * #GProxyResolver to determine if a proxy protocol such as SOCKS is
32214 * needed, and automatically do the necessary proxy negotiation.
32216 * See also g_socket_client_set_proxy_resolver().
32223 * g_socket_client_set_family:
32224 * @client: a #GSocketClient.
32225 * @family: a #GSocketFamily
32227 * Sets the socket family of the socket client.
32228 * If this is set to something other than %G_SOCKET_FAMILY_INVALID
32229 * then the sockets created by this object will be of the specified
32232 * This might be useful for instance if you want to force the local
32233 * connection to be an ipv4 socket, even though the address might
32234 * be an ipv6 mapped to ipv4 address.
32241 * g_socket_client_set_local_address:
32242 * @client: a #GSocketClient.
32243 * @address: (allow-none): a #GSocketAddress, or %NULL
32245 * Sets the local address of the socket client.
32246 * The sockets created by this object will bound to the
32247 * specified address (if not %NULL) before connecting.
32249 * This is useful if you want to ensure that the local
32250 * side of the connection is on a specific port, or on
32251 * a specific interface.
32258 * g_socket_client_set_protocol:
32259 * @client: a #GSocketClient.
32260 * @protocol: a #GSocketProtocol
32262 * Sets the protocol of the socket client.
32263 * The sockets created by this object will use of the specified
32266 * If @protocol is %0 that means to use the default
32267 * protocol for the socket family and type.
32274 * g_socket_client_set_proxy_resolver:
32275 * @client: a #GSocketClient.
32276 * @proxy_resolver: (allow-none): a #GProxyResolver, or %NULL for the
32279 * Overrides the #GProxyResolver used by @client. You can call this if
32280 * you want to use specific proxies, rather than using the system
32281 * default proxy settings.
32283 * Note that whether or not the proxy resolver is actually used
32284 * depends on the setting of #GSocketClient:enable-proxy, which is not
32285 * changed by this function (but which is %TRUE by default)
32292 * g_socket_client_set_socket_type:
32293 * @client: a #GSocketClient.
32294 * @type: a #GSocketType
32296 * Sets the socket type of the socket client.
32297 * The sockets created by this object will be of the specified
32300 * It doesn't make sense to specify a type of %G_SOCKET_TYPE_DATAGRAM,
32301 * as GSocketClient is used for connection oriented services.
32308 * g_socket_client_set_timeout:
32309 * @client: a #GSocketClient.
32310 * @timeout: the timeout
32312 * Sets the I/O timeout for sockets created by @client. @timeout is a
32313 * time in seconds, or 0 for no timeout (the default).
32315 * The timeout value affects the initial connection attempt as well,
32316 * so setting this may cause calls to g_socket_client_connect(), etc,
32317 * to fail with %G_IO_ERROR_TIMED_OUT.
32324 * g_socket_client_set_tls:
32325 * @client: a #GSocketClient.
32326 * @tls: whether to use TLS
32328 * Sets whether @client creates TLS (aka SSL) connections. If @tls is
32329 * %TRUE, @client will wrap its connections in a #GTlsClientConnection
32330 * and perform a TLS handshake when connecting.
32332 * Note that since #GSocketClient must return a #GSocketConnection,
32333 * but #GTlsClientConnection is not a #GSocketConnection, this
32334 * actually wraps the resulting #GTlsClientConnection in a
32335 * #GTcpWrapperConnection when returning it. You can use
32336 * g_tcp_wrapper_connection_get_base_io_stream() on the return value
32337 * to extract the #GTlsClientConnection.
32339 * If you need to modify the behavior of the TLS handshake (eg, by
32340 * setting a client-side certificate to use, or connecting to the
32341 * #GTlsConnection::accept-certificate signal), you can connect to
32342 * @client's #GSocketClient::event signal and wait for it to be
32343 * emitted with %G_SOCKET_CLIENT_TLS_HANDSHAKING, which will give you
32344 * a chance to see the #GTlsClientConnection before the handshake
32352 * g_socket_client_set_tls_validation_flags:
32353 * @client: a #GSocketClient.
32354 * @flags: the validation flags
32356 * Sets the TLS validation flags used when creating TLS connections
32357 * via @client. The default value is %G_TLS_CERTIFICATE_VALIDATE_ALL.
32365 * @socket: a #GSocket
32366 * @error: #GError for error reporting, or %NULL to ignore.
32368 * Closes the socket, shutting down any active connection.
32370 * Closing a socket does not wait for all outstanding I/O operations
32371 * to finish, so the caller should not rely on them to be guaranteed
32372 * to complete even if the close returns with no error.
32374 * Once the socket is closed, all other operations will return
32375 * %G_IO_ERROR_CLOSED. Closing a socket multiple times will not
32378 * Sockets will be automatically closed when the last reference
32379 * is dropped, but you might want to call this function to make sure
32380 * resources are released as early as possible.
32382 * Beware that due to the way that TCP works, it is possible for
32383 * recently-sent data to be lost if either you close a socket while the
32384 * %G_IO_IN condition is set, or else if the remote connection tries to
32385 * send something to you after you close the socket but before it has
32386 * finished reading all of the data you sent. There is no easy generic
32387 * way to avoid this problem; the easiest fix is to design the network
32388 * protocol such that the client will never send data "out of turn".
32389 * Another solution is for the server to half-close the connection by
32390 * calling g_socket_shutdown() with only the @shutdown_write flag set,
32391 * and then wait for the client to notice this and close its side of the
32392 * connection, after which the server can safely call g_socket_close().
32393 * (This is what #GTcpConnection does if you call
32394 * g_tcp_connection_set_graceful_disconnect(). But of course, this
32395 * only works if the client will close its connection after the server
32398 * Returns: %TRUE on success, %FALSE on error
32404 * g_socket_condition_check:
32405 * @socket: a #GSocket
32406 * @condition: a #GIOCondition mask to check
32408 * Checks on the readiness of @socket to perform operations.
32409 * The operations specified in @condition are checked for and masked
32410 * against the currently-satisfied conditions on @socket. The result
32413 * Note that on Windows, it is possible for an operation to return
32414 * %G_IO_ERROR_WOULD_BLOCK even immediately after
32415 * g_socket_condition_check() has claimed that the socket is ready for
32416 * writing. Rather than calling g_socket_condition_check() and then
32417 * writing to the socket if it succeeds, it is generally better to
32418 * simply try writing to the socket right away, and try again later if
32419 * the initial attempt returns %G_IO_ERROR_WOULD_BLOCK.
32421 * It is meaningless to specify %G_IO_ERR or %G_IO_HUP in condition;
32422 * these conditions will always be set in the output if they are true.
32424 * This call never blocks.
32426 * Returns: the @GIOCondition mask of the current state
32432 * g_socket_condition_timed_wait:
32433 * @socket: a #GSocket
32434 * @condition: a #GIOCondition mask to wait for
32435 * @timeout: the maximum time (in microseconds) to wait, or -1
32436 * @cancellable: (allow-none): a #GCancellable, or %NULL
32437 * @error: a #GError pointer, or %NULL
32439 * Waits for up to @timeout microseconds for @condition to become true
32440 * on @socket. If the condition is met, %TRUE is returned.
32442 * If @cancellable is cancelled before the condition is met, or if
32443 * @timeout (or the socket's #GSocket:timeout) is reached before the
32444 * condition is met, then %FALSE is returned and @error, if non-%NULL,
32445 * is set to the appropriate value (%G_IO_ERROR_CANCELLED or
32446 * %G_IO_ERROR_TIMED_OUT).
32448 * If you don't want a timeout, use g_socket_condition_wait().
32449 * (Alternatively, you can pass -1 for @timeout.)
32451 * Note that although @timeout is in microseconds for consistency with
32452 * other GLib APIs, this function actually only has millisecond
32453 * resolution, and the behavior is undefined if @timeout is not an
32454 * exact number of milliseconds.
32456 * Returns: %TRUE if the condition was met, %FALSE otherwise
32462 * g_socket_condition_wait:
32463 * @socket: a #GSocket
32464 * @condition: a #GIOCondition mask to wait for
32465 * @cancellable: (allow-none): a #GCancellable, or %NULL
32466 * @error: a #GError pointer, or %NULL
32468 * Waits for @condition to become true on @socket. When the condition
32469 * is met, %TRUE is returned.
32471 * If @cancellable is cancelled before the condition is met, or if the
32472 * socket has a timeout set and it is reached before the condition is
32473 * met, then %FALSE is returned and @error, if non-%NULL, is set to
32474 * the appropriate value (%G_IO_ERROR_CANCELLED or
32475 * %G_IO_ERROR_TIMED_OUT).
32477 * See also g_socket_condition_timed_wait().
32479 * Returns: %TRUE if the condition was met, %FALSE otherwise
32485 * g_socket_connect:
32486 * @socket: a #GSocket.
32487 * @address: a #GSocketAddress specifying the remote address.
32488 * @cancellable: (allow-none): a %GCancellable or %NULL
32489 * @error: #GError for error reporting, or %NULL to ignore.
32491 * Connect the socket to the specified remote address.
32493 * For connection oriented socket this generally means we attempt to make
32494 * a connection to the @address. For a connection-less socket it sets
32495 * the default address for g_socket_send() and discards all incoming datagrams
32496 * from other sources.
32498 * Generally connection oriented sockets can only connect once, but
32499 * connection-less sockets can connect multiple times to change the
32502 * If the connect call needs to do network I/O it will block, unless
32503 * non-blocking I/O is enabled. Then %G_IO_ERROR_PENDING is returned
32504 * and the user can be notified of the connection finishing by waiting
32505 * for the G_IO_OUT condition. The result of the connection must then be
32506 * checked with g_socket_check_connect_result().
32508 * Returns: %TRUE if connected, %FALSE on error.
32514 * g_socket_connectable_enumerate:
32515 * @connectable: a #GSocketConnectable
32517 * Creates a #GSocketAddressEnumerator for @connectable.
32519 * Returns: (transfer full): a new #GSocketAddressEnumerator.
32525 * g_socket_connectable_proxy_enumerate:
32526 * @connectable: a #GSocketConnectable
32528 * Creates a #GSocketAddressEnumerator for @connectable that will
32529 * return #GProxyAddresses for addresses that you must connect
32532 * If @connectable does not implement
32533 * g_socket_connectable_proxy_enumerate(), this will fall back to
32534 * calling g_socket_connectable_enumerate().
32536 * Returns: (transfer full): a new #GSocketAddressEnumerator.
32542 * g_socket_connection_connect:
32543 * @connection: a #GSocketConnection
32544 * @address: a #GSocketAddress specifying the remote address.
32545 * @cancellable: (allow-none): a %GCancellable or %NULL
32546 * @error: #GError for error reporting, or %NULL to ignore.
32548 * Connect @connection to the specified remote address.
32550 * Returns: %TRUE if the connection succeeded, %FALSE on error
32556 * g_socket_connection_connect_async:
32557 * @connection: a #GSocketConnection
32558 * @address: a #GSocketAddress specifying the remote address.
32559 * @cancellable: (allow-none): a %GCancellable or %NULL
32560 * @callback: (scope async): a #GAsyncReadyCallback
32561 * @user_data: (closure): user data for the callback
32563 * Asynchronously connect @connection to the specified remote address.
32565 * This clears the #GSocket:blocking flag on @connection's underlying
32566 * socket if it is currently set.
32568 * Use g_socket_connection_connect_finish() to retrieve the result.
32575 * g_socket_connection_connect_finish:
32576 * @connection: a #GSocketConnection
32577 * @result: the #GAsyncResult
32578 * @error: #GError for error reporting, or %NULL to ignore.
32580 * Gets the result of a g_socket_connection_connect_async() call.
32582 * Returns: %TRUE if the connection succeeded, %FALSE on error
32588 * g_socket_connection_factory_create_connection:
32589 * @socket: a #GSocket
32591 * Creates a #GSocketConnection subclass of the right type for
32594 * Returns: (transfer full): a #GSocketConnection
32600 * g_socket_connection_factory_lookup_type:
32601 * @family: a #GSocketFamily
32602 * @type: a #GSocketType
32603 * @protocol_id: a protocol id
32605 * Looks up the #GType to be used when creating socket connections on
32606 * sockets with the specified @family, @type and @protocol_id.
32608 * If no type is registered, the #GSocketConnection base type is returned.
32610 * Returns: a #GType
32616 * g_socket_connection_factory_register_type:
32617 * @g_type: a #GType, inheriting from %G_TYPE_SOCKET_CONNECTION
32618 * @family: a #GSocketFamily
32619 * @type: a #GSocketType
32620 * @protocol: a protocol id
32622 * Looks up the #GType to be used when creating socket connections on
32623 * sockets with the specified @family, @type and @protocol.
32625 * If no type is registered, the #GSocketConnection base type is returned.
32632 * g_socket_connection_get_local_address:
32633 * @connection: a #GSocketConnection
32634 * @error: #GError for error reporting, or %NULL to ignore.
32636 * Try to get the local address of a socket connection.
32638 * Returns: (transfer full): a #GSocketAddress or %NULL on error.
32639 * Free the returned object with g_object_unref().
32645 * g_socket_connection_get_remote_address:
32646 * @connection: a #GSocketConnection
32647 * @error: #GError for error reporting, or %NULL to ignore.
32649 * Try to get the remote address of a socket connection.
32651 * Since GLib 2.40, when used with g_socket_client_connect() or
32652 * g_socket_client_connect_async(), during emission of
32653 * %G_SOCKET_CLIENT_CONNECTING, this function will return the remote
32654 * address that will be used for the connection. This allows
32655 * applications to print e.g. "Connecting to example.com
32656 * (10.42.77.3)...".
32658 * Returns: (transfer full): a #GSocketAddress or %NULL on error.
32659 * Free the returned object with g_object_unref().
32665 * g_socket_connection_get_socket:
32666 * @connection: a #GSocketConnection
32668 * Gets the underlying #GSocket object of the connection.
32669 * This can be useful if you want to do something unusual on it
32670 * not supported by the #GSocketConnection APIs.
32672 * Returns: (transfer none): a #GSocketAddress or %NULL on error.
32678 * g_socket_connection_is_connected:
32679 * @connection: a #GSocketConnection
32681 * Checks if @connection is connected. This is equivalent to calling
32682 * g_socket_is_connected() on @connection's underlying #GSocket.
32684 * Returns: whether @connection is connected
32690 * g_socket_control_message_deserialize:
32691 * @level: a socket level
32692 * @type: a socket control message type for the given @level
32693 * @size: the size of the data in bytes
32694 * @data: (array length=size) (element-type guint8): pointer to the message data
32696 * Tries to deserialize a socket control message of a given
32697 * @level and @type. This will ask all known (to GType) subclasses
32698 * of #GSocketControlMessage if they can understand this kind
32699 * of message and if so deserialize it into a #GSocketControlMessage.
32701 * If there is no implementation for this kind of control message, %NULL
32702 * will be returned.
32704 * Returns: (transfer full): the deserialized message or %NULL
32710 * g_socket_control_message_get_level:
32711 * @message: a #GSocketControlMessage
32713 * Returns the "level" (i.e. the originating protocol) of the control message.
32714 * This is often SOL_SOCKET.
32716 * Returns: an integer describing the level
32722 * g_socket_control_message_get_msg_type:
32723 * @message: a #GSocketControlMessage
32725 * Returns the protocol specific type of the control message.
32726 * For instance, for UNIX fd passing this would be SCM_RIGHTS.
32728 * Returns: an integer describing the type of control message
32734 * g_socket_control_message_get_size:
32735 * @message: a #GSocketControlMessage
32737 * Returns the space required for the control message, not including
32738 * headers or alignment.
32740 * Returns: The number of bytes required.
32746 * g_socket_control_message_serialize:
32747 * @message: a #GSocketControlMessage
32748 * @data: A buffer to write data to
32750 * Converts the data in the message to bytes placed in the
32753 * @data is guaranteed to have enough space to fit the size
32754 * returned by g_socket_control_message_get_size() on this
32762 * g_socket_create_source: (skip)
32763 * @socket: a #GSocket
32764 * @condition: a #GIOCondition mask to monitor
32765 * @cancellable: (allow-none): a %GCancellable or %NULL
32767 * Creates a #GSource that can be attached to a %GMainContext to monitor
32768 * for the availability of the specified @condition on the socket. The #GSource
32769 * keeps a reference to the @socket.
32771 * The callback on the source is of the #GSocketSourceFunc type.
32773 * It is meaningless to specify %G_IO_ERR or %G_IO_HUP in @condition;
32774 * these conditions will always be reported output if they are true.
32776 * @cancellable if not %NULL can be used to cancel the source, which will
32777 * cause the source to trigger, reporting the current condition (which
32778 * is likely 0 unless cancellation happened at the same time as a
32779 * condition change). You can check for this in the callback using
32780 * g_cancellable_is_cancelled().
32782 * If @socket has a timeout set, and it is reached before @condition
32783 * occurs, the source will then trigger anyway, reporting %G_IO_IN or
32784 * %G_IO_OUT depending on @condition. However, @socket will have been
32785 * marked as having had a timeout, and so the next #GSocket I/O method
32786 * you call will then fail with a %G_IO_ERROR_TIMED_OUT.
32788 * Returns: (transfer full): a newly allocated %GSource, free with g_source_unref().
32794 * g_socket_get_available_bytes:
32795 * @socket: a #GSocket
32797 * Get the amount of data pending in the OS input buffer.
32799 * If @socket is a UDP or SCTP socket, this will return the size of
32800 * just the next packet, even if additional packets are buffered after
32803 * Note that on Windows, this function is rather inefficient in the
32804 * UDP case, and so if you know any plausible upper bound on the size
32805 * of the incoming packet, it is better to just do a
32806 * g_socket_receive() with a buffer of that size, rather than calling
32807 * g_socket_get_available_bytes() first and then doing a receive of
32808 * exactly the right size.
32810 * Returns: the number of bytes that can be read from the socket
32811 * without blocking or truncating, or -1 on error.
32817 * g_socket_get_blocking:
32818 * @socket: a #GSocket.
32820 * Gets the blocking mode of the socket. For details on blocking I/O,
32821 * see g_socket_set_blocking().
32823 * Returns: %TRUE if blocking I/O is used, %FALSE otherwise.
32829 * g_socket_get_broadcast:
32830 * @socket: a #GSocket.
32832 * Gets the broadcast setting on @socket; if %TRUE,
32833 * it is possible to send packets to broadcast
32836 * Returns: the broadcast setting on @socket
32842 * g_socket_get_credentials:
32843 * @socket: a #GSocket.
32844 * @error: #GError for error reporting, or %NULL to ignore.
32846 * Returns the credentials of the foreign process connected to this
32847 * socket, if any (e.g. it is only supported for %G_SOCKET_FAMILY_UNIX
32850 * If this operation isn't supported on the OS, the method fails with
32851 * the %G_IO_ERROR_NOT_SUPPORTED error. On Linux this is implemented
32852 * by reading the %SO_PEERCRED option on the underlying socket.
32854 * Other ways to obtain credentials from a foreign peer includes the
32855 * #GUnixCredentialsMessage type and
32856 * g_unix_connection_send_credentials() /
32857 * g_unix_connection_receive_credentials() functions.
32859 * Returns: (transfer full): %NULL if @error is set, otherwise a #GCredentials object
32860 * that must be freed with g_object_unref().
32866 * g_socket_get_family:
32867 * @socket: a #GSocket.
32869 * Gets the socket family of the socket.
32871 * Returns: a #GSocketFamily
32878 * @socket: a #GSocket.
32880 * Returns the underlying OS socket object. On unix this
32881 * is a socket file descriptor, and on Windows this is
32882 * a Winsock2 SOCKET handle. This may be useful for
32883 * doing platform specific or otherwise unusual operations
32886 * Returns: the file descriptor of the socket.
32892 * g_socket_get_keepalive:
32893 * @socket: a #GSocket.
32895 * Gets the keepalive mode of the socket. For details on this,
32896 * see g_socket_set_keepalive().
32898 * Returns: %TRUE if keepalive is active, %FALSE otherwise.
32904 * g_socket_get_listen_backlog:
32905 * @socket: a #GSocket.
32907 * Gets the listen backlog setting of the socket. For details on this,
32908 * see g_socket_set_listen_backlog().
32910 * Returns: the maximum number of pending connections.
32916 * g_socket_get_local_address:
32917 * @socket: a #GSocket.
32918 * @error: #GError for error reporting, or %NULL to ignore.
32920 * Try to get the local address of a bound socket. This is only
32921 * useful if the socket has been bound to a local address,
32922 * either explicitly or implicitly when connecting.
32924 * Returns: (transfer full): a #GSocketAddress or %NULL on error.
32925 * Free the returned object with g_object_unref().
32931 * g_socket_get_multicast_loopback:
32932 * @socket: a #GSocket.
32934 * Gets the multicast loopback setting on @socket; if %TRUE (the
32935 * default), outgoing multicast packets will be looped back to
32936 * multicast listeners on the same host.
32938 * Returns: the multicast loopback setting on @socket
32944 * g_socket_get_multicast_ttl:
32945 * @socket: a #GSocket.
32947 * Gets the multicast time-to-live setting on @socket; see
32948 * g_socket_set_multicast_ttl() for more details.
32950 * Returns: the multicast time-to-live setting on @socket
32956 * g_socket_get_option:
32957 * @socket: a #GSocket
32958 * @level: the "API level" of the option (eg, `SOL_SOCKET`)
32959 * @optname: the "name" of the option (eg, `SO_BROADCAST`)
32960 * @value: (out): return location for the option value
32961 * @error: #GError for error reporting, or %NULL to ignore.
32963 * Gets the value of an integer-valued option on @socket, as with
32964 * getsockopt(). (If you need to fetch a non-integer-valued option,
32965 * you will need to call getsockopt() directly.)
32967 * The [<gio/gnetworking.h>][gio-gnetworking.h]
32968 * header pulls in system headers that will define most of the
32969 * standard/portable socket options. For unusual socket protocols or
32970 * platform-dependent options, you may need to include additional
32973 * Note that even for socket options that are a single byte in size,
32974 * @value is still a pointer to a #gint variable, not a #guchar;
32975 * g_socket_get_option() will handle the conversion internally.
32977 * Returns: success or failure. On failure, @error will be set, and
32978 * the system error value (`errno` or WSAGetLastError()) will still
32979 * be set to the result of the getsockopt() call.
32985 * g_socket_get_protocol:
32986 * @socket: a #GSocket.
32988 * Gets the socket protocol id the socket was created with.
32989 * In case the protocol is unknown, -1 is returned.
32991 * Returns: a protocol id, or -1 if unknown
32997 * g_socket_get_remote_address:
32998 * @socket: a #GSocket.
32999 * @error: #GError for error reporting, or %NULL to ignore.
33001 * Try to get the remove address of a connected socket. This is only
33002 * useful for connection oriented sockets that have been connected.
33004 * Returns: (transfer full): a #GSocketAddress or %NULL on error.
33005 * Free the returned object with g_object_unref().
33011 * g_socket_get_socket_type:
33012 * @socket: a #GSocket.
33014 * Gets the socket type of the socket.
33016 * Returns: a #GSocketType
33022 * g_socket_get_timeout:
33023 * @socket: a #GSocket.
33025 * Gets the timeout setting of the socket. For details on this, see
33026 * g_socket_set_timeout().
33028 * Returns: the timeout in seconds
33034 * g_socket_get_ttl:
33035 * @socket: a #GSocket.
33037 * Gets the unicast time-to-live setting on @socket; see
33038 * g_socket_set_ttl() for more details.
33040 * Returns: the time-to-live setting on @socket
33046 * g_socket_is_closed:
33047 * @socket: a #GSocket
33049 * Checks whether a socket is closed.
33051 * Returns: %TRUE if socket is closed, %FALSE otherwise
33057 * g_socket_is_connected:
33058 * @socket: a #GSocket.
33060 * Check whether the socket is connected. This is only useful for
33061 * connection-oriented sockets.
33063 * Returns: %TRUE if socket is connected, %FALSE otherwise.
33069 * g_socket_join_multicast_group:
33070 * @socket: a #GSocket.
33071 * @group: a #GInetAddress specifying the group address to join.
33072 * @iface: (allow-none): Name of the interface to use, or %NULL
33073 * @source_specific: %TRUE if source-specific multicast should be used
33074 * @error: #GError for error reporting, or %NULL to ignore.
33076 * Registers @socket to receive multicast messages sent to @group.
33077 * @socket must be a %G_SOCKET_TYPE_DATAGRAM socket, and must have
33078 * been bound to an appropriate interface and port with
33081 * If @iface is %NULL, the system will automatically pick an interface
33082 * to bind to based on @group.
33084 * If @source_specific is %TRUE, source-specific multicast as defined
33085 * in RFC 4604 is used. Note that on older platforms this may fail
33086 * with a %G_IO_ERROR_NOT_SUPPORTED error.
33088 * Returns: %TRUE on success, %FALSE on error.
33094 * g_socket_leave_multicast_group:
33095 * @socket: a #GSocket.
33096 * @group: a #GInetAddress specifying the group address to leave.
33097 * @iface: (allow-none): Interface used
33098 * @source_specific: %TRUE if source-specific multicast was used
33099 * @error: #GError for error reporting, or %NULL to ignore.
33101 * Removes @socket from the multicast group defined by @group, @iface,
33102 * and @source_specific (which must all have the same values they had
33103 * when you joined the group).
33105 * @socket remains bound to its address and port, and can still receive
33106 * unicast messages after calling this.
33108 * Returns: %TRUE on success, %FALSE on error.
33115 * @socket: a #GSocket.
33116 * @error: #GError for error reporting, or %NULL to ignore.
33118 * Marks the socket as a server socket, i.e. a socket that is used
33119 * to accept incoming requests using g_socket_accept().
33121 * Before calling this the socket must be bound to a local address using
33124 * To set the maximum amount of outstanding clients, use
33125 * g_socket_set_listen_backlog().
33127 * Returns: %TRUE on success, %FALSE on error.
33133 * g_socket_listener_accept:
33134 * @listener: a #GSocketListener
33135 * @source_object: (out) (transfer none) (allow-none): location where #GObject pointer will be stored, or %NULL
33136 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
33137 * @error: #GError for error reporting, or %NULL to ignore.
33139 * Blocks waiting for a client to connect to any of the sockets added
33140 * to the listener. Returns a #GSocketConnection for the socket that was
33143 * If @source_object is not %NULL it will be filled out with the source
33144 * object specified when the corresponding socket or address was added
33147 * If @cancellable is not %NULL, then the operation can be cancelled by
33148 * triggering the cancellable object from another thread. If the operation
33149 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
33151 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
33157 * g_socket_listener_accept_async:
33158 * @listener: a #GSocketListener
33159 * @cancellable: (allow-none): a #GCancellable, or %NULL
33160 * @callback: (scope async): a #GAsyncReadyCallback
33161 * @user_data: (closure): user data for the callback
33163 * This is the asynchronous version of g_socket_listener_accept().
33165 * When the operation is finished @callback will be
33166 * called. You can then call g_socket_listener_accept_socket()
33167 * to get the result of the operation.
33174 * g_socket_listener_accept_finish:
33175 * @listener: a #GSocketListener
33176 * @result: a #GAsyncResult.
33177 * @source_object: (out) (transfer none) (allow-none): Optional #GObject identifying this source
33178 * @error: a #GError location to store the error occurring, or %NULL to
33181 * Finishes an async accept operation. See g_socket_listener_accept_async()
33183 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
33189 * g_socket_listener_accept_socket:
33190 * @listener: a #GSocketListener
33191 * @source_object: (out) (transfer none) (allow-none): location where #GObject pointer will be stored, or %NULL.
33192 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
33193 * @error: #GError for error reporting, or %NULL to ignore.
33195 * Blocks waiting for a client to connect to any of the sockets added
33196 * to the listener. Returns the #GSocket that was accepted.
33198 * If you want to accept the high-level #GSocketConnection, not a #GSocket,
33199 * which is often the case, then you should use g_socket_listener_accept()
33202 * If @source_object is not %NULL it will be filled out with the source
33203 * object specified when the corresponding socket or address was added
33206 * If @cancellable is not %NULL, then the operation can be cancelled by
33207 * triggering the cancellable object from another thread. If the operation
33208 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
33210 * Returns: (transfer full): a #GSocket on success, %NULL on error.
33216 * g_socket_listener_accept_socket_async:
33217 * @listener: a #GSocketListener
33218 * @cancellable: (allow-none): a #GCancellable, or %NULL
33219 * @callback: (scope async): a #GAsyncReadyCallback
33220 * @user_data: (closure): user data for the callback
33222 * This is the asynchronous version of g_socket_listener_accept_socket().
33224 * When the operation is finished @callback will be
33225 * called. You can then call g_socket_listener_accept_socket_finish()
33226 * to get the result of the operation.
33233 * g_socket_listener_accept_socket_finish:
33234 * @listener: a #GSocketListener
33235 * @result: a #GAsyncResult.
33236 * @source_object: (out) (transfer none) (allow-none): Optional #GObject identifying this source
33237 * @error: a #GError location to store the error occurring, or %NULL to
33240 * Finishes an async accept operation. See g_socket_listener_accept_socket_async()
33242 * Returns: (transfer full): a #GSocket on success, %NULL on error.
33248 * g_socket_listener_add_address:
33249 * @listener: a #GSocketListener
33250 * @address: a #GSocketAddress
33251 * @type: a #GSocketType
33252 * @protocol: a #GSocketProtocol
33253 * @source_object: (allow-none): Optional #GObject identifying this source
33254 * @effective_address: (out) (allow-none): location to store the address that was bound to, or %NULL.
33255 * @error: #GError for error reporting, or %NULL to ignore.
33257 * Creates a socket of type @type and protocol @protocol, binds
33258 * it to @address and adds it to the set of sockets we're accepting
33261 * Note that adding an IPv6 address, depending on the platform,
33262 * may or may not result in a listener that also accepts IPv4
33263 * connections. For more deterministic behavior, see
33264 * g_socket_listener_add_inet_port().
33266 * @source_object will be passed out in the various calls
33267 * to accept to identify this particular source, which is
33268 * useful if you're listening on multiple addresses and do
33269 * different things depending on what address is connected to.
33271 * If successful and @effective_address is non-%NULL then it will
33272 * be set to the address that the binding actually occurred at. This
33273 * is helpful for determining the port number that was used for when
33274 * requesting a binding to port 0 (ie: "any port"). This address, if
33275 * requested, belongs to the caller and must be freed.
33277 * Returns: %TRUE on success, %FALSE on error.
33283 * g_socket_listener_add_any_inet_port:
33284 * @listener: a #GSocketListener
33285 * @source_object: (allow-none): Optional #GObject identifying this source
33286 * @error: a #GError location to store the error occurring, or %NULL to
33289 * Listens for TCP connections on any available port number for both
33290 * IPv6 and IPv4 (if each is available).
33292 * This is useful if you need to have a socket for incoming connections
33293 * but don't care about the specific port number.
33295 * @source_object will be passed out in the various calls
33296 * to accept to identify this particular source, which is
33297 * useful if you're listening on multiple addresses and do
33298 * different things depending on what address is connected to.
33300 * Returns: the port number, or 0 in case of failure.
33306 * g_socket_listener_add_inet_port:
33307 * @listener: a #GSocketListener
33308 * @port: an IP port number (non-zero)
33309 * @source_object: (allow-none): Optional #GObject identifying this source
33310 * @error: #GError for error reporting, or %NULL to ignore.
33312 * Helper function for g_socket_listener_add_address() that
33313 * creates a TCP/IP socket listening on IPv4 and IPv6 (if
33314 * supported) on the specified port on all interfaces.
33316 * @source_object will be passed out in the various calls
33317 * to accept to identify this particular source, which is
33318 * useful if you're listening on multiple addresses and do
33319 * different things depending on what address is connected to.
33321 * Returns: %TRUE on success, %FALSE on error.
33327 * g_socket_listener_add_socket:
33328 * @listener: a #GSocketListener
33329 * @socket: a listening #GSocket
33330 * @source_object: (allow-none): Optional #GObject identifying this source
33331 * @error: #GError for error reporting, or %NULL to ignore.
33333 * Adds @socket to the set of sockets that we try to accept
33334 * new clients from. The socket must be bound to a local
33335 * address and listened to.
33337 * @source_object will be passed out in the various calls
33338 * to accept to identify this particular source, which is
33339 * useful if you're listening on multiple addresses and do
33340 * different things depending on what address is connected to.
33342 * The @socket will not be automatically closed when the @listener is finalized
33343 * unless the listener held the final reference to the socket. Before GLib 2.42,
33344 * the @socket was automatically closed on finalization of the @listener, even
33345 * if references to it were held elsewhere.
33347 * Returns: %TRUE on success, %FALSE on error.
33353 * g_socket_listener_close:
33354 * @listener: a #GSocketListener
33356 * Closes all the sockets in the listener.
33363 * g_socket_listener_new:
33365 * Creates a new #GSocketListener with no sockets to listen for.
33366 * New listeners can be added with e.g. g_socket_listener_add_address()
33367 * or g_socket_listener_add_inet_port().
33369 * Returns: a new #GSocketListener.
33375 * g_socket_listener_set_backlog:
33376 * @listener: a #GSocketListener
33377 * @listen_backlog: an integer
33379 * Sets the listen backlog on the sockets in the listener.
33381 * See g_socket_set_listen_backlog() for details
33389 * @family: the socket family to use, e.g. %G_SOCKET_FAMILY_IPV4.
33390 * @type: the socket type to use.
33391 * @protocol: the id of the protocol to use, or 0 for default.
33392 * @error: #GError for error reporting, or %NULL to ignore.
33394 * Creates a new #GSocket with the defined family, type and protocol.
33395 * If @protocol is 0 (%G_SOCKET_PROTOCOL_DEFAULT) the default protocol type
33396 * for the family and type is used.
33398 * The @protocol is a family and type specific int that specifies what
33399 * kind of protocol to use. #GSocketProtocol lists several common ones.
33400 * Many families only support one protocol, and use 0 for this, others
33401 * support several and using 0 means to use the default protocol for
33402 * the family and type.
33404 * The protocol id is passed directly to the operating
33405 * system, so you can use protocols not listed in #GSocketProtocol if you
33406 * know the protocol number used for it.
33408 * Returns: a #GSocket or %NULL on error.
33409 * Free the returned object with g_object_unref().
33415 * g_socket_new_from_fd:
33416 * @fd: a native socket file descriptor.
33417 * @error: #GError for error reporting, or %NULL to ignore.
33419 * Creates a new #GSocket from a native file descriptor
33420 * or winsock SOCKET handle.
33422 * This reads all the settings from the file descriptor so that
33423 * all properties should work. Note that the file descriptor
33424 * will be set to non-blocking mode, independent on the blocking
33425 * mode of the #GSocket.
33427 * Returns: a #GSocket or %NULL on error.
33428 * Free the returned object with g_object_unref().
33434 * g_socket_receive:
33435 * @socket: a #GSocket
33436 * @buffer: (array length=size) (element-type guint8): a buffer to
33437 * read data into (which should be at least @size bytes long).
33438 * @size: the number of bytes you want to read from the socket
33439 * @cancellable: (allow-none): a %GCancellable or %NULL
33440 * @error: #GError for error reporting, or %NULL to ignore.
33442 * Receive data (up to @size bytes) from a socket. This is mainly used by
33443 * connection-oriented sockets; it is identical to g_socket_receive_from()
33444 * with @address set to %NULL.
33446 * For %G_SOCKET_TYPE_DATAGRAM and %G_SOCKET_TYPE_SEQPACKET sockets,
33447 * g_socket_receive() will always read either 0 or 1 complete messages from
33448 * the socket. If the received message is too large to fit in @buffer, then
33449 * the data beyond @size bytes will be discarded, without any explicit
33450 * indication that this has occurred.
33452 * For %G_SOCKET_TYPE_STREAM sockets, g_socket_receive() can return any
33453 * number of bytes, up to @size. If more than @size bytes have been
33454 * received, the additional data will be returned in future calls to
33455 * g_socket_receive().
33457 * If the socket is in blocking mode the call will block until there
33458 * is some data to receive, the connection is closed, or there is an
33459 * error. If there is no data available and the socket is in
33460 * non-blocking mode, a %G_IO_ERROR_WOULD_BLOCK error will be
33461 * returned. To be notified when data is available, wait for the
33462 * %G_IO_IN condition.
33464 * On error -1 is returned and @error is set accordingly.
33466 * Returns: Number of bytes read, or 0 if the connection was closed by
33467 * the peer, or -1 on error
33473 * g_socket_receive_from:
33474 * @socket: a #GSocket
33475 * @address: (out) (allow-none): a pointer to a #GSocketAddress
33476 * pointer, or %NULL
33477 * @buffer: (array length=size) (element-type guint8): a buffer to
33478 * read data into (which should be at least @size bytes long).
33479 * @size: the number of bytes you want to read from the socket
33480 * @cancellable: (allow-none): a %GCancellable or %NULL
33481 * @error: #GError for error reporting, or %NULL to ignore.
33483 * Receive data (up to @size bytes) from a socket.
33485 * If @address is non-%NULL then @address will be set equal to the
33486 * source address of the received packet.
33487 * @address is owned by the caller.
33489 * See g_socket_receive() for additional information.
33491 * Returns: Number of bytes read, or 0 if the connection was closed by
33492 * the peer, or -1 on error
33498 * g_socket_receive_message:
33499 * @socket: a #GSocket
33500 * @address: (out) (allow-none): a pointer to a #GSocketAddress
33501 * pointer, or %NULL
33502 * @vectors: (array length=num_vectors): an array of #GInputVector structs
33503 * @num_vectors: the number of elements in @vectors, or -1
33504 * @messages: (array length=num_messages) (allow-none): a pointer which
33505 * may be filled with an array of #GSocketControlMessages, or %NULL
33506 * @num_messages: a pointer which will be filled with the number of
33507 * elements in @messages, or %NULL
33508 * @flags: a pointer to an int containing #GSocketMsgFlags flags
33509 * @cancellable: (allow-none): a %GCancellable or %NULL
33510 * @error: a #GError pointer, or %NULL
33512 * Receive data from a socket. This is the most complicated and
33513 * fully-featured version of this call. For easier use, see
33514 * g_socket_receive() and g_socket_receive_from().
33516 * If @address is non-%NULL then @address will be set equal to the
33517 * source address of the received packet.
33518 * @address is owned by the caller.
33520 * @vector must point to an array of #GInputVector structs and
33521 * @num_vectors must be the length of this array. These structs
33522 * describe the buffers that received data will be scattered into.
33523 * If @num_vectors is -1, then @vectors is assumed to be terminated
33524 * by a #GInputVector with a %NULL buffer pointer.
33526 * As a special case, if @num_vectors is 0 (in which case, @vectors
33527 * may of course be %NULL), then a single byte is received and
33528 * discarded. This is to facilitate the common practice of sending a
33529 * single '\0' byte for the purposes of transferring ancillary data.
33531 * @messages, if non-%NULL, will be set to point to a newly-allocated
33532 * array of #GSocketControlMessage instances or %NULL if no such
33533 * messages was received. These correspond to the control messages
33534 * received from the kernel, one #GSocketControlMessage per message
33535 * from the kernel. This array is %NULL-terminated and must be freed
33536 * by the caller using g_free() after calling g_object_unref() on each
33537 * element. If @messages is %NULL, any control messages received will
33540 * @num_messages, if non-%NULL, will be set to the number of control
33541 * messages received.
33543 * If both @messages and @num_messages are non-%NULL, then
33544 * @num_messages gives the number of #GSocketControlMessage instances
33545 * in @messages (ie: not including the %NULL terminator).
33547 * @flags is an in/out parameter. The commonly available arguments
33548 * for this are available in the #GSocketMsgFlags enum, but the
33549 * values there are the same as the system values, and the flags
33550 * are passed in as-is, so you can pass in system-specific flags too
33551 * (and g_socket_receive_message() may pass system-specific flags out).
33553 * As with g_socket_receive(), data may be discarded if @socket is
33554 * %G_SOCKET_TYPE_DATAGRAM or %G_SOCKET_TYPE_SEQPACKET and you do not
33555 * provide enough buffer space to read a complete message. You can pass
33556 * %G_SOCKET_MSG_PEEK in @flags to peek at the current message without
33557 * removing it from the receive queue, but there is no portable way to find
33558 * out the length of the message other than by reading it into a
33559 * sufficiently-large buffer.
33561 * If the socket is in blocking mode the call will block until there
33562 * is some data to receive, the connection is closed, or there is an
33563 * error. If there is no data available and the socket is in
33564 * non-blocking mode, a %G_IO_ERROR_WOULD_BLOCK error will be
33565 * returned. To be notified when data is available, wait for the
33566 * %G_IO_IN condition.
33568 * On error -1 is returned and @error is set accordingly.
33570 * Returns: Number of bytes read, or 0 if the connection was closed by
33571 * the peer, or -1 on error
33577 * g_socket_receive_with_blocking:
33578 * @socket: a #GSocket
33579 * @buffer: (array length=size) (element-type guint8): a buffer to
33580 * read data into (which should be at least @size bytes long).
33581 * @size: the number of bytes you want to read from the socket
33582 * @blocking: whether to do blocking or non-blocking I/O
33583 * @cancellable: (allow-none): a %GCancellable or %NULL
33584 * @error: #GError for error reporting, or %NULL to ignore.
33586 * This behaves exactly the same as g_socket_receive(), except that
33587 * the choice of blocking or non-blocking behavior is determined by
33588 * the @blocking argument rather than by @socket's properties.
33590 * Returns: Number of bytes read, or 0 if the connection was closed by
33591 * the peer, or -1 on error
33598 * @socket: a #GSocket
33599 * @buffer: (array length=size) (element-type guint8): the buffer
33600 * containing the data to send.
33601 * @size: the number of bytes to send
33602 * @cancellable: (allow-none): a %GCancellable or %NULL
33603 * @error: #GError for error reporting, or %NULL to ignore.
33605 * Tries to send @size bytes from @buffer on the socket. This is
33606 * mainly used by connection-oriented sockets; it is identical to
33607 * g_socket_send_to() with @address set to %NULL.
33609 * If the socket is in blocking mode the call will block until there is
33610 * space for the data in the socket queue. If there is no space available
33611 * and the socket is in non-blocking mode a %G_IO_ERROR_WOULD_BLOCK error
33612 * will be returned. To be notified when space is available, wait for the
33613 * %G_IO_OUT condition. Note though that you may still receive
33614 * %G_IO_ERROR_WOULD_BLOCK from g_socket_send() even if you were previously
33615 * notified of a %G_IO_OUT condition. (On Windows in particular, this is
33616 * very common due to the way the underlying APIs work.)
33618 * On error -1 is returned and @error is set accordingly.
33620 * Returns: Number of bytes written (which may be less than @size), or -1
33627 * g_socket_send_message:
33628 * @socket: a #GSocket
33629 * @address: (allow-none): a #GSocketAddress, or %NULL
33630 * @vectors: (array length=num_vectors): an array of #GOutputVector structs
33631 * @num_vectors: the number of elements in @vectors, or -1
33632 * @messages: (array length=num_messages) (allow-none): a pointer to an
33633 * array of #GSocketControlMessages, or %NULL.
33634 * @num_messages: number of elements in @messages, or -1.
33635 * @flags: an int containing #GSocketMsgFlags flags
33636 * @cancellable: (allow-none): a %GCancellable or %NULL
33637 * @error: #GError for error reporting, or %NULL to ignore.
33639 * Send data to @address on @socket. This is the most complicated and
33640 * fully-featured version of this call. For easier use, see
33641 * g_socket_send() and g_socket_send_to().
33643 * If @address is %NULL then the message is sent to the default receiver
33644 * (set by g_socket_connect()).
33646 * @vectors must point to an array of #GOutputVector structs and
33647 * @num_vectors must be the length of this array. (If @num_vectors is -1,
33648 * then @vectors is assumed to be terminated by a #GOutputVector with a
33649 * %NULL buffer pointer.) The #GOutputVector structs describe the buffers
33650 * that the sent data will be gathered from. Using multiple
33651 * #GOutputVectors is more memory-efficient than manually copying
33652 * data from multiple sources into a single buffer, and more
33653 * network-efficient than making multiple calls to g_socket_send().
33655 * @messages, if non-%NULL, is taken to point to an array of @num_messages
33656 * #GSocketControlMessage instances. These correspond to the control
33657 * messages to be sent on the socket.
33658 * If @num_messages is -1 then @messages is treated as a %NULL-terminated
33661 * @flags modify how the message is sent. The commonly available arguments
33662 * for this are available in the #GSocketMsgFlags enum, but the
33663 * values there are the same as the system values, and the flags
33664 * are passed in as-is, so you can pass in system-specific flags too.
33666 * If the socket is in blocking mode the call will block until there is
33667 * space for the data in the socket queue. If there is no space available
33668 * and the socket is in non-blocking mode a %G_IO_ERROR_WOULD_BLOCK error
33669 * will be returned. To be notified when space is available, wait for the
33670 * %G_IO_OUT condition. Note though that you may still receive
33671 * %G_IO_ERROR_WOULD_BLOCK from g_socket_send() even if you were previously
33672 * notified of a %G_IO_OUT condition. (On Windows in particular, this is
33673 * very common due to the way the underlying APIs work.)
33675 * On error -1 is returned and @error is set accordingly.
33677 * Returns: Number of bytes written (which may be less than @size), or -1
33684 * g_socket_send_to:
33685 * @socket: a #GSocket
33686 * @address: (allow-none): a #GSocketAddress, or %NULL
33687 * @buffer: (array length=size) (element-type guint8): the buffer
33688 * containing the data to send.
33689 * @size: the number of bytes to send
33690 * @cancellable: (allow-none): a %GCancellable or %NULL
33691 * @error: #GError for error reporting, or %NULL to ignore.
33693 * Tries to send @size bytes from @buffer to @address. If @address is
33694 * %NULL then the message is sent to the default receiver (set by
33695 * g_socket_connect()).
33697 * See g_socket_send() for additional information.
33699 * Returns: Number of bytes written (which may be less than @size), or -1
33706 * g_socket_send_with_blocking:
33707 * @socket: a #GSocket
33708 * @buffer: (array length=size) (element-type guint8): the buffer
33709 * containing the data to send.
33710 * @size: the number of bytes to send
33711 * @blocking: whether to do blocking or non-blocking I/O
33712 * @cancellable: (allow-none): a %GCancellable or %NULL
33713 * @error: #GError for error reporting, or %NULL to ignore.
33715 * This behaves exactly the same as g_socket_send(), except that
33716 * the choice of blocking or non-blocking behavior is determined by
33717 * the @blocking argument rather than by @socket's properties.
33719 * Returns: Number of bytes written (which may be less than @size), or -1
33726 * g_socket_service_is_active:
33727 * @service: a #GSocketService
33729 * Check whether the service is active or not. An active
33730 * service will accept new clients that connect, while
33731 * a non-active service will let connecting clients queue
33732 * up until the service is started.
33734 * Returns: %TRUE if the service is active, %FALSE otherwise
33740 * g_socket_service_new:
33742 * Creates a new #GSocketService with no sockets to listen for.
33743 * New listeners can be added with e.g. g_socket_listener_add_address()
33744 * or g_socket_listener_add_inet_port().
33746 * Returns: a new #GSocketService.
33752 * g_socket_service_start:
33753 * @service: a #GSocketService
33755 * Starts the service, i.e. start accepting connections
33756 * from the added sockets when the mainloop runs.
33758 * This call is thread-safe, so it may be called from a thread
33759 * handling an incoming client request.
33766 * g_socket_service_stop:
33767 * @service: a #GSocketService
33769 * Stops the service, i.e. stops accepting connections
33770 * from the added sockets when the mainloop runs.
33772 * This call is thread-safe, so it may be called from a thread
33773 * handling an incoming client request.
33775 * Note that this only stops accepting new connections; it does not
33776 * close the listening sockets, and you can call
33777 * g_socket_service_start() again later to begin listening again. To
33778 * close the listening sockets, call g_socket_listener_close(). (This
33779 * will happen automatically when the #GSocketService is finalized.)
33786 * g_socket_set_blocking:
33787 * @socket: a #GSocket.
33788 * @blocking: Whether to use blocking I/O or not.
33790 * Sets the blocking mode of the socket. In blocking mode
33791 * all operations block until they succeed or there is an error. In
33792 * non-blocking mode all functions return results immediately or
33793 * with a %G_IO_ERROR_WOULD_BLOCK error.
33795 * All sockets are created in blocking mode. However, note that the
33796 * platform level socket is always non-blocking, and blocking mode
33797 * is a GSocket level feature.
33804 * g_socket_set_broadcast:
33805 * @socket: a #GSocket.
33806 * @broadcast: whether @socket should allow sending to broadcast
33809 * Sets whether @socket should allow sending to broadcast addresses.
33810 * This is %FALSE by default.
33817 * g_socket_set_keepalive:
33818 * @socket: a #GSocket.
33819 * @keepalive: Value for the keepalive flag
33821 * Sets or unsets the %SO_KEEPALIVE flag on the underlying socket. When
33822 * this flag is set on a socket, the system will attempt to verify that the
33823 * remote socket endpoint is still present if a sufficiently long period of
33824 * time passes with no data being exchanged. If the system is unable to
33825 * verify the presence of the remote endpoint, it will automatically close
33828 * This option is only functional on certain kinds of sockets. (Notably,
33829 * %G_SOCKET_PROTOCOL_TCP sockets.)
33831 * The exact time between pings is system- and protocol-dependent, but will
33832 * normally be at least two hours. Most commonly, you would set this flag
33833 * on a server socket if you want to allow clients to remain idle for long
33834 * periods of time, but also want to ensure that connections are eventually
33835 * garbage-collected if clients crash or become unreachable.
33842 * g_socket_set_listen_backlog:
33843 * @socket: a #GSocket.
33844 * @backlog: the maximum number of pending connections.
33846 * Sets the maximum number of outstanding connections allowed
33847 * when listening on this socket. If more clients than this are
33848 * connecting to the socket and the application is not handling them
33849 * on time then the new connections will be refused.
33851 * Note that this must be called before g_socket_listen() and has no
33852 * effect if called after that.
33859 * g_socket_set_multicast_loopback:
33860 * @socket: a #GSocket.
33861 * @loopback: whether @socket should receive messages sent to its
33862 * multicast groups from the local host
33864 * Sets whether outgoing multicast packets will be received by sockets
33865 * listening on that multicast address on the same host. This is %TRUE
33873 * g_socket_set_multicast_ttl:
33874 * @socket: a #GSocket.
33875 * @ttl: the time-to-live value for all multicast datagrams on @socket
33877 * Sets the time-to-live for outgoing multicast datagrams on @socket.
33878 * By default, this is 1, meaning that multicast packets will not leave
33879 * the local network.
33886 * g_socket_set_option:
33887 * @socket: a #GSocket
33888 * @level: the "API level" of the option (eg, `SOL_SOCKET`)
33889 * @optname: the "name" of the option (eg, `SO_BROADCAST`)
33890 * @value: the value to set the option to
33891 * @error: #GError for error reporting, or %NULL to ignore.
33893 * Sets the value of an integer-valued option on @socket, as with
33894 * setsockopt(). (If you need to set a non-integer-valued option,
33895 * you will need to call setsockopt() directly.)
33897 * The [<gio/gnetworking.h>][gio-gnetworking.h]
33898 * header pulls in system headers that will define most of the
33899 * standard/portable socket options. For unusual socket protocols or
33900 * platform-dependent options, you may need to include additional
33903 * Returns: success or failure. On failure, @error will be set, and
33904 * the system error value (`errno` or WSAGetLastError()) will still
33905 * be set to the result of the setsockopt() call.
33911 * g_socket_set_timeout:
33912 * @socket: a #GSocket.
33913 * @timeout: the timeout for @socket, in seconds, or 0 for none
33915 * Sets the time in seconds after which I/O operations on @socket will
33916 * time out if they have not yet completed.
33918 * On a blocking socket, this means that any blocking #GSocket
33919 * operation will time out after @timeout seconds of inactivity,
33920 * returning %G_IO_ERROR_TIMED_OUT.
33922 * On a non-blocking socket, calls to g_socket_condition_wait() will
33923 * also fail with %G_IO_ERROR_TIMED_OUT after the given time. Sources
33924 * created with g_socket_create_source() will trigger after
33925 * @timeout seconds of inactivity, with the requested condition
33926 * set, at which point calling g_socket_receive(), g_socket_send(),
33927 * g_socket_check_connect_result(), etc, will fail with
33928 * %G_IO_ERROR_TIMED_OUT.
33930 * If @timeout is 0 (the default), operations will never time out
33933 * Note that if an I/O operation is interrupted by a signal, this may
33934 * cause the timeout to be reset.
33941 * g_socket_set_ttl:
33942 * @socket: a #GSocket.
33943 * @ttl: the time-to-live value for all unicast packets on @socket
33945 * Sets the time-to-live for outgoing unicast packets on @socket.
33946 * By default the platform-specific default value is used.
33953 * g_socket_shutdown:
33954 * @socket: a #GSocket
33955 * @shutdown_read: whether to shut down the read side
33956 * @shutdown_write: whether to shut down the write side
33957 * @error: #GError for error reporting, or %NULL to ignore.
33959 * Shut down part of a full-duplex connection.
33961 * If @shutdown_read is %TRUE then the receiving side of the connection
33962 * is shut down, and further reading is disallowed.
33964 * If @shutdown_write is %TRUE then the sending side of the connection
33965 * is shut down, and further writing is disallowed.
33967 * It is allowed for both @shutdown_read and @shutdown_write to be %TRUE.
33969 * One example where this is used is graceful disconnect for TCP connections
33970 * where you close the sending side, then wait for the other side to close
33971 * the connection, thus ensuring that the other side saw all sent data.
33973 * Returns: %TRUE on success, %FALSE on error
33979 * g_socket_speaks_ipv4:
33980 * @socket: a #GSocket
33982 * Checks if a socket is capable of speaking IPv4.
33984 * IPv4 sockets are capable of speaking IPv4. On some operating systems
33985 * and under some combinations of circumstances IPv6 sockets are also
33986 * capable of speaking IPv4. See RFC 3493 section 3.7 for more
33989 * No other types of sockets are currently considered as being capable
33990 * of speaking IPv4.
33992 * Returns: %TRUE if this socket can be used with IPv4.
33998 * g_srv_target_copy:
33999 * @target: a #GSrvTarget
34003 * Returns: a copy of @target
34009 * g_srv_target_free:
34010 * @target: a #GSrvTarget
34019 * g_srv_target_get_hostname:
34020 * @target: a #GSrvTarget
34022 * Gets @target's hostname (in ASCII form; if you are going to present
34023 * this to the user, you should use g_hostname_is_ascii_encoded() to
34024 * check if it contains encoded Unicode segments, and use
34025 * g_hostname_to_unicode() to convert it if it does.)
34027 * Returns: @target's hostname
34033 * g_srv_target_get_port:
34034 * @target: a #GSrvTarget
34036 * Gets @target's port
34038 * Returns: @target's port
34044 * g_srv_target_get_priority:
34045 * @target: a #GSrvTarget
34047 * Gets @target's priority. You should not need to look at this;
34048 * #GResolver already sorts the targets according to the algorithm in
34051 * Returns: @target's priority
34057 * g_srv_target_get_weight:
34058 * @target: a #GSrvTarget
34060 * Gets @target's weight. You should not need to look at this;
34061 * #GResolver already sorts the targets according to the algorithm in
34064 * Returns: @target's weight
34070 * g_srv_target_list_sort: (skip)
34071 * @targets: a #GList of #GSrvTarget
34073 * Sorts @targets in place according to the algorithm in RFC 2782.
34075 * Returns: (transfer full): the head of the sorted list.
34081 * g_srv_target_new:
34082 * @hostname: the host that the service is running on
34083 * @port: the port that the service is running on
34084 * @priority: the target's priority
34085 * @weight: the target's weight
34087 * Creates a new #GSrvTarget with the given parameters.
34089 * You should not need to use this; normally #GSrvTargets are
34090 * created by #GResolver.
34092 * Returns: a new #GSrvTarget.
34098 * g_static_resource_fini:
34099 * @static_resource: pointer to a static #GStaticResource
34101 * Finalized a GResource initialized by g_static_resource_init().
34103 * This is normally used by code generated by
34104 * [glib-compile-resources][glib-compile-resources]
34105 * and is not typically used by other code.
34112 * g_static_resource_get_resource:
34113 * @static_resource: pointer to a static #GStaticResource
34115 * Gets the GResource that was registered by a call to g_static_resource_init().
34117 * This is normally used by code generated by
34118 * [glib-compile-resources][glib-compile-resources]
34119 * and is not typically used by other code.
34121 * Returns: (transfer none): a #GResource
34127 * g_static_resource_init:
34128 * @static_resource: pointer to a static #GStaticResource
34130 * Initializes a GResource from static data using a
34133 * This is normally used by code generated by
34134 * [glib-compile-resources][glib-compile-resources]
34135 * and is not typically used by other code.
34142 * g_subprocess_communicate:
34143 * @subprocess: a #GSubprocess
34144 * @stdin_buf: (allow-none): data to send to the stdin of the subprocess, or %NULL
34145 * @cancellable: a #GCancellable
34146 * @stdout_buf: (out): data read from the subprocess stdout
34147 * @stderr_buf: (out): data read from the subprocess stderr
34148 * @error: a pointer to a %NULL #GError pointer, or %NULL
34150 * Communicate with the subprocess until it terminates, and all input
34151 * and output has been completed.
34153 * If @stdin_buf is given, the subprocess must have been created with
34154 * %G_SUBPROCESS_FLAGS_STDIN_PIPE. The given data is fed to the
34155 * stdin of the subprocess and the pipe is closed (ie: EOF).
34157 * At the same time (as not to cause blocking when dealing with large
34158 * amounts of data), if %G_SUBPROCESS_FLAGS_STDOUT_PIPE or
34159 * %G_SUBPROCESS_FLAGS_STDERR_PIPE were used, reads from those
34160 * streams. The data that was read is returned in @stdout and/or
34163 * If the subprocess was created with %G_SUBPROCESS_FLAGS_STDOUT_PIPE,
34164 * @stdout_buf will contain the data read from stdout. Otherwise, for
34165 * subprocesses not created with %G_SUBPROCESS_FLAGS_STDOUT_PIPE,
34166 * @stdout_buf will be set to %NULL. Similar provisions apply to
34167 * @stderr_buf and %G_SUBPROCESS_FLAGS_STDERR_PIPE.
34169 * As usual, any output variable may be given as %NULL to ignore it.
34171 * If you desire the stdout and stderr data to be interleaved, create
34172 * the subprocess with %G_SUBPROCESS_FLAGS_STDOUT_PIPE and
34173 * %G_SUBPROCESS_FLAGS_STDERR_MERGE. The merged result will be returned
34174 * in @stdout_buf and @stderr_buf will be set to %NULL.
34176 * In case of any error (including cancellation), %FALSE will be
34177 * returned with @error set. Some or all of the stdin data may have
34178 * been written. Any stdout or stderr data that has been read will be
34179 * discarded. None of the out variables (aside from @error) will have
34180 * been set to anything in particular and should not be inspected.
34182 * In the case that %TRUE is returned, the subprocess has exited and the
34183 * exit status inspection APIs (eg: g_subprocess_get_if_exited(),
34184 * g_subprocess_get_exit_status()) may be used.
34186 * You should not attempt to use any of the subprocess pipes after
34187 * starting this function, since they may be left in strange states,
34188 * even if the operation was cancelled. You should especially not
34189 * attempt to interact with the pipes while the operation is in progress
34190 * (either from another thread or if using the asynchronous version).
34192 * Returns: %TRUE if successful
34198 * g_subprocess_communicate_async:
34199 * @subprocess: Self
34200 * @stdin_buf: (allow-none): Input data, or %NULL
34201 * @cancellable: (allow-none): Cancellable
34202 * @callback: Callback
34203 * @user_data: User data
34205 * Asynchronous version of g_subprocess_communicate(). Complete
34206 * invocation with g_subprocess_communicate_finish().
34211 * g_subprocess_communicate_finish:
34212 * @subprocess: Self
34214 * @stdout_buf: (out): Return location for stdout data
34215 * @stderr_buf: (out): Return location for stderr data
34218 * Complete an invocation of g_subprocess_communicate_async().
34223 * g_subprocess_communicate_utf8:
34224 * @subprocess: a #GSubprocess
34225 * @stdin_buf: (allow-none): data to send to the stdin of the subprocess, or %NULL
34226 * @cancellable: a #GCancellable
34227 * @stdout_buf: (out): data read from the subprocess stdout
34228 * @stderr_buf: (out): data read from the subprocess stderr
34229 * @error: a pointer to a %NULL #GError pointer, or %NULL
34231 * Like g_subprocess_communicate(), but validates the output of the
34232 * process as UTF-8, and returns it as a regular NUL terminated string.
34237 * g_subprocess_communicate_utf8_async:
34238 * @subprocess: Self
34239 * @stdin_buf: (allow-none): Input data, or %NULL
34240 * @cancellable: Cancellable
34241 * @callback: Callback
34242 * @user_data: User data
34244 * Asynchronous version of g_subprocess_communicate_utf8(). Complete
34245 * invocation with g_subprocess_communicate_utf8_finish().
34250 * g_subprocess_communicate_utf8_finish:
34251 * @subprocess: Self
34253 * @stdout_buf: (out): Return location for stdout data
34254 * @stderr_buf: (out): Return location for stderr data
34257 * Complete an invocation of g_subprocess_communicate_utf8_async().
34262 * g_subprocess_force_exit:
34263 * @subprocess: a #GSubprocess
34265 * Use an operating-system specific method to attempt an immediate,
34266 * forceful termination of the process. There is no mechanism to
34267 * determine whether or not the request itself was successful;
34268 * however, you can use g_subprocess_wait() to monitor the status of
34269 * the process after calling this function.
34271 * On Unix, this function sends %SIGKILL.
34278 * g_subprocess_get_exit_status:
34279 * @subprocess: a #GSubprocess
34281 * Check the exit status of the subprocess, given that it exited
34282 * normally. This is the value passed to the exit() system call or the
34283 * return value from main.
34285 * This is equivalent to the system WEXITSTATUS macro.
34287 * It is an error to call this function before g_subprocess_wait() and
34288 * unless g_subprocess_get_if_exited() returned %TRUE.
34290 * Returns: the exit status
34296 * g_subprocess_get_identifier:
34297 * @subprocess: a #GSubprocess
34299 * On UNIX, returns the process ID as a decimal string.
34300 * On Windows, returns the result of GetProcessId() also as a string.
34305 * g_subprocess_get_if_exited:
34306 * @subprocess: a #GSubprocess
34308 * Check if the given subprocess exited normally (ie: by way of exit()
34309 * or return from main()).
34311 * This is equivalent to the system WIFEXITED macro.
34313 * It is an error to call this function before g_subprocess_wait() has
34316 * Returns: %TRUE if the case of a normal exit
34322 * g_subprocess_get_if_signaled:
34323 * @subprocess: a #GSubprocess
34325 * Check if the given subprocess terminated in response to a signal.
34327 * This is equivalent to the system WIFSIGNALED macro.
34329 * It is an error to call this function before g_subprocess_wait() has
34332 * Returns: %TRUE if the case of termination due to a signal
34338 * g_subprocess_get_status:
34339 * @subprocess: a #GSubprocess
34341 * Gets the raw status code of the process, as from waitpid().
34343 * This value has no particular meaning, but it can be used with the
34344 * macros defined by the system headers such as WIFEXITED. It can also
34345 * be used with g_spawn_check_exit_status().
34347 * It is more likely that you want to use g_subprocess_get_if_exited()
34348 * followed by g_subprocess_get_exit_status().
34350 * It is an error to call this function before g_subprocess_wait() has
34353 * Returns: the (meaningless) waitpid() exit status from the kernel
34359 * g_subprocess_get_stderr_pipe:
34360 * @subprocess: a #GSubprocess
34362 * Gets the #GInputStream from which to read the stderr output of
34365 * The process must have been created with
34366 * %G_SUBPROCESS_FLAGS_STDERR_PIPE.
34368 * Returns: (transfer none): the stderr pipe
34374 * g_subprocess_get_stdin_pipe:
34375 * @subprocess: a #GSubprocess
34377 * Gets the #GOutputStream that you can write to in order to give data
34378 * to the stdin of @subprocess.
34380 * The process must have been created with
34381 * %G_SUBPROCESS_FLAGS_STDIN_PIPE.
34383 * Returns: (transfer none): the stdout pipe
34389 * g_subprocess_get_stdout_pipe:
34390 * @subprocess: a #GSubprocess
34392 * Gets the #GInputStream from which to read the stdout output of
34395 * The process must have been created with
34396 * %G_SUBPROCESS_FLAGS_STDOUT_PIPE.
34398 * Returns: (transfer none): the stdout pipe
34404 * g_subprocess_get_successful:
34405 * @subprocess: a #GSubprocess
34407 * Checks if the process was "successful". A process is considered
34408 * successful if it exited cleanly with an exit status of 0, either by
34409 * way of the exit() system call or return from main().
34411 * It is an error to call this function before g_subprocess_wait() has
34414 * Returns: %TRUE if the process exited cleanly with a exit status of 0
34420 * g_subprocess_get_term_sig:
34421 * @subprocess: a #GSubprocess
34423 * Get the signal number that caused the subprocess to terminate, given
34424 * that it terminated due to a signal.
34426 * This is equivalent to the system WTERMSIG macro.
34428 * It is an error to call this function before g_subprocess_wait() and
34429 * unless g_subprocess_get_if_signaled() returned %TRUE.
34431 * Returns: the signal causing termination
34437 * g_subprocess_launcher_getenv:
34438 * @self: a #GSubprocess
34439 * @variable: the environment variable to get
34441 * Returns the value of the environment variable @variable in the
34442 * environment of processes launched from this launcher.
34444 * The returned string is in the GLib file name encoding. On UNIX, this
34445 * means that it can be an arbitrary byte string. On Windows, it will
34448 * Returns: the value of the environment variable, %NULL if unset
34454 * g_subprocess_launcher_new:
34455 * @flags: #GSubprocessFlags
34457 * Creates a new #GSubprocessLauncher.
34459 * The launcher is created with the default options. A copy of the
34460 * environment of the calling process is made at the time of this call
34461 * and will be used as the environment that the process is launched in.
34468 * g_subprocess_launcher_set_child_setup:
34469 * @self: a #GSubprocessLauncher
34470 * @child_setup: a #GSpawnChildSetupFunc to use as the child setup function
34471 * @user_data: user data for @child_setup
34472 * @destroy_notify: a #GDestroyNotify for @user_data
34474 * Sets up a child setup function.
34476 * The child setup function will be called after fork() but before
34477 * exec() on the child's side.
34479 * @destroy_notify will not be automatically called on the child's side
34480 * of the fork(). It will only be called when the last reference on the
34481 * #GSubprocessLauncher is dropped or when a new child setup function is
34484 * %NULL can be given as @child_setup to disable the functionality.
34486 * Child setup functions are only available on UNIX.
34493 * g_subprocess_launcher_set_cwd:
34494 * @self: a #GSubprocess
34495 * @cwd: the cwd for launched processes
34497 * Sets the current working directory that processes will be launched
34500 * By default processes are launched with the current working directory
34501 * of the launching process at the time of launch.
34508 * g_subprocess_launcher_set_environ:
34509 * @self: a #GSubprocess
34510 * @env: the replacement environment
34512 * Replace the entire environment of processes launched from this
34513 * launcher with the given 'environ' variable.
34515 * Typically you will build this variable by using g_listenv() to copy
34516 * the process 'environ' and using the functions g_environ_setenv(),
34517 * g_environ_unsetenv(), etc.
34519 * As an alternative, you can use g_subprocess_launcher_setenv(),
34520 * g_subprocess_launcher_unsetenv(), etc.
34522 * All strings in this array are expected to be in the GLib file name
34523 * encoding. On UNIX, this means that they can be arbitrary byte
34524 * strings. On Windows, they should be in UTF-8.
34531 * g_subprocess_launcher_set_flags:
34532 * @self: a #GSubprocessLauncher
34533 * @flags: #GSubprocessFlags
34535 * Sets the flags on the launcher.
34537 * The default flags are %G_SUBPROCESS_FLAGS_NONE.
34539 * You may not set flags that specify conflicting options for how to
34540 * handle a particular stdio stream (eg: specifying both
34541 * %G_SUBPROCESS_FLAGS_STDIN_PIPE and
34542 * %G_SUBPROCESS_FLAGS_STDIN_INHERIT).
34544 * You may also not set a flag that conflicts with a previous call to a
34545 * function like g_subprocess_launcher_set_stdin_file_path() or
34546 * g_subprocess_launcher_take_stdout_fd().
34553 * g_subprocess_launcher_set_stderr_file_path:
34554 * @self: a #GSubprocessLauncher
34555 * @path: a filename or %NULL
34557 * Sets the file path to use as the stderr for spawned processes.
34559 * If @path is %NULL then any previously given path is unset.
34561 * The file will be created or truncated when the process is spawned, as
34562 * would be the case if using '2>' at the shell.
34564 * If you want to send both stdout and stderr to the same file then use
34565 * %G_SUBPROCESS_FLAGS_STDERR_MERGE.
34567 * You may not set a stderr file path if a stderr fd is already set or
34568 * if the launcher flags contain any flags directing stderr elsewhere.
34570 * This feature is only available on UNIX.
34577 * g_subprocess_launcher_set_stdin_file_path:
34578 * @self: a #GSubprocessLauncher
34579 * @path: a filename or %NULL
34581 * Sets the file path to use as the stdin for spawned processes.
34583 * If @path is %NULL then any previously given path is unset.
34585 * The file must exist or spawning the process will fail.
34587 * You may not set a stdin file path if a stdin fd is already set or if
34588 * the launcher flags contain any flags directing stdin elsewhere.
34590 * This feature is only available on UNIX.
34597 * g_subprocess_launcher_set_stdout_file_path:
34598 * @self: a #GSubprocessLauncher
34599 * @path: a filename or %NULL
34601 * Sets the file path to use as the stdout for spawned processes.
34603 * If @path is %NULL then any previously given path is unset.
34605 * The file will be created or truncated when the process is spawned, as
34606 * would be the case if using '>' at the shell.
34608 * You may not set a stdout file path if a stdout fd is already set or
34609 * if the launcher flags contain any flags directing stdout elsewhere.
34611 * This feature is only available on UNIX.
34618 * g_subprocess_launcher_setenv:
34619 * @self: a #GSubprocess
34620 * @variable: the environment variable to set, must not contain '='
34621 * @value: the new value for the variable
34622 * @overwrite: whether to change the variable if it already exists
34624 * Sets the environment variable @variable in the environment of
34625 * processes launched from this launcher.
34627 * Both the variable's name and value should be in the GLib file name
34628 * encoding. On UNIX, this means that they can be arbitrary byte
34629 * strings. On Windows, they should be in UTF-8.
34636 * g_subprocess_launcher_spawn:
34637 * @self: a #GSubprocessLauncher
34639 * @argv0: Command line arguments
34640 * @...: Continued arguments, %NULL terminated
34642 * Creates a #GSubprocess given a provided varargs list of arguments.
34645 * Returns: (transfer full): A new #GSubprocess, or %NULL on error (and @error will be set)
34650 * g_subprocess_launcher_spawnv:
34651 * @self: a #GSubprocessLauncher
34652 * @argv: (array zero-terminated=1) (element-type utf8): Command line arguments
34655 * Creates a #GSubprocess given a provided array of arguments.
34658 * Returns: (transfer full): A new #GSubprocess, or %NULL on error (and @error will be set)
34663 * g_subprocess_launcher_take_fd:
34664 * @self: a #GSubprocessLauncher
34665 * @source_fd: File descriptor in parent process
34666 * @target_fd: Target descriptor for child process
34668 * Transfer an arbitrary file descriptor from parent process to the
34669 * child. This function takes "ownership" of the fd; it will be closed
34670 * in the parent when @self is freed.
34672 * By default, all file descriptors from the parent will be closed.
34673 * This function allows you to create (for example) a custom pipe() or
34674 * socketpair() before launching the process, and choose the target
34675 * descriptor in the child.
34677 * An example use case is GNUPG, which has a command line argument
34678 * --passphrase-fd providing a file descriptor number where it expects
34679 * the passphrase to be written.
34684 * g_subprocess_launcher_take_stderr_fd:
34685 * @self: a #GSubprocessLauncher
34686 * @fd: a file descriptor, or -1
34688 * Sets the file descriptor to use as the stderr for spawned processes.
34690 * If @fd is -1 then any previously given fd is unset.
34692 * Note that the default behaviour is to pass stderr through to the
34693 * stderr of the parent process.
34695 * The passed @fd belongs to the #GSubprocessLauncher. It will be
34696 * automatically closed when the launcher is finalized. The file
34697 * descriptor will also be closed on the child side when executing the
34700 * You may not set a stderr fd if a stderr file path is already set or
34701 * if the launcher flags contain any flags directing stderr elsewhere.
34703 * This feature is only available on UNIX.
34710 * g_subprocess_launcher_take_stdin_fd:
34711 * @self: a #GSubprocessLauncher
34712 * @fd: a file descriptor, or -1
34714 * Sets the file descriptor to use as the stdin for spawned processes.
34716 * If @fd is -1 then any previously given fd is unset.
34718 * Note that if your intention is to have the stdin of the calling
34719 * process inherited by the child then %G_SUBPROCESS_FLAGS_STDIN_INHERIT
34720 * is a better way to go about doing that.
34722 * The passed @fd is noted but will not be touched in the current
34723 * process. It is therefore necessary that it be kept open by the
34724 * caller until the subprocess is spawned. The file descriptor will
34725 * also not be explicitly closed on the child side, so it must be marked
34726 * O_CLOEXEC if that's what you want.
34728 * You may not set a stdin fd if a stdin file path is already set or if
34729 * the launcher flags contain any flags directing stdin elsewhere.
34731 * This feature is only available on UNIX.
34738 * g_subprocess_launcher_take_stdout_fd:
34739 * @self: a #GSubprocessLauncher
34740 * @fd: a file descriptor, or -1
34742 * Sets the file descriptor to use as the stdout for spawned processes.
34744 * If @fd is -1 then any previously given fd is unset.
34746 * Note that the default behaviour is to pass stdout through to the
34747 * stdout of the parent process.
34749 * The passed @fd is noted but will not be touched in the current
34750 * process. It is therefore necessary that it be kept open by the
34751 * caller until the subprocess is spawned. The file descriptor will
34752 * also not be explicitly closed on the child side, so it must be marked
34753 * O_CLOEXEC if that's what you want.
34755 * You may not set a stdout fd if a stdout file path is already set or
34756 * if the launcher flags contain any flags directing stdout elsewhere.
34758 * This feature is only available on UNIX.
34765 * g_subprocess_launcher_unsetenv:
34766 * @self: a #GSubprocess
34767 * @variable: the environment variable to unset, must not contain '='
34769 * Removes the environment variable @variable from the environment of
34770 * processes launched from this launcher.
34772 * The variable name should be in the GLib file name encoding. On UNIX,
34773 * this means that they can be arbitrary byte strings. On Windows, they
34774 * should be in UTF-8.
34781 * g_subprocess_new: (skip)
34782 * @flags: flags that define the behaviour of the subprocess
34783 * @error: (allow-none): return location for an error, or %NULL
34784 * @argv0: first commandline argument to pass to the subprocess
34785 * @...: more commandline arguments, followed by %NULL
34787 * Create a new process with the given flags and varargs argument
34788 * list. By default, matching the g_spawn_async() defaults, the
34789 * child's stdin will be set to the system null device, and
34790 * stdout/stderr will be inherited from the parent. You can use
34791 * @flags to control this behavior.
34793 * The argument list must be terminated with %NULL.
34795 * Returns: A newly created #GSubprocess, or %NULL on error (and @error
34802 * g_subprocess_newv: (rename-to g_subprocess_new)
34803 * @argv: (array zero-terminated=1) (element-type utf8): commandline arguments for the subprocess
34804 * @flags: flags that define the behaviour of the subprocess
34805 * @error: (allow-none): return location for an error, or %NULL
34807 * Create a new process with the given flags and argument list.
34809 * The argument list is expected to be %NULL-terminated.
34811 * Returns: A newly created #GSubprocess, or %NULL on error (and @error
34818 * g_subprocess_send_signal:
34819 * @subprocess: a #GSubprocess
34820 * @signal_num: the signal number to send
34822 * Sends the UNIX signal @signal_num to the subprocess, if it is still
34825 * This API is race-free. If the subprocess has terminated, it will not
34828 * This API is not available on Windows.
34835 * g_subprocess_wait:
34836 * @subprocess: a #GSubprocess
34837 * @cancellable: a #GCancellable
34838 * @error: a #GError
34840 * Synchronously wait for the subprocess to terminate.
34842 * After the process terminates you can query its exit status with
34843 * functions such as g_subprocess_get_if_exited() and
34844 * g_subprocess_get_exit_status().
34846 * This function does not fail in the case of the subprocess having
34847 * abnormal termination. See g_subprocess_wait_check() for that.
34849 * Cancelling @cancellable doesn't kill the subprocess. Call
34850 * g_subprocess_force_exit() if it is desirable.
34852 * Returns: %TRUE on success, %FALSE if @cancellable was cancelled
34858 * g_subprocess_wait_async:
34859 * @subprocess: a #GSubprocess
34860 * @cancellable: a #GCancellable, or %NULL
34861 * @callback: a #GAsyncReadyCallback to call when the operation is complete
34862 * @user_data: user_data for @callback
34864 * Wait for the subprocess to terminate.
34866 * This is the asynchronous version of g_subprocess_wait().
34873 * g_subprocess_wait_check:
34874 * @subprocess: a #GSubprocess
34875 * @cancellable: a #GCancellable
34876 * @error: a #GError
34878 * Combines g_subprocess_wait() with g_spawn_check_exit_status().
34880 * Returns: %TRUE on success, %FALSE if process exited abnormally, or
34881 * @cancellable was cancelled
34887 * g_subprocess_wait_check_async:
34888 * @subprocess: a #GSubprocess
34889 * @cancellable: a #GCancellable, or %NULL
34890 * @callback: a #GAsyncReadyCallback to call when the operation is complete
34891 * @user_data: user_data for @callback
34893 * Combines g_subprocess_wait_async() with g_spawn_check_exit_status().
34895 * This is the asynchronous version of g_subprocess_wait_check().
34902 * g_subprocess_wait_check_finish:
34903 * @subprocess: a #GSubprocess
34904 * @result: the #GAsyncResult passed to your #GAsyncReadyCallback
34905 * @error: a pointer to a %NULL #GError, or %NULL
34907 * Collects the result of a previous call to
34908 * g_subprocess_wait_check_async().
34910 * Returns: %TRUE if successful, or %FALSE with @error set
34916 * g_subprocess_wait_finish:
34917 * @subprocess: a #GSubprocess
34918 * @result: the #GAsyncResult passed to your #GAsyncReadyCallback
34919 * @error: a pointer to a %NULL #GError, or %NULL
34921 * Collects the result of a previous call to
34922 * g_subprocess_wait_async().
34924 * Returns: %TRUE if successful, or %FALSE with @error set
34930 * g_task_attach_source:
34932 * @source: the source to attach
34933 * @callback: the callback to invoke when @source triggers
34935 * A utility function for dealing with async operations where you need
34936 * to wait for a #GSource to trigger. Attaches @source to @task's
34937 * #GMainContext with @task's [priority][io-priority], and sets @source's
34938 * callback to @callback, with @task as the callback's `user_data`.
34940 * This takes a reference on @task until @source is destroyed.
34947 * g_task_get_cancellable:
34950 * Gets @task's #GCancellable
34952 * Returns: (transfer none): @task's #GCancellable
34958 * g_task_get_check_cancellable:
34959 * @task: the #GTask
34961 * Gets @task's check-cancellable flag. See
34962 * g_task_set_check_cancellable() for more details.
34969 * g_task_get_context:
34972 * Gets the #GMainContext that @task will return its result in (that
34973 * is, the context that was the
34974 * [thread-default main context][g-main-context-push-thread-default]
34975 * at the point when @task was created).
34977 * This will always return a non-%NULL value, even if the task's
34978 * context is the default #GMainContext.
34980 * Returns: (transfer none): @task's #GMainContext
34986 * g_task_get_priority:
34989 * Gets @task's priority
34991 * Returns: @task's priority
34997 * g_task_get_return_on_cancel:
34998 * @task: the #GTask
35000 * Gets @task's return-on-cancel flag. See
35001 * g_task_set_return_on_cancel() for more details.
35008 * g_task_get_source_object:
35011 * Gets the source object from @task. Like
35012 * g_async_result_get_source_object(), but does not ref the object.
35014 * Returns: (transfer none) (type GObject): @task's source object, or %NULL
35020 * g_task_get_source_tag:
35023 * Gets @task's source tag. See g_task_set_source_tag().
35025 * Returns: (transfer none): @task's source tag
35031 * g_task_get_task_data:
35034 * Gets @task's `task_data`.
35036 * Returns: (transfer none): @task's `task_data`.
35042 * g_task_had_error:
35045 * Tests if @task resulted in an error.
35047 * Returns: %TRUE if the task resulted in an error, %FALSE otherwise.
35054 * @result: (type Gio.AsyncResult): A #GAsyncResult
35055 * @source_object: (allow-none) (type GObject): the source object
35056 * expected to be associated with the task
35058 * Checks that @result is a #GTask, and that @source_object is its
35059 * source object (or that @source_object is %NULL and @result has no
35060 * source object). This can be used in g_return_if_fail() checks.
35062 * Returns: %TRUE if @result and @source_object are valid, %FALSE
35070 * @source_object: (allow-none) (type GObject): the #GObject that owns
35071 * this task, or %NULL.
35072 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
35073 * @callback: (scope async): a #GAsyncReadyCallback.
35074 * @callback_data: (closure): user data passed to @callback.
35076 * Creates a #GTask acting on @source_object, which will eventually be
35077 * used to invoke @callback in the current
35078 * [thread-default main context][g-main-context-push-thread-default].
35080 * Call this in the "start" method of your asynchronous method, and
35081 * pass the #GTask around throughout the asynchronous operation. You
35082 * can use g_task_set_task_data() to attach task-specific data to the
35083 * object, which you can retrieve later via g_task_get_task_data().
35085 * By default, if @cancellable is cancelled, then the return value of
35086 * the task will always be %G_IO_ERROR_CANCELLED, even if the task had
35087 * already completed before the cancellation. This allows for
35088 * simplified handling in cases where cancellation may imply that
35089 * other objects that the task depends on have been destroyed. If you
35090 * do not want this behavior, you can use
35091 * g_task_set_check_cancellable() to change it.
35093 * Returns: a #GTask.
35099 * g_task_propagate_boolean:
35101 * @error: return location for a #GError
35103 * Gets the result of @task as a #gboolean.
35105 * If the task resulted in an error, or was cancelled, then this will
35106 * instead return %FALSE and set @error.
35108 * Since this method transfers ownership of the return value (or
35109 * error) to the caller, you may only call it once.
35111 * Returns: the task result, or %FALSE on error
35117 * g_task_propagate_int:
35119 * @error: return location for a #GError
35121 * Gets the result of @task as an integer (#gssize).
35123 * If the task resulted in an error, or was cancelled, then this will
35124 * instead return -1 and set @error.
35126 * Since this method transfers ownership of the return value (or
35127 * error) to the caller, you may only call it once.
35129 * Returns: the task result, or -1 on error
35135 * g_task_propagate_pointer:
35137 * @error: return location for a #GError
35139 * Gets the result of @task as a pointer, and transfers ownership
35140 * of that value to the caller.
35142 * If the task resulted in an error, or was cancelled, then this will
35143 * instead return %NULL and set @error.
35145 * Since this method transfers ownership of the return value (or
35146 * error) to the caller, you may only call it once.
35148 * Returns: (transfer full): the task result, or %NULL on error
35154 * g_task_report_error:
35155 * @source_object: (allow-none) (type GObject): the #GObject that owns
35156 * this task, or %NULL.
35157 * @callback: (scope async): a #GAsyncReadyCallback.
35158 * @callback_data: (closure): user data passed to @callback.
35159 * @source_tag: an opaque pointer indicating the source of this task
35160 * @error: (transfer full): error to report
35162 * Creates a #GTask and then immediately calls g_task_return_error()
35163 * on it. Use this in the wrapper function of an asynchronous method
35164 * when you want to avoid even calling the virtual method. You can
35165 * then use g_async_result_is_tagged() in the finish method wrapper to
35166 * check if the result there is tagged as having been created by the
35167 * wrapper method, and deal with it appropriately if so.
35169 * See also g_task_report_new_error().
35176 * g_task_report_new_error:
35177 * @source_object: (allow-none) (type GObject): the #GObject that owns
35178 * this task, or %NULL.
35179 * @callback: (scope async): a #GAsyncReadyCallback.
35180 * @callback_data: (closure): user data passed to @callback.
35181 * @source_tag: an opaque pointer indicating the source of this task
35182 * @domain: a #GQuark.
35183 * @code: an error code.
35184 * @format: a string with format characters.
35185 * @...: a list of values to insert into @format.
35187 * Creates a #GTask and then immediately calls
35188 * g_task_return_new_error() on it. Use this in the wrapper function
35189 * of an asynchronous method when you want to avoid even calling the
35190 * virtual method. You can then use g_async_result_is_tagged() in the
35191 * finish method wrapper to check if the result there is tagged as
35192 * having been created by the wrapper method, and deal with it
35193 * appropriately if so.
35195 * See also g_task_report_error().
35202 * g_task_return_boolean:
35204 * @result: the #gboolean result of a task function.
35206 * Sets @task's result to @result and completes the task (see
35207 * g_task_return_pointer() for more discussion of exactly what this
35215 * g_task_return_error:
35217 * @error: (transfer full): the #GError result of a task function.
35219 * Sets @task's result to @error (which @task assumes ownership of)
35220 * and completes the task (see g_task_return_pointer() for more
35221 * discussion of exactly what this means).
35223 * Note that since the task takes ownership of @error, and since the
35224 * task may be completed before returning from g_task_return_error(),
35225 * you cannot assume that @error is still valid after calling this.
35226 * Call g_error_copy() on the error if you need to keep a local copy
35229 * See also g_task_return_new_error().
35236 * g_task_return_error_if_cancelled:
35239 * Checks if @task's #GCancellable has been cancelled, and if so, sets
35240 * @task's error accordingly and completes the task (see
35241 * g_task_return_pointer() for more discussion of exactly what this
35244 * Returns: %TRUE if @task has been cancelled, %FALSE if not
35250 * g_task_return_int:
35252 * @result: the integer (#gssize) result of a task function.
35254 * Sets @task's result to @result and completes the task (see
35255 * g_task_return_pointer() for more discussion of exactly what this
35263 * g_task_return_new_error:
35265 * @domain: a #GQuark.
35266 * @code: an error code.
35267 * @format: a string with format characters.
35268 * @...: a list of values to insert into @format.
35270 * Sets @task's result to a new #GError created from @domain, @code,
35271 * @format, and the remaining arguments, and completes the task (see
35272 * g_task_return_pointer() for more discussion of exactly what this
35275 * See also g_task_return_error().
35282 * g_task_return_pointer:
35284 * @result: (allow-none) (transfer full): the pointer result of a task
35286 * @result_destroy: (allow-none): a #GDestroyNotify function.
35288 * Sets @task's result to @result and completes the task. If @result
35289 * is not %NULL, then @result_destroy will be used to free @result if
35290 * the caller does not take ownership of it with
35291 * g_task_propagate_pointer().
35293 * "Completes the task" means that for an ordinary asynchronous task
35294 * it will either invoke the task's callback, or else queue that
35295 * callback to be invoked in the proper #GMainContext, or in the next
35296 * iteration of the current #GMainContext. For a task run via
35297 * g_task_run_in_thread() or g_task_run_in_thread_sync(), calling this
35298 * method will save @result to be returned to the caller later, but
35299 * the task will not actually be completed until the #GTaskThreadFunc
35302 * Note that since the task may be completed before returning from
35303 * g_task_return_pointer(), you cannot assume that @result is still
35304 * valid after calling this, unless you are still holding another
35312 * g_task_run_in_thread:
35314 * @task_func: a #GTaskThreadFunc
35316 * Runs @task_func in another thread. When @task_func returns, @task's
35317 * #GAsyncReadyCallback will be invoked in @task's #GMainContext.
35319 * This takes a ref on @task until the task completes.
35321 * See #GTaskThreadFunc for more details about how @task_func is handled.
35328 * g_task_run_in_thread_sync:
35330 * @task_func: a #GTaskThreadFunc
35332 * Runs @task_func in another thread, and waits for it to return or be
35333 * cancelled. You can use g_task_propagate_pointer(), etc, afterward
35334 * to get the result of @task_func.
35336 * See #GTaskThreadFunc for more details about how @task_func is handled.
35338 * Normally this is used with tasks created with a %NULL
35339 * `callback`, but note that even if the task does
35340 * have a callback, it will not be invoked when @task_func returns.
35347 * g_task_set_check_cancellable:
35348 * @task: the #GTask
35349 * @check_cancellable: whether #GTask will check the state of
35350 * its #GCancellable for you.
35352 * Sets or clears @task's check-cancellable flag. If this is %TRUE
35353 * (the default), then g_task_propagate_pointer(), etc, and
35354 * g_task_had_error() will check the task's #GCancellable first, and
35355 * if it has been cancelled, then they will consider the task to have
35356 * returned an "Operation was cancelled" error
35357 * (%G_IO_ERROR_CANCELLED), regardless of any other error or return
35358 * value the task may have had.
35360 * If @check_cancellable is %FALSE, then the #GTask will not check the
35361 * cancellable itself, and it is up to @task's owner to do this (eg,
35362 * via g_task_return_error_if_cancelled()).
35364 * If you are using g_task_set_return_on_cancel() as well, then
35365 * you must leave check-cancellable set %TRUE.
35372 * g_task_set_priority:
35373 * @task: the #GTask
35374 * @priority: the [priority][io-priority] of the request
35376 * Sets @task's priority. If you do not call this, it will default to
35377 * %G_PRIORITY_DEFAULT.
35379 * This will affect the priority of #GSources created with
35380 * g_task_attach_source() and the scheduling of tasks run in threads,
35381 * and can also be explicitly retrieved later via
35382 * g_task_get_priority().
35389 * g_task_set_return_on_cancel:
35390 * @task: the #GTask
35391 * @return_on_cancel: whether the task returns automatically when
35394 * Sets or clears @task's return-on-cancel flag. This is only
35395 * meaningful for tasks run via g_task_run_in_thread() or
35396 * g_task_run_in_thread_sync().
35398 * If @return_on_cancel is %TRUE, then cancelling @task's
35399 * #GCancellable will immediately cause it to return, as though the
35400 * task's #GTaskThreadFunc had called
35401 * g_task_return_error_if_cancelled() and then returned.
35403 * This allows you to create a cancellable wrapper around an
35404 * uninterruptable function. The #GTaskThreadFunc just needs to be
35405 * careful that it does not modify any externally-visible state after
35406 * it has been cancelled. To do that, the thread should call
35407 * g_task_set_return_on_cancel() again to (atomically) set
35408 * return-on-cancel %FALSE before making externally-visible changes;
35409 * if the task gets cancelled before the return-on-cancel flag could
35410 * be changed, g_task_set_return_on_cancel() will indicate this by
35411 * returning %FALSE.
35413 * You can disable and re-enable this flag multiple times if you wish.
35414 * If the task's #GCancellable is cancelled while return-on-cancel is
35415 * %FALSE, then calling g_task_set_return_on_cancel() to set it %TRUE
35416 * again will cause the task to be cancelled at that point.
35418 * If the task's #GCancellable is already cancelled before you call
35419 * g_task_run_in_thread()/g_task_run_in_thread_sync(), then the
35420 * #GTaskThreadFunc will still be run (for consistency), but the task
35421 * will also be completed right away.
35423 * Returns: %TRUE if @task's return-on-cancel flag was changed to
35424 * match @return_on_cancel. %FALSE if @task has already been
35431 * g_task_set_source_tag:
35432 * @task: the #GTask
35433 * @source_tag: an opaque pointer indicating the source of this task
35435 * Sets @task's source tag. You can use this to tag a task return
35436 * value with a particular pointer (usually a pointer to the function
35437 * doing the tagging) and then later check it using
35438 * g_task_get_source_tag() (or g_async_result_is_tagged()) in the
35439 * task's "finish" function, to figure out if the response came from a
35440 * particular place.
35447 * g_task_set_task_data:
35448 * @task: the #GTask
35449 * @task_data: (allow-none): task-specific data
35450 * @task_data_destroy: (allow-none): #GDestroyNotify for @task_data
35452 * Sets @task's task data (freeing the existing task data, if any).
35459 * g_tcp_connection_get_graceful_disconnect:
35460 * @connection: a #GTcpConnection
35462 * Checks if graceful disconnects are used. See
35463 * g_tcp_connection_set_graceful_disconnect().
35465 * Returns: %TRUE if graceful disconnect is used on close, %FALSE otherwise
35471 * g_tcp_connection_set_graceful_disconnect:
35472 * @connection: a #GTcpConnection
35473 * @graceful_disconnect: Whether to do graceful disconnects or not
35475 * This enabled graceful disconnects on close. A graceful disconnect
35476 * means that we signal the receiving end that the connection is terminated
35477 * and wait for it to close the connection before closing the connection.
35479 * A graceful disconnect means that we can be sure that we successfully sent
35480 * all the outstanding data to the other end, or get an error reported.
35481 * However, it also means we have to wait for all the data to reach the
35482 * other side and for it to acknowledge this by closing the socket, which may
35483 * take a while. For this reason it is disabled by default.
35490 * g_tcp_wrapper_connection_get_base_io_stream:
35491 * @conn: a #GTcpWrapperConnection
35493 * Get's @conn's base #GIOStream
35495 * Returns: (transfer none): @conn's base #GIOStream
35500 * g_tcp_wrapper_connection_new:
35501 * @base_io_stream: the #GIOStream to wrap
35502 * @socket: the #GSocket associated with @base_io_stream
35504 * Wraps @base_io_stream and @socket together as a #GSocketConnection.
35506 * Returns: the new #GSocketConnection.
35512 * g_test_dbus_add_service_dir:
35513 * @self: a #GTestDBus
35514 * @path: path to a directory containing .service files
35516 * Add a path where dbus-daemon will look up .service files. This can't be
35517 * called after g_test_dbus_up().
35522 * g_test_dbus_down:
35523 * @self: a #GTestDBus
35525 * Stop the session bus started by g_test_dbus_up().
35527 * This will wait for the singleton returned by g_bus_get() or g_bus_get_sync()
35528 * is destroyed. This is done to ensure that the next unit test won't get a
35529 * leaked singleton from this test.
35534 * g_test_dbus_get_bus_address:
35535 * @self: a #GTestDBus
35537 * Get the address on which dbus-daemon is running. If g_test_dbus_up() has not
35538 * been called yet, %NULL is returned. This can be used with
35539 * g_dbus_connection_new_for_address().
35541 * Returns: (allow-none): the address of the bus, or %NULL.
35546 * g_test_dbus_get_flags:
35547 * @self: a #GTestDBus
35549 * Get the flags of the #GTestDBus object.
35551 * Returns: the value of #GTestDBus:flags property
35557 * @flags: a #GTestDBusFlags
35559 * Create a new #GTestDBus object.
35561 * Returns: (transfer full): a new #GTestDBus.
35566 * g_test_dbus_stop:
35567 * @self: a #GTestDBus
35569 * Stop the session bus started by g_test_dbus_up().
35571 * Unlike g_test_dbus_down(), this won't verify the #GDBusConnection
35572 * singleton returned by g_bus_get() or g_bus_get_sync() is destroyed. Unit
35573 * tests wanting to verify behaviour after the session bus has been stopped
35574 * can use this function but should still call g_test_dbus_down() when done.
35579 * g_test_dbus_unset:
35581 * Unset DISPLAY and DBUS_SESSION_BUS_ADDRESS env variables to ensure the test
35582 * won't use user's session bus.
35584 * This is useful for unit tests that want to verify behaviour when no session
35585 * bus is running. It is not necessary to call this if unit test already calls
35586 * g_test_dbus_up() before acquiring the session bus.
35592 * @self: a #GTestDBus
35594 * Start a dbus-daemon instance and set DBUS_SESSION_BUS_ADDRESS. After this
35595 * call, it is safe for unit tests to start sending messages on the session bus.
35597 * If this function is called from setup callback of g_test_add(),
35598 * g_test_dbus_down() must be called in its teardown callback.
35600 * If this function is called from unit test's main(), then g_test_dbus_down()
35601 * must be called after g_test_run().
35606 * g_themed_icon_append_name:
35607 * @icon: a #GThemedIcon
35608 * @iconname: name of icon to append to list of icons from within @icon.
35610 * Append a name to the list of icons from within @icon.
35612 * Note that doing so invalidates the hash computed by prior calls
35613 * to g_icon_hash().
35618 * g_themed_icon_get_names:
35619 * @icon: a #GThemedIcon.
35621 * Gets the names of icons from within @icon.
35623 * Returns: (transfer none): a list of icon names.
35628 * g_themed_icon_new:
35629 * @iconname: a string containing an icon name.
35631 * Creates a new themed icon for @iconname.
35633 * Returns: (transfer full) (type GThemedIcon): a new #GThemedIcon.
35638 * g_themed_icon_new_from_names:
35639 * @iconnames: (array length=len): an array of strings containing icon names.
35640 * @len: the length of the @iconnames array, or -1 if @iconnames is
35643 * Creates a new themed icon for @iconnames.
35645 * Returns: (transfer full) (type GThemedIcon): a new #GThemedIcon
35650 * g_themed_icon_new_with_default_fallbacks:
35651 * @iconname: a string containing an icon name
35653 * Creates a new themed icon for @iconname, and all the names
35654 * that can be created by shortening @iconname at '-' characters.
35656 * In the following example, @icon1 and @icon2 are equivalent:
35657 * |[<!-- language="C" -->
35658 * const char *names[] = {
35659 * "gnome-dev-cdrom-audio",
35660 * "gnome-dev-cdrom",
35665 * icon1 = g_themed_icon_new_from_names (names, 4);
35666 * icon2 = g_themed_icon_new_with_default_fallbacks ("gnome-dev-cdrom-audio");
35669 * Returns: (transfer full) (type GThemedIcon): a new #GThemedIcon.
35674 * g_themed_icon_prepend_name:
35675 * @icon: a #GThemedIcon
35676 * @iconname: name of icon to prepend to list of icons from within @icon.
35678 * Prepend a name to the list of icons from within @icon.
35680 * Note that doing so invalidates the hash computed by prior calls
35681 * to g_icon_hash().
35688 * g_threaded_socket_service_new:
35689 * @max_threads: the maximal number of threads to execute concurrently
35690 * handling incoming clients, -1 means no limit
35692 * Creates a new #GThreadedSocketService with no listeners. Listeners
35693 * must be added with one of the #GSocketListener "add" methods.
35695 * Returns: a new #GSocketService.
35701 * g_tls_backend_get_certificate_type:
35702 * @backend: the #GTlsBackend
35704 * Gets the #GType of @backend's #GTlsCertificate implementation.
35706 * Returns: the #GType of @backend's #GTlsCertificate
35713 * g_tls_backend_get_client_connection_type:
35714 * @backend: the #GTlsBackend
35716 * Gets the #GType of @backend's #GTlsClientConnection implementation.
35718 * Returns: the #GType of @backend's #GTlsClientConnection
35725 * g_tls_backend_get_default:
35727 * Gets the default #GTlsBackend for the system.
35729 * Returns: (transfer none): a #GTlsBackend
35735 * g_tls_backend_get_default_database:
35736 * @backend: the #GTlsBackend
35738 * Gets the default #GTlsDatabase used to verify TLS connections.
35740 * Returns: (transfer full): the default database, which should be
35741 * unreffed when done.
35747 * g_tls_backend_get_file_database_type:
35748 * @backend: the #GTlsBackend
35750 * Gets the #GType of @backend's #GTlsFileDatabase implementation.
35752 * Returns: the #GType of backend's #GTlsFileDatabase implementation.
35758 * g_tls_backend_get_server_connection_type:
35759 * @backend: the #GTlsBackend
35761 * Gets the #GType of @backend's #GTlsServerConnection implementation.
35763 * Returns: the #GType of @backend's #GTlsServerConnection
35770 * g_tls_backend_supports_tls:
35771 * @backend: the #GTlsBackend
35773 * Checks if TLS is supported; if this returns %FALSE for the default
35774 * #GTlsBackend, it means no "real" TLS backend is available.
35776 * Returns: whether or not TLS is supported
35782 * g_tls_certificate_get_issuer:
35783 * @cert: a #GTlsCertificate
35785 * Gets the #GTlsCertificate representing @cert's issuer, if known
35787 * Returns: (transfer none): The certificate of @cert's issuer,
35788 * or %NULL if @cert is self-signed or signed with an unknown
35795 * g_tls_certificate_is_same:
35796 * @cert_one: first certificate to compare
35797 * @cert_two: second certificate to compare
35799 * Check if two #GTlsCertificate objects represent the same certificate.
35800 * The raw DER byte data of the two certificates are checked for equality.
35801 * This has the effect that two certificates may compare equal even if
35802 * their #GTlsCertificate:issuer, #GTlsCertificate:private-key, or
35803 * #GTlsCertificate:private-key-pem properties differ.
35805 * Returns: whether the same or not
35811 * g_tls_certificate_list_new_from_file:
35812 * @file: file containing PEM-encoded certificates to import
35813 * @error: #GError for error reporting, or %NULL to ignore.
35815 * Creates one or more #GTlsCertificates from the PEM-encoded
35816 * data in @file. If @file cannot be read or parsed, the function will
35817 * return %NULL and set @error. If @file does not contain any
35818 * PEM-encoded certificates, this will return an empty list and not
35821 * Returns: (element-type Gio.TlsCertificate) (transfer full): a
35822 * #GList containing #GTlsCertificate objects. You must free the list
35823 * and its contents when you are done with it.
35829 * g_tls_certificate_new_from_file:
35830 * @file: file containing a PEM-encoded certificate to import
35831 * @error: #GError for error reporting, or %NULL to ignore.
35833 * Creates a #GTlsCertificate from the PEM-encoded data in @file. If
35834 * @file cannot be read or parsed, the function will return %NULL and
35835 * set @error. Otherwise, this behaves like
35836 * g_tls_certificate_new_from_pem().
35838 * Returns: the new certificate, or %NULL on error
35844 * g_tls_certificate_new_from_files:
35845 * @cert_file: file containing a PEM-encoded certificate to import
35846 * @key_file: file containing a PEM-encoded private key to import
35847 * @error: #GError for error reporting, or %NULL to ignore.
35849 * Creates a #GTlsCertificate from the PEM-encoded data in @cert_file
35850 * and @key_file. If either file cannot be read or parsed, the
35851 * function will return %NULL and set @error. Otherwise, this behaves
35852 * like g_tls_certificate_new_from_pem().
35854 * Returns: the new certificate, or %NULL on error
35860 * g_tls_certificate_new_from_pem:
35861 * @data: PEM-encoded certificate data
35862 * @length: the length of @data, or -1 if it's 0-terminated.
35863 * @error: #GError for error reporting, or %NULL to ignore.
35865 * Creates a new #GTlsCertificate from the PEM-encoded data in @data.
35866 * If @data includes both a certificate and a private key, then the
35867 * returned certificate will include the private key data as well. (See
35868 * the #GTlsCertificate:private-key-pem property for information about
35869 * supported formats.)
35871 * If @data includes multiple certificates, only the first one will be
35874 * Returns: the new certificate, or %NULL if @data is invalid
35880 * g_tls_certificate_verify:
35881 * @cert: a #GTlsCertificate
35882 * @identity: (allow-none): the expected peer identity
35883 * @trusted_ca: (allow-none): the certificate of a trusted authority
35885 * This verifies @cert and returns a set of #GTlsCertificateFlags
35886 * indicating any problems found with it. This can be used to verify a
35887 * certificate outside the context of making a connection, or to
35888 * check a certificate against a CA that is not part of the system
35891 * If @identity is not %NULL, @cert's name(s) will be compared against
35892 * it, and %G_TLS_CERTIFICATE_BAD_IDENTITY will be set in the return
35893 * value if it does not match. If @identity is %NULL, that bit will
35894 * never be set in the return value.
35896 * If @trusted_ca is not %NULL, then @cert (or one of the certificates
35897 * in its chain) must be signed by it, or else
35898 * %G_TLS_CERTIFICATE_UNKNOWN_CA will be set in the return value. If
35899 * @trusted_ca is %NULL, that bit will never be set in the return
35902 * (All other #GTlsCertificateFlags values will always be set or unset
35905 * Returns: the appropriate #GTlsCertificateFlags
35911 * g_tls_client_connection_get_accepted_cas:
35912 * @conn: the #GTlsClientConnection
35914 * Gets the list of distinguished names of the Certificate Authorities
35915 * that the server will accept certificates from. This will be set
35916 * during the TLS handshake if the server requests a certificate.
35917 * Otherwise, it will be %NULL.
35919 * Each item in the list is a #GByteArray which contains the complete
35920 * subject DN of the certificate authority.
35922 * Returns: (element-type GByteArray) (transfer full): the list of
35923 * CA DNs. You should unref each element with g_byte_array_unref() and then
35924 * the free the list with g_list_free().
35930 * g_tls_client_connection_get_server_identity:
35931 * @conn: the #GTlsClientConnection
35933 * Gets @conn's expected server identity
35935 * Returns: (transfer none): a #GSocketConnectable describing the
35936 * expected server identity, or %NULL if the expected identity is not
35943 * g_tls_client_connection_get_use_ssl3:
35944 * @conn: the #GTlsClientConnection
35946 * Gets whether @conn will use SSL 3.0 rather than the
35947 * highest-supported version of TLS; see
35948 * g_tls_client_connection_set_use_ssl3().
35950 * Returns: whether @conn will use SSL 3.0
35956 * g_tls_client_connection_get_validation_flags:
35957 * @conn: the #GTlsClientConnection
35959 * Gets @conn's validation flags
35961 * Returns: the validation flags
35967 * g_tls_client_connection_new:
35968 * @base_io_stream: the #GIOStream to wrap
35969 * @server_identity: (allow-none): the expected identity of the server
35970 * @error: #GError for error reporting, or %NULL to ignore.
35972 * Creates a new #GTlsClientConnection wrapping @base_io_stream (which
35973 * must have pollable input and output streams) which is assumed to
35974 * communicate with the server identified by @server_identity.
35976 * Returns: (transfer full) (type GTlsClientConnection): the new
35977 * #GTlsClientConnection, or %NULL on error
35983 * g_tls_client_connection_set_server_identity:
35984 * @conn: the #GTlsClientConnection
35985 * @identity: a #GSocketConnectable describing the expected server identity
35987 * Sets @conn's expected server identity, which is used both to tell
35988 * servers on virtual hosts which certificate to present, and also
35989 * to let @conn know what name to look for in the certificate when
35990 * performing %G_TLS_CERTIFICATE_BAD_IDENTITY validation, if enabled.
35997 * g_tls_client_connection_set_use_ssl3:
35998 * @conn: the #GTlsClientConnection
35999 * @use_ssl3: whether to use SSL 3.0
36001 * If @use_ssl3 is %TRUE, this forces @conn to use SSL 3.0 rather than
36002 * trying to properly negotiate the right version of TLS or SSL to use.
36003 * This can be used when talking to servers that do not implement the
36004 * fallbacks correctly and which will therefore fail to handshake with
36005 * a "modern" TLS handshake attempt.
36012 * g_tls_client_connection_set_validation_flags:
36013 * @conn: the #GTlsClientConnection
36014 * @flags: the #GTlsCertificateFlags to use
36016 * Sets @conn's validation flags, to override the default set of
36017 * checks performed when validating a server certificate. By default,
36018 * %G_TLS_CERTIFICATE_VALIDATE_ALL is used.
36025 * g_tls_connection_emit_accept_certificate:
36026 * @conn: a #GTlsConnection
36027 * @peer_cert: the peer's #GTlsCertificate
36028 * @errors: the problems with @peer_cert
36030 * Used by #GTlsConnection implementations to emit the
36031 * #GTlsConnection::accept-certificate signal.
36033 * Returns: %TRUE if one of the signal handlers has returned
36034 * %TRUE to accept @peer_cert
36040 * g_tls_connection_get_certificate:
36041 * @conn: a #GTlsConnection
36043 * Gets @conn's certificate, as set by
36044 * g_tls_connection_set_certificate().
36046 * Returns: (transfer none): @conn's certificate, or %NULL
36052 * g_tls_connection_get_database:
36053 * @conn: a #GTlsConnection
36055 * Gets the certificate database that @conn uses to verify
36056 * peer certificates. See g_tls_connection_set_database().
36058 * Returns: (transfer none): the certificate database that @conn uses or %NULL
36064 * g_tls_connection_get_interaction:
36065 * @conn: a connection
36067 * Get the object that will be used to interact with the user. It will be used
36068 * for things like prompting the user for passwords. If %NULL is returned, then
36069 * no user interaction will occur for this connection.
36071 * Returns: (transfer none): The interaction object.
36077 * g_tls_connection_get_peer_certificate:
36078 * @conn: a #GTlsConnection
36080 * Gets @conn's peer's certificate after the handshake has completed.
36081 * (It is not set during the emission of
36082 * #GTlsConnection::accept-certificate.)
36084 * Returns: (transfer none): @conn's peer's certificate, or %NULL
36090 * g_tls_connection_get_peer_certificate_errors:
36091 * @conn: a #GTlsConnection
36093 * Gets the errors associated with validating @conn's peer's
36094 * certificate, after the handshake has completed. (It is not set
36095 * during the emission of #GTlsConnection::accept-certificate.)
36097 * Returns: @conn's peer's certificate errors
36103 * g_tls_connection_get_rehandshake_mode:
36104 * @conn: a #GTlsConnection
36106 * Gets @conn rehandshaking mode. See
36107 * g_tls_connection_set_rehandshake_mode() for details.
36109 * Returns: @conn's rehandshaking mode
36115 * g_tls_connection_get_require_close_notify:
36116 * @conn: a #GTlsConnection
36118 * Tests whether or not @conn expects a proper TLS close notification
36119 * when the connection is closed. See
36120 * g_tls_connection_set_require_close_notify() for details.
36122 * Returns: %TRUE if @conn requires a proper TLS close
36129 * g_tls_connection_get_use_system_certdb:
36130 * @conn: a #GTlsConnection
36132 * Gets whether @conn uses the system certificate database to verify
36133 * peer certificates. See g_tls_connection_set_use_system_certdb().
36135 * Returns: whether @conn uses the system certificate database
36136 * Deprecated: 2.30: Use g_tls_connection_get_database() instead
36141 * g_tls_connection_handshake:
36142 * @conn: a #GTlsConnection
36143 * @cancellable: (allow-none): a #GCancellable, or %NULL
36144 * @error: a #GError, or %NULL
36146 * Attempts a TLS handshake on @conn.
36148 * On the client side, it is never necessary to call this method;
36149 * although the connection needs to perform a handshake after
36150 * connecting (or after sending a "STARTTLS"-type command) and may
36151 * need to rehandshake later if the server requests it,
36152 * #GTlsConnection will handle this for you automatically when you try
36153 * to send or receive data on the connection. However, you can call
36154 * g_tls_connection_handshake() manually if you want to know for sure
36155 * whether the initial handshake succeeded or failed (as opposed to
36156 * just immediately trying to write to @conn's output stream, in which
36157 * case if it fails, it may not be possible to tell if it failed
36158 * before or after completing the handshake).
36160 * Likewise, on the server side, although a handshake is necessary at
36161 * the beginning of the communication, you do not need to call this
36162 * function explicitly unless you want clearer error reporting.
36163 * However, you may call g_tls_connection_handshake() later on to
36164 * renegotiate parameters (encryption methods, etc) with the client.
36166 * #GTlsConnection::accept_certificate may be emitted during the
36169 * Returns: success or failure
36175 * g_tls_connection_handshake_async:
36176 * @conn: a #GTlsConnection
36177 * @io_priority: the [I/O priority][io-priority] of the request
36178 * @cancellable: (allow-none): a #GCancellable, or %NULL
36179 * @callback: callback to call when the handshake is complete
36180 * @user_data: the data to pass to the callback function
36182 * Asynchronously performs a TLS handshake on @conn. See
36183 * g_tls_connection_handshake() for more information.
36190 * g_tls_connection_handshake_finish:
36191 * @conn: a #GTlsConnection
36192 * @result: a #GAsyncResult.
36193 * @error: a #GError pointer, or %NULL
36195 * Finish an asynchronous TLS handshake operation. See
36196 * g_tls_connection_handshake() for more information.
36198 * Returns: %TRUE on success, %FALSE on failure, in which
36199 * case @error will be set.
36205 * g_tls_connection_set_certificate:
36206 * @conn: a #GTlsConnection
36207 * @certificate: the certificate to use for @conn
36209 * This sets the certificate that @conn will present to its peer
36210 * during the TLS handshake. For a #GTlsServerConnection, it is
36211 * mandatory to set this, and that will normally be done at construct
36214 * For a #GTlsClientConnection, this is optional. If a handshake fails
36215 * with %G_TLS_ERROR_CERTIFICATE_REQUIRED, that means that the server
36216 * requires a certificate, and if you try connecting again, you should
36217 * call this method first. You can call
36218 * g_tls_client_connection_get_accepted_cas() on the failed connection
36219 * to get a list of Certificate Authorities that the server will
36220 * accept certificates from.
36222 * (It is also possible that a server will allow the connection with
36223 * or without a certificate; in that case, if you don't provide a
36224 * certificate, you can tell that the server requested one by the fact
36225 * that g_tls_client_connection_get_accepted_cas() will return
36233 * g_tls_connection_set_database:
36234 * @conn: a #GTlsConnection
36235 * @database: a #GTlsDatabase
36237 * Sets the certificate database that is used to verify peer certificates.
36238 * This is set to the default database by default. See
36239 * g_tls_backend_get_default_database(). If set to %NULL, then
36240 * peer certificate validation will always set the
36241 * %G_TLS_CERTIFICATE_UNKNOWN_CA error (meaning
36242 * #GTlsConnection::accept-certificate will always be emitted on
36243 * client-side connections, unless that bit is not set in
36244 * #GTlsClientConnection:validation-flags).
36251 * g_tls_connection_set_interaction:
36252 * @conn: a connection
36253 * @interaction: (allow-none): an interaction object, or %NULL
36255 * Set the object that will be used to interact with the user. It will be used
36256 * for things like prompting the user for passwords.
36258 * The @interaction argument will normally be a derived subclass of
36259 * #GTlsInteraction. %NULL can also be provided if no user interaction
36260 * should occur for this connection.
36267 * g_tls_connection_set_rehandshake_mode:
36268 * @conn: a #GTlsConnection
36269 * @mode: the rehandshaking mode
36271 * Sets how @conn behaves with respect to rehandshaking requests.
36273 * %G_TLS_REHANDSHAKE_NEVER means that it will never agree to
36274 * rehandshake after the initial handshake is complete. (For a client,
36275 * this means it will refuse rehandshake requests from the server, and
36276 * for a server, this means it will close the connection with an error
36277 * if the client attempts to rehandshake.)
36279 * %G_TLS_REHANDSHAKE_SAFELY means that the connection will allow a
36280 * rehandshake only if the other end of the connection supports the
36281 * TLS `renegotiation_info` extension. This is the default behavior,
36282 * but means that rehandshaking will not work against older
36283 * implementations that do not support that extension.
36285 * %G_TLS_REHANDSHAKE_UNSAFELY means that the connection will allow
36286 * rehandshaking even without the `renegotiation_info` extension. On
36287 * the server side in particular, this is not recommended, since it
36288 * leaves the server open to certain attacks. However, this mode is
36289 * necessary if you need to allow renegotiation with older client
36297 * g_tls_connection_set_require_close_notify:
36298 * @conn: a #GTlsConnection
36299 * @require_close_notify: whether or not to require close notification
36301 * Sets whether or not @conn expects a proper TLS close notification
36302 * before the connection is closed. If this is %TRUE (the default),
36303 * then @conn will expect to receive a TLS close notification from its
36304 * peer before the connection is closed, and will return a
36305 * %G_TLS_ERROR_EOF error if the connection is closed without proper
36306 * notification (since this may indicate a network error, or
36307 * man-in-the-middle attack).
36309 * In some protocols, the application will know whether or not the
36310 * connection was closed cleanly based on application-level data
36311 * (because the application-level data includes a length field, or is
36312 * somehow self-delimiting); in this case, the close notify is
36313 * redundant and sometimes omitted. (TLS 1.1 explicitly allows this;
36314 * in TLS 1.0 it is technically an error, but often done anyway.) You
36315 * can use g_tls_connection_set_require_close_notify() to tell @conn
36316 * to allow an "unannounced" connection close, in which case the close
36317 * will show up as a 0-length read, as in a non-TLS
36318 * #GSocketConnection, and it is up to the application to check that
36319 * the data has been fully received.
36321 * Note that this only affects the behavior when the peer closes the
36322 * connection; when the application calls g_io_stream_close() itself
36323 * on @conn, this will send a close notification regardless of the
36324 * setting of this property. If you explicitly want to do an unclean
36325 * close, you can close @conn's #GTlsConnection:base-io-stream rather
36326 * than closing @conn itself.
36333 * g_tls_connection_set_use_system_certdb:
36334 * @conn: a #GTlsConnection
36335 * @use_system_certdb: whether to use the system certificate database
36337 * Sets whether @conn uses the system certificate database to verify
36338 * peer certificates. This is %TRUE by default. If set to %FALSE, then
36339 * peer certificate validation will always set the
36340 * %G_TLS_CERTIFICATE_UNKNOWN_CA error (meaning
36341 * #GTlsConnection::accept-certificate will always be emitted on
36342 * client-side connections, unless that bit is not set in
36343 * #GTlsClientConnection:validation-flags).
36345 * Deprecated: 2.30: Use g_tls_connection_set_database() instead
36350 * g_tls_database_create_certificate_handle:
36351 * @self: a #GTlsDatabase
36352 * @certificate: certificate for which to create a handle.
36354 * Create a handle string for the certificate. The database will only be able
36355 * to create a handle for certificates that originate from the database. In
36356 * cases where the database cannot create a handle for a certificate, %NULL
36357 * will be returned.
36359 * This handle should be stable across various instances of the application,
36360 * and between applications. If a certificate is modified in the database,
36361 * then it is not guaranteed that this handle will continue to point to it.
36363 * Returns: (nullable): a newly allocated string containing the
36370 * g_tls_database_lookup_certificate_for_handle:
36371 * @self: a #GTlsDatabase
36372 * @handle: a certificate handle
36373 * @interaction: (allow-none): used to interact with the user if necessary
36374 * @flags: Flags which affect the lookup.
36375 * @cancellable: (allow-none): a #GCancellable, or %NULL
36376 * @error: (allow-none): a #GError, or %NULL
36378 * Lookup a certificate by its handle.
36380 * The handle should have been created by calling
36381 * g_tls_database_create_certificate_handle() on a #GTlsDatabase object of
36382 * the same TLS backend. The handle is designed to remain valid across
36383 * instantiations of the database.
36385 * If the handle is no longer valid, or does not point to a certificate in
36386 * this database, then %NULL will be returned.
36388 * This function can block, use g_tls_database_lookup_certificate_for_handle_async() to perform
36389 * the lookup operation asynchronously.
36391 * Returns: (transfer full) (allow-none): a newly allocated
36392 * #GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate.
36398 * g_tls_database_lookup_certificate_for_handle_async:
36399 * @self: a #GTlsDatabase
36400 * @handle: a certificate handle
36401 * @interaction: (allow-none): used to interact with the user if necessary
36402 * @flags: Flags which affect the lookup.
36403 * @cancellable: (allow-none): a #GCancellable, or %NULL
36404 * @callback: callback to call when the operation completes
36405 * @user_data: the data to pass to the callback function
36407 * Asynchronously lookup a certificate by its handle in the database. See
36408 * g_tls_database_lookup_certificate_for_handle() for more information.
36415 * g_tls_database_lookup_certificate_for_handle_finish:
36416 * @self: a #GTlsDatabase
36417 * @result: a #GAsyncResult.
36418 * @error: a #GError pointer, or %NULL
36420 * Finish an asynchronous lookup of a certificate by its handle. See
36421 * g_tls_database_lookup_certificate_handle() for more information.
36423 * If the handle is no longer valid, or does not point to a certificate in
36424 * this database, then %NULL will be returned.
36426 * Returns: (transfer full): a newly allocated #GTlsCertificate object.
36427 * Use g_object_unref() to release the certificate.
36433 * g_tls_database_lookup_certificate_issuer:
36434 * @self: a #GTlsDatabase
36435 * @certificate: a #GTlsCertificate
36436 * @interaction: (allow-none): used to interact with the user if necessary
36437 * @flags: flags which affect the lookup operation
36438 * @cancellable: (allow-none): a #GCancellable, or %NULL
36439 * @error: (allow-none): a #GError, or %NULL
36441 * Lookup the issuer of @certificate in the database.
36443 * The %issuer property
36444 * of @certificate is not modified, and the two certificates are not hooked
36447 * This function can block, use g_tls_database_lookup_certificate_issuer_async() to perform
36448 * the lookup operation asynchronously.
36450 * Returns: (transfer full): a newly allocated issuer #GTlsCertificate,
36451 * or %NULL. Use g_object_unref() to release the certificate.
36457 * g_tls_database_lookup_certificate_issuer_async:
36458 * @self: a #GTlsDatabase
36459 * @certificate: a #GTlsCertificate
36460 * @interaction: (allow-none): used to interact with the user if necessary
36461 * @flags: flags which affect the lookup operation
36462 * @cancellable: (allow-none): a #GCancellable, or %NULL
36463 * @callback: callback to call when the operation completes
36464 * @user_data: the data to pass to the callback function
36466 * Asynchronously lookup the issuer of @certificate in the database. See
36467 * g_tls_database_lookup_certificate_issuer() for more information.
36474 * g_tls_database_lookup_certificate_issuer_finish:
36475 * @self: a #GTlsDatabase
36476 * @result: a #GAsyncResult.
36477 * @error: a #GError pointer, or %NULL
36479 * Finish an asynchronous lookup issuer operation. See
36480 * g_tls_database_lookup_certificate_issuer() for more information.
36482 * Returns: (transfer full): a newly allocated issuer #GTlsCertificate,
36483 * or %NULL. Use g_object_unref() to release the certificate.
36489 * g_tls_database_lookup_certificates_issued_by:
36490 * @self: a #GTlsDatabase
36491 * @issuer_raw_dn: a #GByteArray which holds the DER encoded issuer DN.
36492 * @interaction: (allow-none): used to interact with the user if necessary
36493 * @flags: Flags which affect the lookup operation.
36494 * @cancellable: (allow-none): a #GCancellable, or %NULL
36495 * @error: (allow-none): a #GError, or %NULL
36497 * Lookup certificates issued by this issuer in the database.
36499 * This function can block, use g_tls_database_lookup_certificates_issued_by_async() to perform
36500 * the lookup operation asynchronously.
36502 * Returns: (transfer full) (element-type GTlsCertificate): a newly allocated list of #GTlsCertificate
36503 * objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list.
36509 * g_tls_database_lookup_certificates_issued_by_async:
36510 * @self: a #GTlsDatabase
36511 * @issuer_raw_dn: a #GByteArray which holds the DER encoded issuer DN.
36512 * @interaction: (allow-none): used to interact with the user if necessary
36513 * @flags: Flags which affect the lookup operation.
36514 * @cancellable: (allow-none): a #GCancellable, or %NULL
36515 * @callback: callback to call when the operation completes
36516 * @user_data: the data to pass to the callback function
36518 * Asynchronously lookup certificates issued by this issuer in the database. See
36519 * g_tls_database_lookup_certificates_issued_by() for more information.
36521 * The database may choose to hold a reference to the issuer byte array for the duration
36522 * of of this asynchronous operation. The byte array should not be modified during
36530 * g_tls_database_lookup_certificates_issued_by_finish:
36531 * @self: a #GTlsDatabase
36532 * @result: a #GAsyncResult.
36533 * @error: a #GError pointer, or %NULL
36535 * Finish an asynchronous lookup of certificates. See
36536 * g_tls_database_lookup_certificates_issued_by() for more information.
36538 * Returns: (transfer full) (element-type GTlsCertificate): a newly allocated list of #GTlsCertificate
36539 * objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list.
36545 * g_tls_database_verify_chain:
36546 * @self: a #GTlsDatabase
36547 * @chain: a #GTlsCertificate chain
36548 * @purpose: the purpose that this certificate chain will be used for.
36549 * @identity: (allow-none): the expected peer identity
36550 * @interaction: (allow-none): used to interact with the user if necessary
36551 * @flags: additional verify flags
36552 * @cancellable: (allow-none): a #GCancellable, or %NULL
36553 * @error: (allow-none): a #GError, or %NULL
36555 * Verify's a certificate chain after looking up and adding any missing
36556 * certificates to the chain.
36558 * @chain is a chain of #GTlsCertificate objects each pointing to the next
36559 * certificate in the chain by its %issuer property. The chain may initially
36560 * consist of one or more certificates. After the verification process is
36561 * complete, @chain may be modified by adding missing certificates, or removing
36562 * extra certificates. If a certificate anchor was found, then it is added to
36565 * @purpose describes the purpose (or usage) for which the certificate
36566 * is being used. Typically @purpose will be set to #G_TLS_DATABASE_PURPOSE_AUTHENTICATE_SERVER
36567 * which means that the certificate is being used to authenticate a server
36568 * (and we are acting as the client).
36570 * The @identity is used to check for pinned certificates (trust exceptions)
36571 * in the database. These will override the normal verification process on a
36572 * host by host basis.
36574 * Currently there are no @flags, and %G_TLS_DATABASE_VERIFY_NONE should be
36577 * This function can block, use g_tls_database_verify_chain_async() to perform
36578 * the verification operation asynchronously.
36580 * Returns: the appropriate #GTlsCertificateFlags which represents the
36581 * result of verification.
36587 * g_tls_database_verify_chain_async:
36588 * @self: a #GTlsDatabase
36589 * @chain: a #GTlsCertificate chain
36590 * @purpose: the purpose that this certificate chain will be used for.
36591 * @identity: (allow-none): the expected peer identity
36592 * @interaction: (allow-none): used to interact with the user if necessary
36593 * @flags: additional verify flags
36594 * @cancellable: (allow-none): a #GCancellable, or %NULL
36595 * @callback: callback to call when the operation completes
36596 * @user_data: the data to pass to the callback function
36598 * Asynchronously verify's a certificate chain after looking up and adding
36599 * any missing certificates to the chain. See g_tls_database_verify_chain()
36600 * for more information.
36607 * g_tls_database_verify_chain_finish:
36608 * @self: a #GTlsDatabase
36609 * @result: a #GAsyncResult.
36610 * @error: a #GError pointer, or %NULL
36612 * Finish an asynchronous verify chain operation. See
36613 * g_tls_database_verify_chain() for more information. *
36615 * Returns: the appropriate #GTlsCertificateFlags which represents the
36616 * result of verification.
36622 * g_tls_error_quark:
36624 * Gets the TLS error quark.
36626 * Returns: a #GQuark.
36632 * g_tls_file_database_new:
36633 * @anchors: filename of anchor certificate authorities.
36634 * @error: #GError for error reporting, or %NULL to ignore.
36636 * Creates a new #GTlsFileDatabase which uses anchor certificate authorities
36637 * in @anchors to verify certificate chains.
36639 * The certificates in @anchors must be PEM encoded.
36641 * Returns: (transfer full) (type GTlsFileDatabase): the new
36642 * #GTlsFileDatabase, or %NULL on error
36648 * g_tls_interaction_ask_password:
36649 * @interaction: a #GTlsInteraction object
36650 * @password: a #GTlsPassword object
36651 * @cancellable: an optional #GCancellable cancellation object
36652 * @error: an optional location to place an error on failure
36654 * Run synchronous interaction to ask the user for a password. In general,
36655 * g_tls_interaction_invoke_ask_password() should be used instead of this
36658 * Derived subclasses usually implement a password prompt, although they may
36659 * also choose to provide a password from elsewhere. The @password value will
36660 * be filled in and then @callback will be called. Alternatively the user may
36661 * abort this password request, which will usually abort the TLS connection.
36663 * If the interaction is cancelled by the cancellation object, or by the
36664 * user then %G_TLS_INTERACTION_FAILED will be returned with an error that
36665 * contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may
36666 * not support immediate cancellation.
36668 * Returns: The status of the ask password interaction.
36674 * g_tls_interaction_ask_password_async:
36675 * @interaction: a #GTlsInteraction object
36676 * @password: a #GTlsPassword object
36677 * @cancellable: an optional #GCancellable cancellation object
36678 * @callback: (allow-none): will be called when the interaction completes
36679 * @user_data: (allow-none): data to pass to the @callback
36681 * Run asynchronous interaction to ask the user for a password. In general,
36682 * g_tls_interaction_invoke_ask_password() should be used instead of this
36685 * Derived subclasses usually implement a password prompt, although they may
36686 * also choose to provide a password from elsewhere. The @password value will
36687 * be filled in and then @callback will be called. Alternatively the user may
36688 * abort this password request, which will usually abort the TLS connection.
36690 * If the interaction is cancelled by the cancellation object, or by the
36691 * user then %G_TLS_INTERACTION_FAILED will be returned with an error that
36692 * contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may
36693 * not support immediate cancellation.
36695 * Certain implementations may not support immediate cancellation.
36702 * g_tls_interaction_ask_password_finish:
36703 * @interaction: a #GTlsInteraction object
36704 * @result: the result passed to the callback
36705 * @error: an optional location to place an error on failure
36707 * Complete an ask password user interaction request. This should be once
36708 * the g_tls_interaction_ask_password_async() completion callback is called.
36710 * If %G_TLS_INTERACTION_HANDLED is returned, then the #GTlsPassword passed
36711 * to g_tls_interaction_ask_password() will have its password filled in.
36713 * If the interaction is cancelled by the cancellation object, or by the
36714 * user then %G_TLS_INTERACTION_FAILED will be returned with an error that
36715 * contains a %G_IO_ERROR_CANCELLED error code.
36717 * Returns: The status of the ask password interaction.
36723 * g_tls_interaction_invoke_ask_password:
36724 * @interaction: a #GTlsInteraction object
36725 * @password: a #GTlsPassword object
36726 * @cancellable: an optional #GCancellable cancellation object
36727 * @error: an optional location to place an error on failure
36729 * Invoke the interaction to ask the user for a password. It invokes this
36730 * interaction in the main loop, specifically the #GMainContext returned by
36731 * g_main_context_get_thread_default() when the interaction is created. This
36732 * is called by called by #GTlsConnection or #GTlsDatabase to ask the user
36735 * Derived subclasses usually implement a password prompt, although they may
36736 * also choose to provide a password from elsewhere. The @password value will
36737 * be filled in and then @callback will be called. Alternatively the user may
36738 * abort this password request, which will usually abort the TLS connection.
36740 * The implementation can either be a synchronous (eg: modal dialog) or an
36741 * asynchronous one (eg: modeless dialog). This function will take care of
36742 * calling which ever one correctly.
36744 * If the interaction is cancelled by the cancellation object, or by the
36745 * user then %G_TLS_INTERACTION_FAILED will be returned with an error that
36746 * contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may
36747 * not support immediate cancellation.
36749 * Returns: The status of the ask password interaction.
36755 * g_tls_interaction_invoke_request_certificate:
36756 * @interaction: a #GTlsInteraction object
36757 * @connection: a #GTlsConnection object
36758 * @flags: flags providing more information about the request
36759 * @cancellable: an optional #GCancellable cancellation object
36760 * @error: an optional location to place an error on failure
36762 * Invoke the interaction to ask the user to choose a certificate to
36763 * use with the connection. It invokes this interaction in the main
36764 * loop, specifically the #GMainContext returned by
36765 * g_main_context_get_thread_default() when the interaction is
36766 * created. This is called by called by #GTlsConnection when the peer
36767 * requests a certificate during the handshake.
36769 * Derived subclasses usually implement a certificate selector,
36770 * although they may also choose to provide a certificate from
36771 * elsewhere. Alternatively the user may abort this certificate
36772 * request, which may or may not abort the TLS connection.
36774 * The implementation can either be a synchronous (eg: modal dialog) or an
36775 * asynchronous one (eg: modeless dialog). This function will take care of
36776 * calling which ever one correctly.
36778 * If the interaction is cancelled by the cancellation object, or by the
36779 * user then %G_TLS_INTERACTION_FAILED will be returned with an error that
36780 * contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may
36781 * not support immediate cancellation.
36783 * Returns: The status of the certificate request interaction.
36789 * g_tls_interaction_request_certificate:
36790 * @interaction: a #GTlsInteraction object
36791 * @connection: a #GTlsConnection object
36792 * @flags: flags providing more information about the request
36793 * @cancellable: an optional #GCancellable cancellation object
36794 * @error: an optional location to place an error on failure
36796 * Run synchronous interaction to ask the user to choose a certificate to use
36797 * with the connection. In general, g_tls_interaction_invoke_request_certificate()
36798 * should be used instead of this function.
36800 * Derived subclasses usually implement a certificate selector, although they may
36801 * also choose to provide a certificate from elsewhere. Alternatively the user may
36802 * abort this certificate request, which will usually abort the TLS connection.
36804 * If %G_TLS_INTERACTION_HANDLED is returned, then the #GTlsConnection
36805 * passed to g_tls_interaction_request_certificate() will have had its
36806 * #GTlsConnection:certificate filled in.
36808 * If the interaction is cancelled by the cancellation object, or by the
36809 * user then %G_TLS_INTERACTION_FAILED will be returned with an error that
36810 * contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may
36811 * not support immediate cancellation.
36813 * Returns: The status of the request certificate interaction.
36819 * g_tls_interaction_request_certificate_async:
36820 * @interaction: a #GTlsInteraction object
36821 * @connection: a #GTlsConnection object
36822 * @flags: flags providing more information about the request
36823 * @cancellable: an optional #GCancellable cancellation object
36824 * @callback: (allow-none): will be called when the interaction completes
36825 * @user_data: (allow-none): data to pass to the @callback
36827 * Run asynchronous interaction to ask the user for a certificate to use with
36828 * the connection. In general, g_tls_interaction_invoke_request_certificate() should
36829 * be used instead of this function.
36831 * Derived subclasses usually implement a certificate selector, although they may
36832 * also choose to provide a certificate from elsewhere. @callback will be called
36833 * when the operation completes. Alternatively the user may abort this certificate
36834 * request, which will usually abort the TLS connection.
36841 * g_tls_interaction_request_certificate_finish:
36842 * @interaction: a #GTlsInteraction object
36843 * @result: the result passed to the callback
36844 * @error: an optional location to place an error on failure
36846 * Complete an request certificate user interaction request. This should be once
36847 * the g_tls_interaction_request_certificate_async() completion callback is called.
36849 * If %G_TLS_INTERACTION_HANDLED is returned, then the #GTlsConnection
36850 * passed to g_tls_interaction_request_certificate_async() will have had its
36851 * #GTlsConnection:certificate filled in.
36853 * If the interaction is cancelled by the cancellation object, or by the
36854 * user then %G_TLS_INTERACTION_FAILED will be returned with an error that
36855 * contains a %G_IO_ERROR_CANCELLED error code.
36857 * Returns: The status of the request certificate interaction.
36863 * g_tls_password_get_description:
36864 * @password: a #GTlsPassword object
36866 * Get a description string about what the password will be used for.
36868 * Returns: The description of the password.
36874 * g_tls_password_get_flags:
36875 * @password: a #GTlsPassword object
36877 * Get flags about the password.
36879 * Returns: The flags about the password.
36885 * g_tls_password_get_value:
36886 * @password: a #GTlsPassword object
36887 * @length: (allow-none): location to place the length of the password.
36889 * Get the password value. If @length is not %NULL then it will be
36890 * filled in with the length of the password value. (Note that the
36891 * password value is not nul-terminated, so you can only pass %NULL
36892 * for @length in contexts where you know the password will have a
36893 * certain fixed length.)
36895 * Returns: The password value (owned by the password object).
36901 * g_tls_password_get_warning:
36902 * @password: a #GTlsPassword object
36904 * Get a user readable translated warning. Usually this warning is a
36905 * representation of the password flags returned from
36906 * g_tls_password_get_flags().
36908 * Returns: The warning.
36914 * g_tls_password_new:
36915 * @flags: the password flags
36916 * @description: description of what the password is for
36918 * Create a new #GTlsPassword object.
36920 * Returns: (transfer full): The newly allocated password object
36925 * g_tls_password_set_description:
36926 * @password: a #GTlsPassword object
36927 * @description: The description of the password
36929 * Set a description string about what the password will be used for.
36936 * g_tls_password_set_flags:
36937 * @password: a #GTlsPassword object
36938 * @flags: The flags about the password
36940 * Set flags about the password.
36947 * g_tls_password_set_value:
36948 * @password: a #GTlsPassword object
36949 * @value: the new password value
36950 * @length: the length of the password, or -1
36952 * Set the value for this password. The @value will be copied by the password
36955 * Specify the @length, for a non-nul-terminated password. Pass -1 as
36956 * @length if using a nul-terminated password, and @length will be
36957 * calculated automatically. (Note that the terminating nul is not
36958 * considered part of the password in this case.)
36965 * g_tls_password_set_value_full: (virtual set_value)
36966 * @password: a #GTlsPassword object
36967 * @value: the value for the password
36968 * @length: the length of the password, or -1
36969 * @destroy: (allow-none): a function to use to free the password.
36971 * Provide the value for this password.
36973 * The @value will be owned by the password object, and later freed using
36974 * the @destroy function callback.
36976 * Specify the @length, for a non-nul-terminated password. Pass -1 as
36977 * @length if using a nul-terminated password, and @length will be
36978 * calculated automatically. (Note that the terminating nul is not
36979 * considered part of the password in this case.)
36986 * g_tls_password_set_warning:
36987 * @password: a #GTlsPassword object
36988 * @warning: The user readable warning
36990 * Set a user readable translated warning. Usually this warning is a
36991 * representation of the password flags returned from
36992 * g_tls_password_get_flags().
36999 * g_tls_server_connection_new:
37000 * @base_io_stream: the #GIOStream to wrap
37001 * @certificate: (allow-none): the default server certificate, or %NULL
37002 * @error: #GError for error reporting, or %NULL to ignore.
37004 * Creates a new #GTlsServerConnection wrapping @base_io_stream (which
37005 * must have pollable input and output streams).
37007 * Returns: (transfer full) (type GTlsServerConnection): the new
37008 * #GTlsServerConnection, or %NULL on error
37014 * g_unix_connection_receive_credentials:
37015 * @connection: A #GUnixConnection.
37016 * @cancellable: (allow-none): A #GCancellable or %NULL.
37017 * @error: Return location for error or %NULL.
37019 * Receives credentials from the sending end of the connection. The
37020 * sending end has to call g_unix_connection_send_credentials() (or
37021 * similar) for this to work.
37023 * As well as reading the credentials this also reads (and discards) a
37024 * single byte from the stream, as this is required for credentials
37025 * passing to work on some implementations.
37027 * Other ways to exchange credentials with a foreign peer includes the
37028 * #GUnixCredentialsMessage type and g_socket_get_credentials() function.
37030 * Returns: (transfer full): Received credentials on success (free with
37031 * g_object_unref()), %NULL if @error is set.
37037 * g_unix_connection_receive_credentials_async:
37038 * @connection: A #GUnixConnection.
37039 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
37040 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
37041 * @user_data: (closure): the data to pass to callback function
37043 * Asynchronously receive credentials.
37045 * For more details, see g_unix_connection_receive_credentials() which is
37046 * the synchronous version of this call.
37048 * When the operation is finished, @callback will be called. You can then call
37049 * g_unix_connection_receive_credentials_finish() to get the result of the operation.
37056 * g_unix_connection_receive_credentials_finish:
37057 * @connection: A #GUnixConnection.
37058 * @result: a #GAsyncResult.
37059 * @error: a #GError, or %NULL
37061 * Finishes an asynchronous receive credentials operation started with
37062 * g_unix_connection_receive_credentials_async().
37064 * Returns: (transfer full): a #GCredentials, or %NULL on error.
37065 * Free the returned object with g_object_unref().
37071 * g_unix_connection_receive_fd:
37072 * @connection: a #GUnixConnection
37073 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
37074 * @error: (allow-none): #GError for error reporting, or %NULL to ignore
37076 * Receives a file descriptor from the sending end of the connection.
37077 * The sending end has to call g_unix_connection_send_fd() for this
37080 * As well as reading the fd this also reads a single byte from the
37081 * stream, as this is required for fd passing to work on some
37084 * Returns: a file descriptor on success, -1 on error.
37090 * g_unix_connection_send_credentials:
37091 * @connection: A #GUnixConnection.
37092 * @cancellable: (allow-none): A #GCancellable or %NULL.
37093 * @error: Return location for error or %NULL.
37095 * Passes the credentials of the current user the receiving side
37096 * of the connection. The receiving end has to call
37097 * g_unix_connection_receive_credentials() (or similar) to accept the
37100 * As well as sending the credentials this also writes a single NUL
37101 * byte to the stream, as this is required for credentials passing to
37102 * work on some implementations.
37104 * Other ways to exchange credentials with a foreign peer includes the
37105 * #GUnixCredentialsMessage type and g_socket_get_credentials() function.
37107 * Returns: %TRUE on success, %FALSE if @error is set.
37113 * g_unix_connection_send_credentials_async:
37114 * @connection: A #GUnixConnection.
37115 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
37116 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
37117 * @user_data: (closure): the data to pass to callback function
37119 * Asynchronously send credentials.
37121 * For more details, see g_unix_connection_send_credentials() which is
37122 * the synchronous version of this call.
37124 * When the operation is finished, @callback will be called. You can then call
37125 * g_unix_connection_send_credentials_finish() to get the result of the operation.
37132 * g_unix_connection_send_credentials_finish:
37133 * @connection: A #GUnixConnection.
37134 * @result: a #GAsyncResult.
37135 * @error: a #GError, or %NULL
37137 * Finishes an asynchronous send credentials operation started with
37138 * g_unix_connection_send_credentials_async().
37140 * Returns: %TRUE if the operation was successful, otherwise %FALSE.
37146 * g_unix_connection_send_fd:
37147 * @connection: a #GUnixConnection
37148 * @fd: a file descriptor
37149 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
37150 * @error: (allow-none): #GError for error reporting, or %NULL to ignore.
37152 * Passes a file descriptor to the receiving side of the
37153 * connection. The receiving end has to call g_unix_connection_receive_fd()
37154 * to accept the file descriptor.
37156 * As well as sending the fd this also writes a single byte to the
37157 * stream, as this is required for fd passing to work on some
37160 * Returns: a %TRUE on success, %NULL on error.
37166 * g_unix_credentials_message_get_credentials:
37167 * @message: A #GUnixCredentialsMessage.
37169 * Gets the credentials stored in @message.
37171 * Returns: (transfer none): A #GCredentials instance. Do not free, it is owned by @message.
37177 * g_unix_credentials_message_is_supported:
37179 * Checks if passing #GCredentials on a #GSocket is supported on this platform.
37181 * Returns: %TRUE if supported, %FALSE otherwise
37187 * g_unix_credentials_message_new:
37189 * Creates a new #GUnixCredentialsMessage with credentials matching the current processes.
37191 * Returns: a new #GUnixCredentialsMessage
37197 * g_unix_credentials_message_new_with_credentials:
37198 * @credentials: A #GCredentials object.
37200 * Creates a new #GUnixCredentialsMessage holding @credentials.
37202 * Returns: a new #GUnixCredentialsMessage
37208 * g_unix_fd_list_append:
37209 * @list: a #GUnixFDList
37210 * @fd: a valid open file descriptor
37211 * @error: a #GError pointer
37213 * Adds a file descriptor to @list.
37215 * The file descriptor is duplicated using dup(). You keep your copy
37216 * of the descriptor and the copy contained in @list will be closed
37217 * when @list is finalized.
37219 * A possible cause of failure is exceeding the per-process or
37220 * system-wide file descriptor limit.
37222 * The index of the file descriptor in the list is returned. If you use
37223 * this index with g_unix_fd_list_get() then you will receive back a
37224 * duplicated copy of the same file descriptor.
37226 * Returns: the index of the appended fd in case of success, else -1
37227 * (and @error is set)
37233 * g_unix_fd_list_get:
37234 * @list: a #GUnixFDList
37235 * @index_: the index into the list
37236 * @error: a #GError pointer
37238 * Gets a file descriptor out of @list.
37240 * @index_ specifies the index of the file descriptor to get. It is a
37241 * programmer error for @index_ to be out of range; see
37242 * g_unix_fd_list_get_length().
37244 * The file descriptor is duplicated using dup() and set as
37245 * close-on-exec before being returned. You must call close() on it
37246 * when you are done.
37248 * A possible cause of failure is exceeding the per-process or
37249 * system-wide file descriptor limit.
37251 * Returns: the file descriptor, or -1 in case of error
37257 * g_unix_fd_list_get_length:
37258 * @list: a #GUnixFDList
37260 * Gets the length of @list (ie: the number of file descriptors
37261 * contained within).
37263 * Returns: the length of @list
37269 * g_unix_fd_list_new:
37271 * Creates a new #GUnixFDList containing no file descriptors.
37273 * Returns: a new #GUnixFDList
37279 * g_unix_fd_list_new_from_array:
37280 * @fds: (array length=n_fds): the initial list of file descriptors
37281 * @n_fds: the length of #fds, or -1
37283 * Creates a new #GUnixFDList containing the file descriptors given in
37284 * @fds. The file descriptors become the property of the new list and
37285 * may no longer be used by the caller. The array itself is owned by
37288 * Each file descriptor in the array should be set to close-on-exec.
37290 * If @n_fds is -1 then @fds must be terminated with -1.
37292 * Returns: a new #GUnixFDList
37298 * g_unix_fd_list_peek_fds:
37299 * @list: a #GUnixFDList
37300 * @length: (out) (allow-none): pointer to the length of the returned
37303 * Returns the array of file descriptors that is contained in this
37306 * After this call, the descriptors remain the property of @list. The
37307 * caller must not close them and must not free the array. The array is
37308 * valid only until @list is changed in any way.
37310 * If @length is non-%NULL then it is set to the number of file
37311 * descriptors in the returned array. The returned array is also
37312 * terminated with -1.
37314 * This function never returns %NULL. In case there are no file
37315 * descriptors contained in @list, an empty array is returned.
37317 * Returns: (array length=length) (transfer none): an array of file
37324 * g_unix_fd_list_steal_fds:
37325 * @list: a #GUnixFDList
37326 * @length: (out) (allow-none): pointer to the length of the returned
37329 * Returns the array of file descriptors that is contained in this
37332 * After this call, the descriptors are no longer contained in
37333 * @list. Further calls will return an empty list (unless more
37334 * descriptors have been added).
37336 * The return result of this function must be freed with g_free().
37337 * The caller is also responsible for closing all of the file
37338 * descriptors. The file descriptors in the array are set to
37341 * If @length is non-%NULL then it is set to the number of file
37342 * descriptors in the returned array. The returned array is also
37343 * terminated with -1.
37345 * This function never returns %NULL. In case there are no file
37346 * descriptors contained in @list, an empty array is returned.
37348 * Returns: (array length=length) (transfer full): an array of file
37355 * g_unix_fd_message_append_fd:
37356 * @message: a #GUnixFDMessage
37357 * @fd: a valid open file descriptor
37358 * @error: a #GError pointer
37360 * Adds a file descriptor to @message.
37362 * The file descriptor is duplicated using dup(). You keep your copy
37363 * of the descriptor and the copy contained in @message will be closed
37364 * when @message is finalized.
37366 * A possible cause of failure is exceeding the per-process or
37367 * system-wide file descriptor limit.
37369 * Returns: %TRUE in case of success, else %FALSE (and @error is set)
37375 * g_unix_fd_message_get_fd_list:
37376 * @message: a #GUnixFDMessage
37378 * Gets the #GUnixFDList contained in @message. This function does not
37379 * return a reference to the caller, but the returned list is valid for
37380 * the lifetime of @message.
37382 * Returns: (transfer none): the #GUnixFDList from @message
37388 * g_unix_fd_message_new:
37390 * Creates a new #GUnixFDMessage containing an empty file descriptor
37393 * Returns: a new #GUnixFDMessage
37399 * g_unix_fd_message_new_with_fd_list:
37400 * @fd_list: a #GUnixFDList
37402 * Creates a new #GUnixFDMessage containing @list.
37404 * Returns: a new #GUnixFDMessage
37410 * g_unix_fd_message_steal_fds:
37411 * @message: a #GUnixFDMessage
37412 * @length: (out) (allow-none): pointer to the length of the returned
37415 * Returns the array of file descriptors that is contained in this
37418 * After this call, the descriptors are no longer contained in
37419 * @message. Further calls will return an empty list (unless more
37420 * descriptors have been added).
37422 * The return result of this function must be freed with g_free().
37423 * The caller is also responsible for closing all of the file
37426 * If @length is non-%NULL then it is set to the number of file
37427 * descriptors in the returned array. The returned array is also
37428 * terminated with -1.
37430 * This function never returns %NULL. In case there are no file
37431 * descriptors contained in @message, an empty array is returned.
37433 * Returns: (array length=length) (transfer full): an array of file
37440 * g_unix_input_stream_get_close_fd:
37441 * @stream: a #GUnixInputStream
37443 * Returns whether the file descriptor of @stream will be
37444 * closed when the stream is closed.
37446 * Returns: %TRUE if the file descriptor is closed when done
37452 * g_unix_input_stream_get_fd:
37453 * @stream: a #GUnixInputStream
37455 * Return the UNIX file descriptor that the stream reads from.
37457 * Returns: The file descriptor of @stream
37463 * g_unix_input_stream_new:
37464 * @fd: a UNIX file descriptor
37465 * @close_fd: %TRUE to close the file descriptor when done
37467 * Creates a new #GUnixInputStream for the given @fd.
37469 * If @close_fd is %TRUE, the file descriptor will be closed
37470 * when the stream is closed.
37472 * Returns: a new #GUnixInputStream
37477 * g_unix_input_stream_set_close_fd:
37478 * @stream: a #GUnixInputStream
37479 * @close_fd: %TRUE to close the file descriptor when done
37481 * Sets whether the file descriptor of @stream shall be closed
37482 * when the stream is closed.
37489 * g_unix_is_mount_path_system_internal:
37490 * @mount_path: a mount path, e.g. `/media/disk` or `/usr`
37492 * Determines if @mount_path is considered an implementation of the
37493 * OS. This is primarily used for hiding mountable and mounted volumes
37494 * that only are used in the OS and has little to no relevance to the
37497 * Returns: %TRUE if @mount_path is considered an implementation detail
37503 * g_unix_mount_at: (skip)
37504 * @mount_path: path for a possible unix mount.
37505 * @time_read: (out) (allow-none): guint64 to contain a timestamp.
37507 * Gets a #GUnixMountEntry for a given mount path. If @time_read
37508 * is set, it will be filled with a unix timestamp for checking
37509 * if the mounts have changed since with g_unix_mounts_changed_since().
37511 * Returns: (transfer full): a #GUnixMountEntry.
37516 * g_unix_mount_compare:
37517 * @mount1: first #GUnixMountEntry to compare.
37518 * @mount2: second #GUnixMountEntry to compare.
37520 * Compares two unix mounts.
37522 * Returns: 1, 0 or -1 if @mount1 is greater than, equal to,
37523 * or less than @mount2, respectively.
37528 * g_unix_mount_free:
37529 * @mount_entry: a #GUnixMountEntry.
37531 * Frees a unix mount.
37536 * g_unix_mount_get_device_path:
37537 * @mount_entry: a #GUnixMount.
37539 * Gets the device path for a unix mount.
37541 * Returns: a string containing the device path.
37546 * g_unix_mount_get_fs_type:
37547 * @mount_entry: a #GUnixMount.
37549 * Gets the filesystem type for the unix mount.
37551 * Returns: a string containing the file system type.
37556 * g_unix_mount_get_mount_path:
37557 * @mount_entry: input #GUnixMountEntry to get the mount path for.
37559 * Gets the mount path for a unix mount.
37561 * Returns: the mount path for @mount_entry.
37566 * g_unix_mount_guess_can_eject:
37567 * @mount_entry: a #GUnixMountEntry
37569 * Guesses whether a Unix mount can be ejected.
37571 * Returns: %TRUE if @mount_entry is deemed to be ejectable.
37576 * g_unix_mount_guess_icon:
37577 * @mount_entry: a #GUnixMountEntry
37579 * Guesses the icon of a Unix mount.
37581 * Returns: (transfer full): a #GIcon
37586 * g_unix_mount_guess_name:
37587 * @mount_entry: a #GUnixMountEntry
37589 * Guesses the name of a Unix mount.
37590 * The result is a translated string.
37592 * Returns: A newly allocated string that must
37593 * be freed with g_free()
37598 * g_unix_mount_guess_should_display:
37599 * @mount_entry: a #GUnixMountEntry
37601 * Guesses whether a Unix mount should be displayed in the UI.
37603 * Returns: %TRUE if @mount_entry is deemed to be displayable.
37608 * g_unix_mount_guess_symbolic_icon:
37609 * @mount_entry: a #GUnixMountEntry
37611 * Guesses the symbolic icon of a Unix mount.
37613 * Returns: (transfer full): a #GIcon
37619 * g_unix_mount_guess_type:
37620 * @mount_entry: a #GUnixMount.
37622 * Guesses the type of a unix mount. If the mount type cannot be
37623 * determined, returns %G_UNIX_MOUNT_TYPE_UNKNOWN.
37625 * Returns: a #GUnixMountType.
37630 * g_unix_mount_is_readonly:
37631 * @mount_entry: a #GUnixMount.
37633 * Checks if a unix mount is mounted read only.
37635 * Returns: %TRUE if @mount_entry is read only.
37640 * g_unix_mount_is_system_internal:
37641 * @mount_entry: a #GUnixMount.
37643 * Checks if a unix mount is a system path.
37645 * Returns: %TRUE if the unix mount is for a system path.
37650 * g_unix_mount_monitor_new:
37652 * Gets a new #GUnixMountMonitor. The default rate limit for which the
37653 * monitor will report consecutive changes for the mount and mount
37654 * point entry files is the default for a #GFileMonitor. Use
37655 * g_unix_mount_monitor_set_rate_limit() to change this.
37657 * Returns: a #GUnixMountMonitor.
37662 * g_unix_mount_monitor_set_rate_limit:
37663 * @mount_monitor: a #GUnixMountMonitor
37664 * @limit_msec: a integer with the limit in milliseconds to
37665 * poll for changes.
37667 * Sets the rate limit to which the @mount_monitor will report
37668 * consecutive change events to the mount and mount point entry files.
37675 * g_unix_mount_point_compare:
37676 * @mount1: a #GUnixMount.
37677 * @mount2: a #GUnixMount.
37679 * Compares two unix mount points.
37681 * Returns: 1, 0 or -1 if @mount1 is greater than, equal to,
37682 * or less than @mount2, respectively.
37687 * g_unix_mount_point_free:
37688 * @mount_point: unix mount point to free.
37690 * Frees a unix mount point.
37695 * g_unix_mount_point_get_device_path:
37696 * @mount_point: a #GUnixMountPoint.
37698 * Gets the device path for a unix mount point.
37700 * Returns: a string containing the device path.
37705 * g_unix_mount_point_get_fs_type:
37706 * @mount_point: a #GUnixMountPoint.
37708 * Gets the file system type for the mount point.
37710 * Returns: a string containing the file system type.
37715 * g_unix_mount_point_get_mount_path:
37716 * @mount_point: a #GUnixMountPoint.
37718 * Gets the mount path for a unix mount point.
37720 * Returns: a string containing the mount path.
37725 * g_unix_mount_point_get_options:
37726 * @mount_point: a #GUnixMountPoint.
37728 * Gets the options for the mount point.
37730 * Returns: a string containing the options.
37736 * g_unix_mount_point_guess_can_eject:
37737 * @mount_point: a #GUnixMountPoint
37739 * Guesses whether a Unix mount point can be ejected.
37741 * Returns: %TRUE if @mount_point is deemed to be ejectable.
37746 * g_unix_mount_point_guess_icon:
37747 * @mount_point: a #GUnixMountPoint
37749 * Guesses the icon of a Unix mount point.
37751 * Returns: (transfer full): a #GIcon
37756 * g_unix_mount_point_guess_name:
37757 * @mount_point: a #GUnixMountPoint
37759 * Guesses the name of a Unix mount point.
37760 * The result is a translated string.
37762 * Returns: A newly allocated string that must
37763 * be freed with g_free()
37768 * g_unix_mount_point_guess_symbolic_icon:
37769 * @mount_point: a #GUnixMountPoint
37771 * Guesses the symbolic icon of a Unix mount point.
37773 * Returns: (transfer full): a #GIcon
37779 * g_unix_mount_point_guess_type:
37780 * @mount_point: a #GUnixMountPoint.
37782 * Guesses the type of a unix mount point.
37783 * If the mount type cannot be determined,
37784 * returns %G_UNIX_MOUNT_TYPE_UNKNOWN.
37786 * Returns: a #GUnixMountType.
37791 * g_unix_mount_point_is_loopback:
37792 * @mount_point: a #GUnixMountPoint.
37794 * Checks if a unix mount point is a loopback device.
37796 * Returns: %TRUE if the mount point is a loopback. %FALSE otherwise.
37801 * g_unix_mount_point_is_readonly:
37802 * @mount_point: a #GUnixMountPoint.
37804 * Checks if a unix mount point is read only.
37806 * Returns: %TRUE if a mount point is read only.
37811 * g_unix_mount_point_is_user_mountable:
37812 * @mount_point: a #GUnixMountPoint.
37814 * Checks if a unix mount point is mountable by the user.
37816 * Returns: %TRUE if the mount point is user mountable.
37821 * g_unix_mount_points_changed_since:
37822 * @time: guint64 to contain a timestamp.
37824 * Checks if the unix mount points have changed since a given unix time.
37826 * Returns: %TRUE if the mount points have changed since @time.
37831 * g_unix_mount_points_get: (skip)
37832 * @time_read: (out) (allow-none): guint64 to contain a timestamp.
37834 * Gets a #GList of #GUnixMountPoint containing the unix mount points.
37835 * If @time_read is set, it will be filled with the mount timestamp,
37836 * allowing for checking if the mounts have changed with
37837 * g_unix_mount_points_changed_since().
37839 * Returns: (element-type GUnixMountPoint) (transfer full):
37840 * a #GList of the UNIX mountpoints.
37845 * g_unix_mounts_changed_since:
37846 * @time: guint64 to contain a timestamp.
37848 * Checks if the unix mounts have changed since a given unix time.
37850 * Returns: %TRUE if the mounts have changed since @time.
37855 * g_unix_mounts_get: (skip)
37856 * @time_read: (out) (allow-none): guint64 to contain a timestamp, or %NULL
37858 * Gets a #GList of #GUnixMountEntry containing the unix mounts.
37859 * If @time_read is set, it will be filled with the mount
37860 * timestamp, allowing for checking if the mounts have changed
37861 * with g_unix_mounts_changed_since().
37863 * Returns: (element-type GUnixMountEntry) (transfer full):
37864 * a #GList of the UNIX mounts.
37869 * g_unix_output_stream_get_close_fd:
37870 * @stream: a #GUnixOutputStream
37872 * Returns whether the file descriptor of @stream will be
37873 * closed when the stream is closed.
37875 * Returns: %TRUE if the file descriptor is closed when done
37881 * g_unix_output_stream_get_fd:
37882 * @stream: a #GUnixOutputStream
37884 * Return the UNIX file descriptor that the stream writes to.
37886 * Returns: The file descriptor of @stream
37892 * g_unix_output_stream_new:
37893 * @fd: a UNIX file descriptor
37894 * @close_fd: %TRUE to close the file descriptor when done
37896 * Creates a new #GUnixOutputStream for the given @fd.
37898 * If @close_fd, is %TRUE, the file descriptor will be closed when
37899 * the output stream is destroyed.
37901 * Returns: a new #GOutputStream
37906 * g_unix_output_stream_set_close_fd:
37907 * @stream: a #GUnixOutputStream
37908 * @close_fd: %TRUE to close the file descriptor when done
37910 * Sets whether the file descriptor of @stream shall be closed
37911 * when the stream is closed.
37918 * g_unix_socket_address_abstract_names_supported:
37920 * Checks if abstract UNIX domain socket names are supported.
37922 * Returns: %TRUE if supported, %FALSE otherwise
37928 * g_unix_socket_address_get_address_type:
37929 * @address: a #GInetSocketAddress
37931 * Gets @address's type.
37933 * Returns: a #GUnixSocketAddressType
37939 * g_unix_socket_address_get_is_abstract:
37940 * @address: a #GInetSocketAddress
37942 * Tests if @address is abstract.
37944 * Returns: %TRUE if the address is abstract, %FALSE otherwise
37946 * Deprecated: Use g_unix_socket_address_get_address_type()
37951 * g_unix_socket_address_get_path:
37952 * @address: a #GInetSocketAddress
37954 * Gets @address's path, or for abstract sockets the "name".
37956 * Guaranteed to be zero-terminated, but an abstract socket
37957 * may contain embedded zeros, and thus you should use
37958 * g_unix_socket_address_get_path_len() to get the true length
37961 * Returns: the path for @address
37967 * g_unix_socket_address_get_path_len:
37968 * @address: a #GInetSocketAddress
37970 * Gets the length of @address's path.
37972 * For details, see g_unix_socket_address_get_path().
37974 * Returns: the length of the path
37980 * g_unix_socket_address_new:
37981 * @path: the socket path
37983 * Creates a new #GUnixSocketAddress for @path.
37985 * To create abstract socket addresses, on systems that support that,
37986 * use g_unix_socket_address_new_abstract().
37988 * Returns: a new #GUnixSocketAddress
37994 * g_unix_socket_address_new_abstract:
37995 * @path: (array length=path_len) (element-type gchar): the abstract name
37996 * @path_len: the length of @path, or -1
37998 * Creates a new %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED
37999 * #GUnixSocketAddress for @path.
38001 * Returns: a new #GUnixSocketAddress
38002 * Deprecated: Use g_unix_socket_address_new_with_type().
38007 * g_unix_socket_address_new_with_type:
38008 * @path: (array length=path_len) (element-type gchar): the name
38009 * @path_len: the length of @path, or -1
38010 * @type: a #GUnixSocketAddressType
38012 * Creates a new #GUnixSocketAddress of type @type with name @path.
38014 * If @type is %G_UNIX_SOCKET_ADDRESS_PATH, this is equivalent to
38015 * calling g_unix_socket_address_new().
38017 * If @path_type is %G_UNIX_SOCKET_ADDRESS_ABSTRACT, then @path_len
38018 * bytes of @path will be copied to the socket's path, and only those
38019 * bytes will be considered part of the name. (If @path_len is -1,
38020 * then @path is assumed to be NUL-terminated.) For example, if @path
38021 * was "test", then calling g_socket_address_get_native_size() on the
38022 * returned socket would return 7 (2 bytes of overhead, 1 byte for the
38023 * abstract-socket indicator byte, and 4 bytes for the name "test").
38025 * If @path_type is %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED, then
38026 * @path_len bytes of @path will be copied to the socket's path, the
38027 * rest of the path will be padded with 0 bytes, and the entire
38028 * zero-padded buffer will be considered the name. (As above, if
38029 * @path_len is -1, then @path is assumed to be NUL-terminated.) In
38030 * this case, g_socket_address_get_native_size() will always return
38031 * the full size of a `struct sockaddr_un`, although
38032 * g_unix_socket_address_get_path_len() will still return just the
38035 * %G_UNIX_SOCKET_ADDRESS_ABSTRACT is preferred over
38036 * %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED for new programs. Of course,
38037 * when connecting to a server created by another process, you must
38038 * use the appropriate type corresponding to how that process created
38039 * its listening socket.
38041 * Returns: a new #GUnixSocketAddress
38047 * g_vfs_get_default:
38049 * Gets the default #GVfs for the system.
38051 * Returns: (transfer none): a #GVfs.
38056 * g_vfs_get_file_for_path:
38058 * @path: a string containing a VFS path.
38060 * Gets a #GFile for @path.
38062 * Returns: (transfer full): a #GFile.
38063 * Free the returned object with g_object_unref().
38068 * g_vfs_get_file_for_uri:
38070 * @uri: a string containing a URI
38072 * Gets a #GFile for @uri.
38074 * This operation never fails, but the returned object
38075 * might not support any I/O operation if the URI
38076 * is malformed or if the URI scheme is not supported.
38078 * Returns: (transfer full): a #GFile.
38079 * Free the returned object with g_object_unref().
38086 * Gets the local #GVfs for the system.
38088 * Returns: (transfer none): a #GVfs.
38093 * g_vfs_get_supported_uri_schemes:
38096 * Gets a list of URI schemes supported by @vfs.
38098 * Returns: (transfer none): a %NULL-terminated array of strings.
38099 * The returned array belongs to GIO and must
38100 * not be freed or modified.
38108 * Checks if the VFS is active.
38110 * Returns: %TRUE if construction of the @vfs was successful
38111 * and it is now active.
38116 * g_vfs_parse_name:
38118 * @parse_name: a string to be parsed by the VFS module.
38120 * This operation never fails, but the returned object might
38121 * not support any I/O operations if the @parse_name cannot
38122 * be parsed by the #GVfs module.
38124 * Returns: (transfer full): a #GFile for the given @parse_name.
38125 * Free the returned object with g_object_unref().
38130 * g_volume_can_eject:
38131 * @volume: a #GVolume
38133 * Checks if a volume can be ejected.
38135 * Returns: %TRUE if the @volume can be ejected. %FALSE otherwise
38140 * g_volume_can_mount:
38141 * @volume: a #GVolume
38143 * Checks if a volume can be mounted.
38145 * Returns: %TRUE if the @volume can be mounted. %FALSE otherwise
38151 * @volume: a #GVolume
38152 * @flags: flags affecting the unmount if required for eject
38153 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
38154 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL
38155 * @user_data: user data that gets passed to @callback
38157 * Ejects a volume. This is an asynchronous operation, and is
38158 * finished by calling g_volume_eject_finish() with the @volume
38159 * and #GAsyncResult returned in the @callback.
38161 * Deprecated: 2.22: Use g_volume_eject_with_operation() instead.
38166 * g_volume_eject_finish:
38167 * @volume: pointer to a #GVolume
38168 * @result: a #GAsyncResult
38169 * @error: a #GError location to store an error, or %NULL to ignore
38171 * Finishes ejecting a volume. If any errors occurred during the operation,
38172 * @error will be set to contain the errors and %FALSE will be returned.
38174 * Returns: %TRUE, %FALSE if operation failed
38175 * Deprecated: 2.22: Use g_volume_eject_with_operation_finish() instead.
38180 * g_volume_eject_with_operation:
38181 * @volume: a #GVolume
38182 * @flags: flags affecting the unmount if required for eject
38183 * @mount_operation: (allow-none): a #GMountOperation or %NULL to
38184 * avoid user interaction
38185 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
38186 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL
38187 * @user_data: user data passed to @callback
38189 * Ejects a volume. This is an asynchronous operation, and is
38190 * finished by calling g_volume_eject_with_operation_finish() with the @volume
38191 * and #GAsyncResult data returned in the @callback.
38198 * g_volume_eject_with_operation_finish:
38199 * @volume: a #GVolume
38200 * @result: a #GAsyncResult
38201 * @error: a #GError location to store the error occurring, or %NULL
38203 * Finishes ejecting a volume. If any errors occurred during the operation,
38204 * @error will be set to contain the errors and %FALSE will be returned.
38206 * Returns: %TRUE if the volume was successfully ejected. %FALSE otherwise
38212 * g_volume_enumerate_identifiers:
38213 * @volume: a #GVolume
38215 * Gets the kinds of [identifiers][volume-identifier] that @volume has.
38216 * Use g_volume_get_identifier() to obtain the identifiers themselves.
38218 * Returns: (array zero-terminated=1) (transfer full): a %NULL-terminated array
38219 * of strings containing kinds of identifiers. Use g_strfreev() to free.
38224 * g_volume_get_activation_root:
38225 * @volume: a #GVolume
38227 * Gets the activation root for a #GVolume if it is known ahead of
38228 * mount time. Returns %NULL otherwise. If not %NULL and if @volume
38229 * is mounted, then the result of g_mount_get_root() on the
38230 * #GMount object obtained from g_volume_get_mount() will always
38231 * either be equal or a prefix of what this function returns. In
38232 * other words, in code
38234 * |[<!-- language="C" -->
38236 * GFile *mount_root
38237 * GFile *volume_activation_root;
38239 * mount = g_volume_get_mount (volume); // mounted, so never NULL
38240 * mount_root = g_mount_get_root (mount);
38241 * volume_activation_root = g_volume_get_activation_root (volume); // assume not NULL
38243 * then the expression
38244 * |[<!-- language="C" -->
38245 * (g_file_has_prefix (volume_activation_root, mount_root) ||
38246 * g_file_equal (volume_activation_root, mount_root))
38248 * will always be %TRUE.
38250 * Activation roots are typically used in #GVolumeMonitor
38251 * implementations to find the underlying mount to shadow, see
38252 * g_mount_is_shadowed() for more details.
38254 * Returns: (nullable) (transfer full): the activation root of @volume
38255 * or %NULL. Use g_object_unref() to free.
38261 * g_volume_get_drive:
38262 * @volume: a #GVolume
38264 * Gets the drive for the @volume.
38266 * Returns: (transfer full): a #GDrive or %NULL if @volume is not
38267 * associated with a drive. The returned object should be unreffed
38268 * with g_object_unref() when no longer needed.
38273 * g_volume_get_icon:
38274 * @volume: a #GVolume
38276 * Gets the icon for @volume.
38278 * Returns: (transfer full): a #GIcon.
38279 * The returned object should be unreffed with g_object_unref()
38280 * when no longer needed.
38285 * g_volume_get_identifier:
38286 * @volume: a #GVolume
38287 * @kind: the kind of identifier to return
38289 * Gets the identifier of the given kind for @volume.
38290 * See the [introduction][volume-identifier] for more
38291 * information about volume identifiers.
38293 * Returns: a newly allocated string containing the
38294 * requested identfier, or %NULL if the #GVolume
38295 * doesn't have this kind of identifier
38300 * g_volume_get_mount:
38301 * @volume: a #GVolume
38303 * Gets the mount for the @volume.
38305 * Returns: (transfer full): a #GMount or %NULL if @volume isn't mounted.
38306 * The returned object should be unreffed with g_object_unref()
38307 * when no longer needed.
38312 * g_volume_get_name:
38313 * @volume: a #GVolume
38315 * Gets the name of @volume.
38317 * Returns: the name for the given @volume. The returned string should
38318 * be freed with g_free() when no longer needed.
38323 * g_volume_get_sort_key:
38324 * @volume: a #GVolume
38326 * Gets the sort key for @volume, if any.
38328 * Returns: Sorting key for @volume or %NULL if no such key is available
38334 * g_volume_get_symbolic_icon:
38335 * @volume: a #GVolume
38337 * Gets the symbolic icon for @volume.
38339 * Returns: (transfer full): a #GIcon.
38340 * The returned object should be unreffed with g_object_unref()
38341 * when no longer needed.
38347 * g_volume_get_uuid:
38348 * @volume: a #GVolume
38350 * Gets the UUID for the @volume. The reference is typically based on
38351 * the file system UUID for the volume in question and should be
38352 * considered an opaque string. Returns %NULL if there is no UUID
38355 * Returns: the UUID for @volume or %NULL if no UUID can be computed.
38356 * The returned string should be freed with g_free()
38357 * when no longer needed.
38362 * g_volume_monitor_adopt_orphan_mount:
38363 * @mount: a #GMount object to find a parent for
38365 * This function should be called by any #GVolumeMonitor
38366 * implementation when a new #GMount object is created that is not
38367 * associated with a #GVolume object. It must be called just before
38368 * emitting the @mount_added signal.
38370 * If the return value is not %NULL, the caller must associate the
38371 * returned #GVolume object with the #GMount. This involves returning
38372 * it in its g_mount_get_volume() implementation. The caller must
38373 * also listen for the "removed" signal on the returned object
38374 * and give up its reference when handling that signal
38376 * Similary, if implementing g_volume_monitor_adopt_orphan_mount(),
38377 * the implementor must take a reference to @mount and return it in
38378 * its g_volume_get_mount() implemented. Also, the implementor must
38379 * listen for the "unmounted" signal on @mount and give up its
38380 * reference upon handling that signal.
38382 * There are two main use cases for this function.
38384 * One is when implementing a user space file system driver that reads
38385 * blocks of a block device that is already represented by the native
38386 * volume monitor (for example a CD Audio file system driver). Such
38387 * a driver will generate its own #GMount object that needs to be
38388 * associated with the #GVolume object that represents the volume.
38390 * The other is for implementing a #GVolumeMonitor whose sole purpose
38391 * is to return #GVolume objects representing entries in the users
38392 * "favorite servers" list or similar.
38394 * Returns: (transfer full): the #GVolume object that is the parent for @mount or %NULL
38395 * if no wants to adopt the #GMount.
38396 * Deprecated: 2.20: Instead of using this function, #GVolumeMonitor
38397 * implementations should instead create shadow mounts with the URI of
38398 * the mount they intend to adopt. See the proxy volume monitor in
38399 * gvfs for an example of this. Also see g_mount_is_shadowed(),
38400 * g_mount_shadow() and g_mount_unshadow() functions.
38405 * g_volume_monitor_get:
38407 * Gets the volume monitor used by gio.
38409 * Returns: (transfer full): a reference to the #GVolumeMonitor used by gio. Call
38410 * g_object_unref() when done with it.
38415 * g_volume_monitor_get_connected_drives:
38416 * @volume_monitor: a #GVolumeMonitor.
38418 * Gets a list of drives connected to the system.
38420 * The returned list should be freed with g_list_free(), after
38421 * its elements have been unreffed with g_object_unref().
38423 * Returns: (element-type GDrive) (transfer full): a #GList of connected #GDrive objects.
38428 * g_volume_monitor_get_mount_for_uuid:
38429 * @volume_monitor: a #GVolumeMonitor.
38430 * @uuid: the UUID to look for
38432 * Finds a #GMount object by its UUID (see g_mount_get_uuid())
38434 * Returns: (transfer full): a #GMount or %NULL if no such mount is available.
38435 * Free the returned object with g_object_unref().
38440 * g_volume_monitor_get_mounts:
38441 * @volume_monitor: a #GVolumeMonitor.
38443 * Gets a list of the mounts on the system.
38445 * The returned list should be freed with g_list_free(), after
38446 * its elements have been unreffed with g_object_unref().
38448 * Returns: (element-type GMount) (transfer full): a #GList of #GMount objects.
38453 * g_volume_monitor_get_volume_for_uuid:
38454 * @volume_monitor: a #GVolumeMonitor.
38455 * @uuid: the UUID to look for
38457 * Finds a #GVolume object by its UUID (see g_volume_get_uuid())
38459 * Returns: (transfer full): a #GVolume or %NULL if no such volume is available.
38460 * Free the returned object with g_object_unref().
38465 * g_volume_monitor_get_volumes:
38466 * @volume_monitor: a #GVolumeMonitor.
38468 * Gets a list of the volumes on the system.
38470 * The returned list should be freed with g_list_free(), after
38471 * its elements have been unreffed with g_object_unref().
38473 * Returns: (element-type GVolume) (transfer full): a #GList of #GVolume objects.
38478 * g_volume_mount: (virtual mount_fn)
38479 * @volume: a #GVolume
38480 * @flags: flags affecting the operation
38481 * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction
38482 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
38483 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL
38484 * @user_data: user data that gets passed to @callback
38486 * Mounts a volume. This is an asynchronous operation, and is
38487 * finished by calling g_volume_mount_finish() with the @volume
38488 * and #GAsyncResult returned in the @callback.
38493 * g_volume_mount_finish:
38494 * @volume: a #GVolume
38495 * @result: a #GAsyncResult
38496 * @error: a #GError location to store an error, or %NULL to ignore
38498 * Finishes mounting a volume. If any errors occurred during the operation,
38499 * @error will be set to contain the errors and %FALSE will be returned.
38501 * If the mount operation succeeded, g_volume_get_mount() on @volume
38502 * is guaranteed to return the mount right after calling this
38503 * function; there's no need to listen for the 'mount-added' signal on
38506 * Returns: %TRUE, %FALSE if operation failed
38511 * g_volume_should_automount:
38512 * @volume: a #GVolume
38514 * Returns whether the volume should be automatically mounted.
38516 * Returns: %TRUE if the volume should be automatically mounted
38521 * g_win32_input_stream_get_close_handle:
38522 * @stream: a #GWin32InputStream
38524 * Returns whether the handle of @stream will be
38525 * closed when the stream is closed.
38527 * Returns: %TRUE if the handle is closed when done
38533 * g_win32_input_stream_get_handle:
38534 * @stream: a #GWin32InputStream
38536 * Return the Windows file handle that the stream reads from.
38538 * Returns: The file handle of @stream
38544 * g_win32_input_stream_new:
38545 * @handle: a Win32 file handle
38546 * @close_handle: %TRUE to close the handle when done
38548 * Creates a new #GWin32InputStream for the given @handle.
38550 * If @close_handle is %TRUE, the handle will be closed
38551 * when the stream is closed.
38553 * Note that "handle" here means a Win32 HANDLE, not a "file descriptor"
38554 * as used in the Windows C libraries.
38556 * Returns: a new #GWin32InputStream
38561 * g_win32_input_stream_set_close_handle:
38562 * @stream: a #GWin32InputStream
38563 * @close_handle: %TRUE to close the handle when done
38565 * Sets whether the handle of @stream shall be closed
38566 * when the stream is closed.
38573 * g_win32_output_stream_get_close_handle:
38574 * @stream: a #GWin32OutputStream
38576 * Returns whether the handle of @stream will be closed when the
38577 * stream is closed.
38579 * Returns: %TRUE if the handle is closed when done
38585 * g_win32_output_stream_get_handle:
38586 * @stream: a #GWin32OutputStream
38588 * Return the Windows handle that the stream writes to.
38590 * Returns: The handle descriptor of @stream
38596 * g_win32_output_stream_new:
38597 * @handle: a Win32 file handle
38598 * @close_handle: %TRUE to close the handle when done
38600 * Creates a new #GWin32OutputStream for the given @handle.
38602 * If @close_handle, is %TRUE, the handle will be closed when the
38603 * output stream is destroyed.
38605 * Returns: a new #GOutputStream
38611 * g_win32_output_stream_set_close_handle:
38612 * @stream: a #GWin32OutputStream
38613 * @close_handle: %TRUE to close the handle when done
38615 * Sets whether the handle of @stream shall be closed when the stream
38623 * g_zlib_compressor_get_file_info:
38624 * @compressor: a #GZlibCompressor
38626 * Returns the #GZlibCompressor:file-info property.
38628 * Returns: (transfer none): a #GFileInfo, or %NULL
38634 * g_zlib_compressor_new:
38635 * @format: The format to use for the compressed data
38636 * @level: compression level (0-9), -1 for default
38638 * Creates a new #GZlibCompressor.
38640 * Returns: a new #GZlibCompressor
38646 * g_zlib_compressor_set_file_info:
38647 * @compressor: a #GZlibCompressor
38648 * @file_info: (allow-none): a #GFileInfo
38650 * Sets @file_info in @compressor. If non-%NULL, and @compressor's
38651 * #GZlibCompressor:format property is %G_ZLIB_COMPRESSOR_FORMAT_GZIP,
38652 * it will be used to set the file name and modification time in
38653 * the GZIP header of the compressed data.
38655 * Note: it is an error to call this function while a compression is in
38656 * progress; it may only be called immediately after creation of @compressor,
38657 * or after resetting it with g_converter_reset().
38664 * g_zlib_decompressor_get_file_info:
38665 * @decompressor: a #GZlibDecompressor
38667 * Retrieves the #GFileInfo constructed from the GZIP header data
38668 * of compressed data processed by @compressor, or %NULL if @decompressor's
38669 * #GZlibDecompressor:format property is not %G_ZLIB_COMPRESSOR_FORMAT_GZIP,
38670 * or the header data was not fully processed yet, or it not present in the
38671 * data stream at all.
38673 * Returns: (transfer none): a #GFileInfo, or %NULL
38679 * g_zlib_decompressor_new:
38680 * @format: The format to use for the compressed data
38682 * Creates a new #GZlibDecompressor.
38684 * Returns: a new #GZlibDecompressor
38690 * get_viewable_logical_drives:
38692 * Returns the list of logical and viewable drives as defined by
38693 * GetLogicalDrives() and the registry keys
38694 * Software\Microsoft\Windows\CurrentVersion\Policies\Explorer under
38695 * HKLM or HKCU. If neither key exists the result of
38696 * GetLogicalDrives() is returned.
38698 * Returns: bitmask with same meaning as returned by GetLogicalDrives()
38703 /************************************************************/
38704 /* THIS FILE IS GENERATED DO NOT EDIT */
38705 /************************************************************/