1 /************************************************************/
2 /* THIS FILE IS GENERATED DO NOT EDIT */
3 /************************************************************/
8 * #GAction is an opaque data structure and can only be accessed
9 * using the following functions.
16 * If @action is currently enabled.
18 * If the action is disabled then calls to g_action_activate() and
19 * g_action_change_state() have no effect.
28 * The name of the action. This is mostly meaningful for identifying
29 * the action once it has been added to a #GActionGroup. It is immutable.
36 * GAction:parameter-type:
38 * The type of the parameter that must be given when activating the
39 * action. This is immutable, and may be %NULL if no parameter is needed when
40 * activating the action.
49 * The state of the action, or %NULL if the action is stateless.
58 * The #GVariantType of the state that the action has, or %NULL if the
59 * action is stateless. This is immutable.
67 * @name: the name of the action
68 * @activate: the callback to connect to the "activate" signal of the
69 * action. Since GLib 2.40, this can be %NULL for stateful
70 * actions, in which case the default handler is used. For
71 * boolean-stated actions with no parameter, this is a
72 * toggle. For other state types (and parameter type equal
73 * to the state type) this will be a function that
74 * just calls @change_state (which you should provide).
75 * @parameter_type: the type of the parameter that must be passed to the
76 * activate function for this action, given as a single
77 * GVariant type string (or %NULL for no parameter)
78 * @state: the initial state for this action, given in
79 * [GVariant text format][gvariant-text]. The state is parsed
80 * with no extra type information, so type tags must be added to
81 * the string if they are necessary. Stateless actions should
83 * @change_state: the callback to connect to the "change-state" signal
84 * of the action. All stateful actions should provide a
85 * handler here; stateless actions should not.
87 * This struct defines a single action. It is for use with
88 * g_action_map_add_action_entries().
90 * The order of the items in the structure are intended to reflect
91 * frequency of use. It is permissible to use an incomplete initialiser
92 * in order to leave some of the later values as %NULL. All values
93 * after @name are optional. Additional optional fields may be added in
96 * See g_action_map_add_action_entries() for an example.
103 * #GActionGroup is an opaque data structure and can only be accessed
104 * using the following functions.
109 * GActionGroup::action-added:
110 * @action_group: the #GActionGroup that changed
111 * @action_name: the name of the action in @action_group
113 * Signals that a new action was just added to the group.
114 * This signal is emitted after the action has been added
115 * and is now visible.
122 * GActionGroup::action-enabled-changed:
123 * @action_group: the #GActionGroup that changed
124 * @action_name: the name of the action in @action_group
125 * @enabled: whether the action is enabled or not
127 * Signals that the enabled status of the named action has changed.
134 * GActionGroup::action-removed:
135 * @action_group: the #GActionGroup that changed
136 * @action_name: the name of the action in @action_group
138 * Signals that an action is just about to be removed from the group.
139 * This signal is emitted before the action is removed, so the action
140 * is still visible and can be queried from the signal handler.
147 * GActionGroup::action-state-changed:
148 * @action_group: the #GActionGroup that changed
149 * @action_name: the name of the action in @action_group
150 * @value: the new value of the state
152 * Signals that the state of the named action has changed.
159 * GActionGroupInterface:
160 * @has_action: the virtual function pointer for g_action_group_has_action()
161 * @list_actions: the virtual function pointer for g_action_group_list_actions()
162 * @get_action_parameter_type: the virtual function pointer for g_action_group_get_action_parameter_type()
163 * @get_action_state_type: the virtual function pointer for g_action_group_get_action_state_type()
164 * @get_action_state_hint: the virtual function pointer for g_action_group_get_action_state_hint()
165 * @get_action_enabled: the virtual function pointer for g_action_group_get_action_enabled()
166 * @get_action_state: the virtual function pointer for g_action_group_get_action_state()
167 * @change_action_state: the virtual function pointer for g_action_group_change_action_state()
168 * @query_action: the virtual function pointer for g_action_group_query_action()
169 * @activate_action: the virtual function pointer for g_action_group_activate_action()
170 * @action_added: the class closure for the #GActionGroup::action-added signal
171 * @action_removed: the class closure for the #GActionGroup::action-removed signal
172 * @action_enabled_changed: the class closure for the #GActionGroup::action-enabled-changed signal
173 * @action_state_changed: the class closure for the #GActionGroup::action-enabled-changed signal
175 * The virtual function table for #GActionGroup.
183 * @get_name: the virtual function pointer for g_action_get_name()
184 * @get_parameter_type: the virtual function pointer for g_action_get_parameter_type()
185 * @get_state_type: the virtual function pointer for g_action_get_state_type()
186 * @get_state_hint: the virtual function pointer for g_action_get_state_hint()
187 * @get_enabled: the virtual function pointer for g_action_get_enabled()
188 * @get_state: the virtual function pointer for g_action_get_state()
189 * @change_state: the virtual function pointer for g_action_change_state()
190 * @activate: the virtual function pointer for g_action_activate(). Note that #GAction does not have an
191 * 'activate' signal but that implementations of it may have one.
193 * The virtual function table for #GAction.
202 * #GActionMap is an opaque data structure and can only be accessed
203 * using the following functions.
208 * GActionMapInterface:
209 * @lookup_action: the virtual function pointer for g_action_map_lookup_action()
210 * @add_action: the virtual function pointer for g_action_map_add_action()
211 * @remove_action: the virtual function pointer for g_action_map_remove_action()
213 * The virtual function table for #GActionMap.
222 * The only thing you can do with this is to get it via
223 * g_app_info_monitor_get() and connect to the "changed" signal.
230 * GAppInfoMonitor::changed:
232 * Signal emitted when the app info database for changes (ie: newly installed
233 * or removed applications).
238 * GAppLaunchContext::launch-failed:
239 * @context: the object emitting the signal
240 * @startup_notify_id: the startup notification id for the failed launch
242 * The ::launch-failed signal is emitted when a #GAppInfo launch
243 * fails. The startup notification id is provided, so that the launcher
244 * can cancel the startup notification.
251 * GAppLaunchContext::launched:
252 * @context: the object emitting the signal
253 * @info: the #GAppInfo that was just launched
254 * @platform_data: additional platform-specific data for this launch
256 * The ::launched signal is emitted when a #GAppInfo is successfully
257 * launched. The @platform_data is an GVariant dictionary mapping
258 * strings to variants (ie a{sv}), which contains additional,
259 * platform-specific data about this launch. On UNIX, at least the
260 * "pid" and "startup-notification-id" keys will be present.
269 * #GApplication is an opaque data structure and can only be accessed
270 * using the following functions.
277 * GApplication::activate:
278 * @application: the application
280 * The ::activate signal is emitted on the primary instance when an
281 * activation occurs. See g_application_activate().
286 * GApplication::command-line:
287 * @application: the application
288 * @command_line: a #GApplicationCommandLine representing the
291 * The ::command-line signal is emitted on the primary instance when
292 * a commandline is not handled locally. See g_application_run() and
293 * the #GApplicationCommandLine documentation for more information.
295 * Returns: An integer that is set as the exit status for the calling
296 * process. See g_application_command_line_set_exit_status().
301 * GApplication::handle-local-options:
302 * @application: the application
303 * @options: the options dictionary
305 * The ::handle-local-options signal is emitted on the local instance
306 * after the parsing of the commandline options has occurred.
308 * You can add options to be recognised during commandline option
309 * parsing using g_application_add_main_option_entries() and
310 * g_application_add_option_group().
312 * Signal handlers can inspect @options (along with values pointed to
313 * from the @arg_data of an installed #GOptionEntrys) in order to
314 * decide to perform certain actions, including direct local handling
315 * (which may be useful for options like --version).
317 * In the event that the application is marked
318 * %G_APPLICATION_HANDLES_COMMAND_LINE the "normal processing" will
319 * send the @options dictionary to the primary instance where it can be
320 * read with g_application_command_line_get_options_dict(). The signal
321 * handler can modify the dictionary before returning, and the
322 * modified dictionary will be sent.
324 * In the event that %G_APPLICATION_HANDLES_COMMAND_LINE is not set,
325 * "normal processing" will treat the remaining uncollected command
326 * line arguments as filenames or URIs. If there are no arguments,
327 * the application is activated by g_application_activate(). One or
328 * more arguments results in a call to g_application_open().
330 * If you want to handle the local commandline arguments for yourself
331 * by converting them to calls to g_application_open() or
332 * g_action_group_activate_action() then you must be sure to register
333 * the application first. You should probably not call
334 * g_application_activate() for yourself, however: just return -1 and
335 * allow the default handler to do it for you. This will ensure that
336 * the `--gapplication-service` switch works properly (i.e. no activation
339 * Note that this signal is emitted from the default implementation of
340 * local_command_line(). If you override that function and don't
341 * chain up then this signal will never be emitted.
343 * You can override local_command_line() if you need more powerful
344 * capabilities than what is provided here, but this should not
345 * normally be required.
347 * Returns: an exit code. If you have handled your options and want
348 * to exit the process, return a non-negative option, 0 for success,
349 * and a positive value for failure. To continue, return -1 to let
350 * the default option processing continue.
356 * GApplication::name-lost:
357 * @application: the application
359 * The ::name-lost signal is emitted only on the registered primary instance
360 * when a new instance has taken over. This can only happen if the application
361 * is using the %G_APPLICATION_ALLOW_REPLACEMENT flag.
363 * The default handler for this signal calls g_application_quit().
365 * Returns: %TRUE if the signal has been handled
371 * GApplication::open:
372 * @application: the application
373 * @files: (array length=n_files) (element-type GFile): an array of #GFiles
374 * @n_files: the length of @files
375 * @hint: a hint provided by the calling instance
377 * The ::open signal is emitted on the primary instance when there are
378 * files to open. See g_application_open() for more information.
383 * GApplication::shutdown:
384 * @application: the application
386 * The ::shutdown signal is emitted only on the registered primary instance
387 * immediately after the main loop terminates.
392 * GApplication::startup:
393 * @application: the application
395 * The ::startup signal is emitted on the primary instance immediately
396 * after registration. See g_application_register().
401 * GApplication:is-busy:
403 * Whether the application is currently marked as busy through
404 * g_application_mark_busy() or g_application_bind_busy_property().
412 * @startup: invoked on the primary instance immediately after registration
413 * @shutdown: invoked only on the registered primary instance immediately
414 * after the main loop terminates
415 * @activate: invoked on the primary instance when an activation occurs
416 * @open: invoked on the primary instance when there are files to open
417 * @command_line: invoked on the primary instance when a command-line is
418 * not handled locally
419 * @local_command_line: invoked (locally). The virtual function has the chance
420 * to inspect (and possibly replace) command line arguments. See
421 * g_application_run() for more information. Also see the
422 * #GApplication::handle-local-options signal, which is a simpler
423 * alternative to handling some commandline options locally
424 * @before_emit: invoked on the primary instance before 'activate', 'open',
425 * 'command-line' or any action invocation, gets the 'platform data' from
426 * the calling instance
427 * @after_emit: invoked on the primary instance after 'activate', 'open',
428 * 'command-line' or any action invocation, gets the 'platform data' from
429 * the calling instance
430 * @add_platform_data: invoked (locally) to add 'platform data' to be sent to
431 * the primary instance when activating, opening or invoking actions
432 * @quit_mainloop: Used to be invoked on the primary instance when the use
433 * count of the application drops to zero (and after any inactivity
434 * timeout, if requested). Not used anymore since 2.32
435 * @run_mainloop: Used to be invoked on the primary instance from
436 * g_application_run() if the use-count is non-zero. Since 2.32,
437 * GApplication is iterating the main context directly and is not
438 * using @run_mainloop anymore
439 * @dbus_register: invoked locally during registration, if the application is
440 * using its D-Bus backend. You can use this to export extra objects on the
441 * bus, that need to exist before the application tries to own the bus name.
442 * The function is passed the #GDBusConnection to to session bus, and the
443 * object path that #GApplication will use to export is D-Bus API.
444 * If this function returns %TRUE, registration will proceed; otherwise
445 * registration will abort. Since: 2.34
446 * @dbus_unregister: invoked locally during unregistration, if the application
447 * is using its D-Bus backend. Use this to undo anything done by
448 * the @dbus_register vfunc. Since: 2.34
449 * @handle_local_options: invoked locally after the parsing of the commandline
450 * options has occurred. Since: 2.40
451 * @name_lost: invoked when another instance is taking over the name. Since: 2.60
453 * Virtual function table for #GApplication.
460 * GApplicationCommandLine:
462 * #GApplicationCommandLine is an opaque data structure and can only be accessed
463 * using the following functions.
468 * GApplicationCommandLineClass:
470 * The #GApplicationCommandLineClass-struct
471 * contains private data only.
480 * The bytes containing the icon.
485 * GCancellable::cancelled:
486 * @cancellable: a #GCancellable.
488 * Emitted when the operation has been cancelled.
490 * Can be used by implementations of cancellable operations. If the
491 * operation is cancelled from another thread, the signal will be
492 * emitted in the thread that cancelled the operation, not the
493 * thread that is running the operation.
495 * Note that disconnecting from this signal (or any signal) in a
496 * multi-threaded program is prone to race conditions. For instance
497 * it is possible that a signal handler may be invoked even after
498 * a call to g_signal_handler_disconnect() for that handler has
501 * There is also a problem when cancellation happens right before
502 * connecting to the signal. If this happens the signal will
503 * unexpectedly not be emitted, and checking before connecting to
504 * the signal leaves a race condition where this is still happening.
506 * In order to make it safe and easy to connect handlers there
507 * are two helper functions: g_cancellable_connect() and
508 * g_cancellable_disconnect() which protect against problems
511 * An example of how to us this:
512 * |[<!-- language="C" -->
513 * // Make sure we don't do unnecessary work if already cancelled
514 * if (g_cancellable_set_error_if_cancelled (cancellable, error))
517 * // Set up all the data needed to be able to handle cancellation
518 * // of the operation
519 * my_data = my_data_new (...);
523 * id = g_cancellable_connect (cancellable,
524 * G_CALLBACK (cancelled_handler)
527 * // cancellable operation here...
529 * g_cancellable_disconnect (cancellable, id);
531 * // cancelled_handler is never called after this, it is now safe
532 * // to free the data
533 * my_data_free (my_data);
536 * Note that the cancelled signal is emitted in the thread that
537 * the user cancelled from, which may be the main thread. So, the
538 * cancellable signal should not do something that can block.
545 * Conversions between character sets.
552 * The #GCredentials structure contains only private data and
553 * should only be accessed using the provided API.
562 * Class structure for #GCredentials.
571 * #GDBusActionGroup is an opaque data structure and can only be accessed
572 * using the following functions.
577 * GDBusAuthMechanism:credentials:
579 * If authenticating as a server, this property contains the
580 * received credentials, if any.
582 * If authenticating as a client, the property contains the
583 * credentials that were sent, if any.
590 * The #GDBusAuthObserver structure contains only private data and
591 * should only be accessed using the provided API.
598 * GDBusAuthObserver::allow-mechanism:
599 * @observer: The #GDBusAuthObserver emitting the signal.
600 * @mechanism: The name of the mechanism, e.g. `DBUS_COOKIE_SHA1`.
602 * Emitted to check if @mechanism is allowed to be used.
604 * Returns: %TRUE if @mechanism can be used to authenticate the other peer, %FALSE if not.
610 * GDBusAuthObserver::authorize-authenticated-peer:
611 * @observer: The #GDBusAuthObserver emitting the signal.
612 * @stream: A #GIOStream for the #GDBusConnection.
613 * @credentials: (nullable): Credentials received from the peer or %NULL.
615 * Emitted to check if a peer that is successfully authenticated
618 * Returns: %TRUE if the peer is authorized, %FALSE if not.
624 * GDBusAuthObserverClass:
625 * @authorize_authenticated_peer: Signal class handler for the #GDBusAuthObserver::authorize-authenticated-peer signal.
627 * Class structure for #GDBusAuthObserverClass.
636 * The #GDBusConnection structure contains only private data and
637 * should only be accessed using the provided API.
644 * GDBusConnection::closed:
645 * @connection: the #GDBusConnection emitting the signal
646 * @remote_peer_vanished: %TRUE if @connection is closed because the
647 * remote peer closed its end of the connection
648 * @error: (nullable): a #GError with more details about the event or %NULL
650 * Emitted when the connection is closed.
652 * The cause of this event can be
654 * - If g_dbus_connection_close() is called. In this case
655 * @remote_peer_vanished is set to %FALSE and @error is %NULL.
657 * - If the remote peer closes the connection. In this case
658 * @remote_peer_vanished is set to %TRUE and @error is set.
660 * - If the remote peer sends invalid or malformed data. In this
661 * case @remote_peer_vanished is set to %FALSE and @error is set.
663 * Upon receiving this signal, you should give up your reference to
664 * @connection. You are guaranteed that this signal is emitted only
672 * GDBusConnection:address:
674 * A D-Bus address specifying potential endpoints that can be used
675 * when establishing the connection.
682 * GDBusConnection:authentication-observer:
684 * A #GDBusAuthObserver object to assist in the authentication process or %NULL.
691 * GDBusConnection:capabilities:
693 * Flags from the #GDBusCapabilityFlags enumeration
694 * representing connection features negotiated with the other peer.
701 * GDBusConnection:closed:
703 * A boolean specifying whether the connection has been closed.
710 * GDBusConnection:exit-on-close:
712 * A boolean specifying whether the process will be terminated (by
713 * calling `raise(SIGTERM)`) if the connection is closed by the
716 * Note that #GDBusConnection objects returned by g_bus_get_finish()
717 * and g_bus_get_sync() will (usually) have this property set to %TRUE.
724 * GDBusConnection:flags:
726 * Flags from the #GDBusConnectionFlags enumeration.
733 * GDBusConnection:guid:
735 * The GUID of the peer performing the role of server when
738 * If you are constructing a #GDBusConnection and pass
739 * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER in the
740 * #GDBusConnection:flags property then you **must** also set this
741 * property to a valid guid.
743 * If you are constructing a #GDBusConnection and pass
744 * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_CLIENT in the
745 * #GDBusConnection:flags property you will be able to read the GUID
746 * of the other peer here after the connection has been successfully
750 * [D-Bus specification](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses)
751 * uses the term ‘UUID’ to refer to this, whereas GLib consistently uses the
752 * term ‘GUID’ for historical reasons.
754 * Despite its name, the format of #GDBusConnection:guid does not follow
755 * [RFC 4122](https://datatracker.ietf.org/doc/html/rfc4122) or the Microsoft
763 * GDBusConnection:locked:
765 * A boolean specifying whether the message is locked.
772 * GDBusConnection:stream:
774 * The underlying #GIOStream used for I/O.
776 * If this is passed on construction and is a #GSocketConnection,
777 * then the corresponding #GSocket will be put into non-blocking mode.
779 * While the #GDBusConnection is active, it will interact with this
780 * stream from a worker thread, so it is not safe to interact with
781 * the stream directly.
788 * GDBusConnection:unique-name:
790 * The unique name as assigned by the message bus or %NULL if the
791 * connection is not open or not a message bus connection.
798 * GDBusConnectionClass:
799 * @closed: Signal class handler for the #GDBusConnection::closed signal.
801 * Class structure for #GDBusConnection.
808 * GDBusInterfaceSkeleton::g-authorize-method:
809 * @interface: The #GDBusInterfaceSkeleton emitting the signal.
810 * @invocation: A #GDBusMethodInvocation.
812 * Emitted when a method is invoked by a remote caller and used to
813 * determine if the method call is authorized.
815 * Note that this signal is emitted in a thread dedicated to
816 * handling the method call so handlers are allowed to perform
817 * blocking IO. This means that it is appropriate to call e.g.
818 * [polkit_authority_check_authorization_sync()](http://hal.freedesktop.org/docs/polkit/PolkitAuthority.html#polkit-authority-check-authorization-sync)
820 * [POLKIT_CHECK_AUTHORIZATION_FLAGS_ALLOW_USER_INTERACTION](http://hal.freedesktop.org/docs/polkit/PolkitAuthority.html#POLKIT-CHECK-AUTHORIZATION-FLAGS-ALLOW-USER-INTERACTION:CAPS)
823 * If %FALSE is returned then no further handlers are run and the
824 * signal handler must take a reference to @invocation and finish
825 * handling the call (e.g. return an error via
826 * g_dbus_method_invocation_return_error()).
828 * Otherwise, if %TRUE is returned, signal emission continues. If no
829 * handlers return %FALSE, then the method is dispatched. If
830 * @interface has an enclosing #GDBusObjectSkeleton, then the
831 * #GDBusObjectSkeleton::authorize-method signal handlers run before
832 * the handlers for this signal.
834 * The default class handler just returns %TRUE.
836 * Please note that the common case is optimized: if no signals
837 * handlers are connected and the default class handler isn't
838 * overridden (for both @interface and the enclosing
839 * #GDBusObjectSkeleton, if any) and #GDBusInterfaceSkeleton:g-flags does
841 * %G_DBUS_INTERFACE_SKELETON_FLAGS_HANDLE_METHOD_INVOCATIONS_IN_THREAD
842 * flags set, no dedicated thread is ever used and the call will be
843 * handled in the same thread as the object that @interface belongs
844 * to was exported in.
846 * Returns: %TRUE if the call is authorized, %FALSE otherwise.
852 * GDBusInterfaceSkeleton:g-flags:
854 * Flags from the #GDBusInterfaceSkeletonFlags enumeration.
863 * #GDBusMenuModel is an opaque data structure and can only be accessed
864 * using the following functions.
871 * The #GDBusMessage structure contains only private data and should
872 * only be accessed using the provided API.
881 * Class structure for #GDBusMessage.
888 * GDBusMethodInvocation:
890 * The #GDBusMethodInvocation structure contains only private data and
891 * should only be accessed using the provided API.
898 * GDBusMethodInvocationClass:
900 * Class structure for #GDBusMethodInvocation.
909 * #GDBusObject is an opaque data structure and can only be accessed
910 * using the following functions.
915 * GDBusObject::interface-added:
916 * @object: The #GDBusObject emitting the signal.
917 * @interface: The #GDBusInterface that was added.
919 * Emitted when @interface is added to @object.
926 * GDBusObject::interface-removed:
927 * @object: The #GDBusObject emitting the signal.
928 * @interface: The #GDBusInterface that was removed.
930 * Emitted when @interface is removed from @object.
937 * GDBusObjectManager:
939 * #GDBusObjectManager is an opaque data structure and can only be accessed
940 * using the following functions.
945 * GDBusObjectManager::interface-added:
946 * @manager: The #GDBusObjectManager emitting the signal.
947 * @object: The #GDBusObject on which an interface was added.
948 * @interface: The #GDBusInterface that was added.
950 * Emitted when @interface is added to @object.
952 * This signal exists purely as a convenience to avoid having to
953 * connect signals to all objects managed by @manager.
960 * GDBusObjectManager::interface-removed:
961 * @manager: The #GDBusObjectManager emitting the signal.
962 * @object: The #GDBusObject on which an interface was removed.
963 * @interface: The #GDBusInterface that was removed.
965 * Emitted when @interface has been removed from @object.
967 * This signal exists purely as a convenience to avoid having to
968 * connect signals to all objects managed by @manager.
975 * GDBusObjectManager::object-added:
976 * @manager: The #GDBusObjectManager emitting the signal.
977 * @object: The #GDBusObject that was added.
979 * Emitted when @object is added to @manager.
986 * GDBusObjectManager::object-removed:
987 * @manager: The #GDBusObjectManager emitting the signal.
988 * @object: The #GDBusObject that was removed.
990 * Emitted when @object is removed from @manager.
997 * GDBusObjectManagerClient::interface-proxy-properties-changed:
998 * @manager: The #GDBusObjectManagerClient emitting the signal.
999 * @object_proxy: The #GDBusObjectProxy on which an interface has properties that are changing.
1000 * @interface_proxy: The #GDBusProxy that has properties that are changing.
1001 * @changed_properties: A #GVariant containing the properties that changed (type: `a{sv}`).
1002 * @invalidated_properties: (array zero-terminated=1) (element-type utf8): A %NULL terminated
1003 * array of properties that were invalidated.
1005 * Emitted when one or more D-Bus properties on proxy changes. The
1006 * local cache has already been updated when this signal fires. Note
1007 * that both @changed_properties and @invalidated_properties are
1008 * guaranteed to never be %NULL (either may be empty though).
1010 * This signal exists purely as a convenience to avoid having to
1011 * connect signals to all interface proxies managed by @manager.
1013 * This signal is emitted in the
1014 * [thread-default main context][g-main-context-push-thread-default]
1015 * that @manager was constructed in.
1022 * GDBusObjectManagerClient::interface-proxy-signal:
1023 * @manager: The #GDBusObjectManagerClient emitting the signal.
1024 * @object_proxy: The #GDBusObjectProxy on which an interface is emitting a D-Bus signal.
1025 * @interface_proxy: The #GDBusProxy that is emitting a D-Bus signal.
1026 * @sender_name: The sender of the signal or NULL if the connection is not a bus connection.
1027 * @signal_name: The signal name.
1028 * @parameters: A #GVariant tuple with parameters for the signal.
1030 * Emitted when a D-Bus signal is received on @interface_proxy.
1032 * This signal exists purely as a convenience to avoid having to
1033 * connect signals to all interface proxies managed by @manager.
1035 * This signal is emitted in the
1036 * [thread-default main context][g-main-context-push-thread-default]
1037 * that @manager was constructed in.
1044 * GDBusObjectManagerClient:bus-type:
1046 * If this property is not %G_BUS_TYPE_NONE, then
1047 * #GDBusObjectManagerClient:connection must be %NULL and will be set to the
1048 * #GDBusConnection obtained by calling g_bus_get() with the value
1056 * GDBusObjectManagerClient:connection:
1058 * The #GDBusConnection to use.
1065 * GDBusObjectManagerClient:flags:
1067 * Flags from the #GDBusObjectManagerClientFlags enumeration.
1074 * GDBusObjectManagerClient:get-proxy-type-destroy-notify:
1076 * A #GDestroyNotify for the #gpointer user_data in #GDBusObjectManagerClient:get-proxy-type-user-data.
1083 * GDBusObjectManagerClient:get-proxy-type-func:
1085 * The #GDBusProxyTypeFunc to use when determining what #GType to
1086 * use for interface proxies or %NULL.
1093 * GDBusObjectManagerClient:get-proxy-type-user-data:
1095 * The #gpointer user_data to pass to #GDBusObjectManagerClient:get-proxy-type-func.
1102 * GDBusObjectManagerClient:name:
1104 * The well-known name or unique name that the manager is for.
1111 * GDBusObjectManagerClient:name-owner:
1113 * The unique name that owns #GDBusObjectManagerClient:name or %NULL if
1114 * no-one is currently owning the name. Connect to the
1115 * #GObject::notify signal to track changes to this property.
1122 * GDBusObjectManagerClient:object-path:
1124 * The object path the manager is for.
1131 * GDBusObjectManagerServer:connection:
1133 * The #GDBusConnection to export objects on.
1140 * GDBusObjectManagerServer:object-path:
1142 * The object path to register the manager object at.
1149 * GDBusObjectProxy:g-connection:
1151 * The connection of the proxy.
1158 * GDBusObjectProxy:g-object-path:
1160 * The object path of the proxy.
1167 * GDBusObjectSkeleton::authorize-method:
1168 * @object: The #GDBusObjectSkeleton emitting the signal.
1169 * @interface: The #GDBusInterfaceSkeleton that @invocation is for.
1170 * @invocation: A #GDBusMethodInvocation.
1172 * Emitted when a method is invoked by a remote caller and used to
1173 * determine if the method call is authorized.
1175 * This signal is like #GDBusInterfaceSkeleton's
1176 * #GDBusInterfaceSkeleton::g-authorize-method signal,
1177 * except that it is for the enclosing object.
1179 * The default class handler just returns %TRUE.
1181 * Returns: %TRUE if the call is authorized, %FALSE otherwise.
1187 * GDBusObjectSkeleton:g-object-path:
1189 * The object path where the object is exported.
1196 * GDBusProxy::g-properties-changed:
1197 * @proxy: The #GDBusProxy emitting the signal.
1198 * @changed_properties: A #GVariant containing the properties that changed (type: `a{sv}`)
1199 * @invalidated_properties: A %NULL terminated array of properties that was invalidated
1201 * Emitted when one or more D-Bus properties on @proxy changes. The
1202 * local cache has already been updated when this signal fires. Note
1203 * that both @changed_properties and @invalidated_properties are
1204 * guaranteed to never be %NULL (either may be empty though).
1206 * If the proxy has the flag
1207 * %G_DBUS_PROXY_FLAGS_GET_INVALIDATED_PROPERTIES set, then
1208 * @invalidated_properties will always be empty.
1210 * This signal corresponds to the
1211 * `PropertiesChanged` D-Bus signal on the
1212 * `org.freedesktop.DBus.Properties` interface.
1219 * GDBusProxy::g-signal:
1220 * @proxy: The #GDBusProxy emitting the signal.
1221 * @sender_name: (nullable): The sender of the signal or %NULL if the connection is not a bus connection.
1222 * @signal_name: The name of the signal.
1223 * @parameters: A #GVariant tuple with parameters for the signal.
1225 * Emitted when a signal from the remote object and interface that @proxy is for, has been received.
1232 * GDBusProxy:g-bus-type:
1234 * If this property is not %G_BUS_TYPE_NONE, then
1235 * #GDBusProxy:g-connection must be %NULL and will be set to the
1236 * #GDBusConnection obtained by calling g_bus_get() with the value
1244 * GDBusProxy:g-connection:
1246 * The #GDBusConnection the proxy is for.
1253 * GDBusProxy:g-default-timeout:
1255 * The timeout to use if -1 (specifying default timeout) is passed
1256 * as @timeout_msec in the g_dbus_proxy_call() and
1257 * g_dbus_proxy_call_sync() functions.
1259 * This allows applications to set a proxy-wide timeout for all
1260 * remote method invocations on the proxy. If this property is -1,
1261 * the default timeout (typically 25 seconds) is used. If set to
1262 * %G_MAXINT, then no timeout is used.
1269 * GDBusProxy:g-flags:
1271 * Flags from the #GDBusProxyFlags enumeration.
1278 * GDBusProxy:g-interface-info:
1280 * Ensure that interactions with this proxy conform to the given
1281 * interface. This is mainly to ensure that malformed data received
1282 * from the other peer is ignored. The given #GDBusInterfaceInfo is
1283 * said to be the "expected interface".
1285 * The checks performed are:
1286 * - When completing a method call, if the type signature of
1287 * the reply message isn't what's expected, the reply is
1288 * discarded and the #GError is set to %G_IO_ERROR_INVALID_ARGUMENT.
1290 * - Received signals that have a type signature mismatch are dropped and
1291 * a warning is logged via g_warning().
1293 * - Properties received via the initial `GetAll()` call or via the
1294 * `::PropertiesChanged` signal (on the
1295 * [org.freedesktop.DBus.Properties](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties)
1296 * interface) or set using g_dbus_proxy_set_cached_property()
1297 * with a type signature mismatch are ignored and a warning is
1298 * logged via g_warning().
1300 * Note that these checks are never done on methods, signals and
1301 * properties that are not referenced in the given
1302 * #GDBusInterfaceInfo, since extending a D-Bus interface on the
1303 * service-side is not considered an ABI break.
1310 * GDBusProxy:g-interface-name:
1312 * The D-Bus interface name the proxy is for.
1319 * GDBusProxy:g-name:
1321 * The well-known or unique name that the proxy is for.
1328 * GDBusProxy:g-name-owner:
1330 * The unique name that owns #GDBusProxy:g-name or %NULL if no-one
1331 * currently owns that name. You may connect to #GObject::notify signal to
1332 * track changes to this property.
1339 * GDBusProxy:g-object-path:
1341 * The object path the proxy is for.
1350 * The #GDBusServer structure contains only private data and
1351 * should only be accessed using the provided API.
1358 * GDBusServer::new-connection:
1359 * @server: The #GDBusServer emitting the signal.
1360 * @connection: A #GDBusConnection for the new connection.
1362 * Emitted when a new authenticated connection has been made. Use
1363 * g_dbus_connection_get_peer_credentials() to figure out what
1364 * identity (if any), was authenticated.
1366 * If you want to accept the connection, take a reference to the
1367 * @connection object and return %TRUE. When you are done with the
1368 * connection call g_dbus_connection_close() and give up your
1369 * reference. Note that the other peer may disconnect at any time -
1370 * a typical thing to do when accepting a connection is to listen to
1371 * the #GDBusConnection::closed signal.
1373 * If #GDBusServer:flags contains %G_DBUS_SERVER_FLAGS_RUN_IN_THREAD
1374 * then the signal is emitted in a new thread dedicated to the
1375 * connection. Otherwise the signal is emitted in the
1376 * [thread-default main context][g-main-context-push-thread-default]
1377 * of the thread that @server was constructed in.
1379 * You are guaranteed that signal handlers for this signal runs
1380 * before incoming messages on @connection are processed. This means
1381 * that it's suitable to call g_dbus_connection_register_object() or
1382 * similar from the signal handler.
1384 * Returns: %TRUE to claim @connection, %FALSE to let other handlers
1391 * GDBusServer:active:
1393 * Whether the server is currently active.
1400 * GDBusServer:address:
1402 * The D-Bus address to listen on.
1409 * GDBusServer:authentication-observer:
1411 * A #GDBusAuthObserver object to assist in the authentication process or %NULL.
1418 * GDBusServer:client-address:
1420 * The D-Bus address that clients can use.
1427 * GDBusServer:flags:
1429 * Flags from the #GDBusServerFlags enumeration.
1438 * The GUID of the server.
1440 * See #GDBusConnection:guid for more details.
1448 * @new_connection: Signal class handler for the #GDBusServer::new-connection signal.
1450 * Class structure for #GDBusServer.
1457 * GDataInputStream:byte-order:
1459 * The :byte-order property determines the byte ordering that
1460 * is used when reading multi-byte entities (such as integers)
1466 * GDataInputStream:newline-type:
1468 * The :newline-type property determines what is considered
1469 * as a line ending when reading complete lines from the stream.
1474 * GDataOutputStream:byte-order:
1476 * Determines the byte ordering that is used when writing
1477 * multi-byte entities (such as integers) to the stream.
1484 * Information about an installed application from a desktop file.
1489 * GDesktopAppInfo:filename:
1491 * The origin filename of this #GDesktopAppInfo
1496 * GDesktopAppInfoLookup:
1498 * #GDesktopAppInfoLookup is an opaque data structure and can only be accessed
1499 * using the following functions.
1501 * Deprecated: 2.28: The #GDesktopAppInfoLookup interface is deprecated and
1508 * @drive: a #GDrive.
1510 * Emitted when the drive's state has changed.
1515 * GDrive::disconnected:
1516 * @drive: a #GDrive.
1518 * This signal is emitted when the #GDrive have been
1519 * disconnected. If the recipient is holding references to the
1520 * object they should release them so the object can be
1526 * GDrive::eject-button:
1527 * @drive: a #GDrive.
1529 * Emitted when the physical eject button (if any) of a drive has
1535 * GDrive::stop-button:
1536 * @drive: a #GDrive.
1538 * Emitted when the physical stop button (if any) of a drive has
1546 * GDtlsClientConnection:
1548 * Abstract base class for the backend-specific client connection
1556 * GDtlsClientConnection:accepted-cas: (type GLib.List) (element-type GLib.ByteArray)
1558 * A list of the distinguished names of the Certificate Authorities
1559 * that the server will accept client certificates signed by. If the
1560 * server requests a client certificate during the handshake, then
1561 * this property will be set after the handshake completes.
1563 * Each item in the list is a #GByteArray which contains the complete
1564 * subject DN of the certificate authority.
1571 * GDtlsClientConnection:server-identity:
1573 * A #GSocketConnectable describing the identity of the server that
1574 * is expected on the other end of the connection.
1576 * If the %G_TLS_CERTIFICATE_BAD_IDENTITY flag is set in
1577 * #GDtlsClientConnection:validation-flags, this object will be used
1578 * to determine the expected identify of the remote end of the
1579 * connection; if #GDtlsClientConnection:server-identity is not set,
1580 * or does not match the identity presented by the server, then the
1581 * %G_TLS_CERTIFICATE_BAD_IDENTITY validation will fail.
1583 * In addition to its use in verifying the server certificate,
1584 * this is also used to give a hint to the server about what
1585 * certificate we expect, which is useful for servers that serve
1593 * GDtlsClientConnection:validation-flags:
1595 * What steps to perform when validating a certificate received from
1596 * a server. Server certificates that fail to validate in any of the
1597 * ways indicated here will be rejected unless the application
1598 * overrides the default via #GDtlsConnection::accept-certificate.
1607 * Abstract base class for the backend-specific #GDtlsClientConnection
1608 * and #GDtlsServerConnection types.
1615 * GDtlsConnection::accept-certificate:
1616 * @conn: a #GDtlsConnection
1617 * @peer_cert: the peer's #GTlsCertificate
1618 * @errors: the problems with @peer_cert.
1620 * Emitted during the TLS handshake after the peer certificate has
1621 * been received. You can examine @peer_cert's certification path by
1622 * calling g_tls_certificate_get_issuer() on it.
1624 * For a client-side connection, @peer_cert is the server's
1625 * certificate, and the signal will only be emitted if the
1626 * certificate was not acceptable according to @conn's
1627 * #GDtlsClientConnection:validation_flags. If you would like the
1628 * certificate to be accepted despite @errors, return %TRUE from the
1629 * signal handler. Otherwise, if no handler accepts the certificate,
1630 * the handshake will fail with %G_TLS_ERROR_BAD_CERTIFICATE.
1632 * For a server-side connection, @peer_cert is the certificate
1633 * presented by the client, if this was requested via the server's
1634 * #GDtlsServerConnection:authentication_mode. On the server side,
1635 * the signal is always emitted when the client presents a
1636 * certificate, and the certificate will only be accepted if a
1637 * handler returns %TRUE.
1639 * Note that if this signal is emitted as part of asynchronous I/O
1640 * in the main thread, then you should not attempt to interact with
1641 * the user before returning from the signal handler. If you want to
1642 * let the user decide whether or not to accept the certificate, you
1643 * would have to return %FALSE from the signal handler on the first
1644 * attempt, and then after the connection attempt returns a
1645 * %G_TLS_ERROR_BAD_CERTIFICATE, you can interact with the user, and
1646 * if the user decides to accept the certificate, remember that fact,
1647 * create a new connection, and return %TRUE from the signal handler
1650 * If you are doing I/O in another thread, you do not
1651 * need to worry about this, and can simply block in the signal
1652 * handler until the UI thread returns an answer.
1654 * Returns: %TRUE to accept @peer_cert (which will also
1655 * immediately end the signal emission). %FALSE to allow the signal
1656 * emission to continue, which will cause the handshake to fail if
1657 * no one else overrides it.
1663 * GDtlsConnection:advertised-protocols: (nullable)
1665 * The list of application-layer protocols that the connection
1666 * advertises that it is willing to speak. See
1667 * g_dtls_connection_set_advertised_protocols().
1674 * GDtlsConnection:base-socket:
1676 * The #GDatagramBased that the connection wraps. Note that this may be any
1677 * implementation of #GDatagramBased, not just a #GSocket.
1684 * GDtlsConnection:certificate:
1686 * The connection's certificate; see
1687 * g_dtls_connection_set_certificate().
1694 * GDtlsConnection:ciphersuite-name: (nullable)
1696 * The name of the DTLS ciphersuite in use. See g_dtls_connection_get_ciphersuite_name().
1703 * GDtlsConnection:database: (nullable)
1705 * The certificate database to use when verifying this TLS connection.
1706 * If no certificate database is set, then the default database will be
1707 * used. See g_tls_backend_get_default_database().
1714 * GDtlsConnection:interaction: (nullable)
1716 * A #GTlsInteraction object to be used when the connection or certificate
1717 * database need to interact with the user. This will be used to prompt the
1718 * user for passwords where necessary.
1725 * GDtlsConnection:negotiated-protocol:
1727 * The application-layer protocol negotiated during the TLS
1728 * handshake. See g_dtls_connection_get_negotiated_protocol().
1735 * GDtlsConnection:peer-certificate: (nullable)
1737 * The connection's peer's certificate, after the TLS handshake has
1738 * completed or failed. Note in particular that this is not yet set
1739 * during the emission of #GDtlsConnection::accept-certificate.
1741 * (You can watch for a #GObject::notify signal on this property to
1742 * detect when a handshake has occurred.)
1749 * GDtlsConnection:peer-certificate-errors:
1751 * The errors noticed while verifying
1752 * #GDtlsConnection:peer-certificate. Normally this should be 0, but
1753 * it may not be if #GDtlsClientConnection:validation-flags is not
1754 * %G_TLS_CERTIFICATE_VALIDATE_ALL, or if
1755 * #GDtlsConnection::accept-certificate overrode the default
1763 * GDtlsConnection:protocol-version:
1765 * The DTLS protocol version in use. See g_dtls_connection_get_protocol_version().
1772 * GDtlsConnection:rehandshake-mode:
1774 * The rehandshaking mode. See
1775 * g_dtls_connection_set_rehandshake_mode().
1778 * Deprecated: 2.60: The rehandshake mode is ignored.
1783 * GDtlsConnection:require-close-notify:
1785 * Whether or not proper TLS close notification is required.
1786 * See g_dtls_connection_set_require_close_notify().
1793 * GDtlsServerConnection:authentication-mode:
1795 * The #GTlsAuthenticationMode for the server. This can be changed
1796 * before calling g_dtls_connection_handshake() if you want to
1797 * rehandshake with a different mode from the initial handshake.
1806 * The file containing the icon.
1811 * GFileMonitor::changed:
1812 * @monitor: a #GFileMonitor.
1814 * @other_file: (nullable): a #GFile or #NULL.
1815 * @event_type: a #GFileMonitorEvent.
1817 * Emitted when @file has been changed.
1819 * If using %G_FILE_MONITOR_WATCH_MOVES on a directory monitor, and
1820 * the information is available (and if supported by the backend),
1821 * @event_type may be %G_FILE_MONITOR_EVENT_RENAMED,
1822 * %G_FILE_MONITOR_EVENT_MOVED_IN or %G_FILE_MONITOR_EVENT_MOVED_OUT.
1824 * In all cases @file will be a child of the monitored directory. For
1825 * renames, @file will be the old name and @other_file is the new
1826 * name. For "moved in" events, @file is the name of the file that
1827 * appeared and @other_file is the old name that it was moved from (in
1828 * another directory). For "moved out" events, @file is the name of
1829 * the file that used to be in this directory and @other_file is the
1830 * name of the file at its new location.
1832 * It makes sense to treat %G_FILE_MONITOR_EVENT_MOVED_IN as
1833 * equivalent to %G_FILE_MONITOR_EVENT_CREATED and
1834 * %G_FILE_MONITOR_EVENT_MOVED_OUT as equivalent to
1835 * %G_FILE_MONITOR_EVENT_DELETED, with extra information.
1836 * %G_FILE_MONITOR_EVENT_RENAMED is equivalent to a delete/create
1837 * pair. This is exactly how the events will be reported in the case
1838 * that the %G_FILE_MONITOR_WATCH_MOVES flag is not in use.
1840 * If using the deprecated flag %G_FILE_MONITOR_SEND_MOVED flag and @event_type is
1841 * #G_FILE_MONITOR_EVENT_MOVED, @file will be set to a #GFile containing the
1842 * old path, and @other_file will be set to a #GFile containing the new path.
1844 * In all the other cases, @other_file will be set to #NULL.
1849 * GFilenameCompleter::got-completion-data:
1851 * Emitted when the file name completion information comes available.
1858 * #GIOExtension is an opaque data structure and can only be accessed
1859 * using the following functions.
1864 * GIOExtensionPoint:
1866 * #GIOExtensionPoint is an opaque data structure and can only be accessed
1867 * using the following functions.
1874 * Represents a scope for loading IO modules. A scope can be used for blocking
1875 * duplicate modules, or blocking a module you don't want to load.
1877 * The scope can be used with g_io_modules_load_all_in_directory_with_scope()
1878 * or g_io_modules_scan_all_in_directory_with_scope().
1887 * An IPv4 or IPv6 internet address.
1892 * GInetAddress:is-any:
1894 * Whether this is the "any" address for its family.
1895 * See g_inet_address_get_is_any().
1902 * GInetAddress:is-link-local:
1904 * Whether this is a link-local address.
1905 * See g_inet_address_get_is_link_local().
1912 * GInetAddress:is-loopback:
1914 * Whether this is the loopback address for its family.
1915 * See g_inet_address_get_is_loopback().
1922 * GInetAddress:is-mc-global:
1924 * Whether this is a global multicast address.
1925 * See g_inet_address_get_is_mc_global().
1932 * GInetAddress:is-mc-link-local:
1934 * Whether this is a link-local multicast address.
1935 * See g_inet_address_get_is_mc_link_local().
1942 * GInetAddress:is-mc-node-local:
1944 * Whether this is a node-local multicast address.
1945 * See g_inet_address_get_is_mc_node_local().
1952 * GInetAddress:is-mc-org-local:
1954 * Whether this is an organization-local multicast address.
1955 * See g_inet_address_get_is_mc_org_local().
1962 * GInetAddress:is-mc-site-local:
1964 * Whether this is a site-local multicast address.
1965 * See g_inet_address_get_is_mc_site_local().
1972 * GInetAddress:is-multicast:
1974 * Whether this is a multicast address.
1975 * See g_inet_address_get_is_multicast().
1982 * GInetAddress:is-site-local:
1984 * Whether this is a site-local address.
1985 * See g_inet_address_get_is_loopback().
1994 * A combination of an IPv4 or IPv6 base address and a length,
1995 * representing a range of IP addresses.
2002 * GInetSocketAddress:
2004 * An IPv4 or IPv6 socket address, corresponding to a struct
2005 * sockaddr_in or struct sockaddr_in6.
2010 * GInetSocketAddress:flowinfo:
2012 * The `sin6_flowinfo` field, for IPv6 addresses.
2019 * GInetSocketAddress:scope_id:
2021 * The `sin6_scope_id` field, for IPv6 addresses.
2028 * GKeyfileSettingsBackend:default-dir:
2030 * The directory where the system defaults and locks are located.
2032 * Defaults to `/etc/glib-2.0/settings`.
2037 * GKeyfileSettingsBackend:filename:
2039 * The location where the settings are stored on disk.
2041 * Defaults to `$XDG_CONFIG_HOME/glib-2.0/settings/keyfile`.
2046 * GKeyfileSettingsBackend:root-group:
2048 * If @root_group is non-%NULL then it specifies the name of the keyfile
2049 * group used for keys that are written directly below the root path.
2056 * GKeyfileSettingsBackend:root-path:
2058 * All settings read to or written from the backend must fall under the
2059 * path given in @root_path (which must start and end with a slash and
2060 * not contain two consecutive slashes). @root_path may be "/".
2069 * #GListModel is an opaque data structure and can only be accessed
2070 * using the following functions.
2075 * GListModel::items-changed:
2076 * @list: the #GListModel that changed
2077 * @position: the position at which @list changed
2078 * @removed: the number of items removed
2079 * @added: the number of items added
2081 * This signal is emitted whenever items were added to or removed
2082 * from @list. At @position, @removed items were removed and @added
2083 * items were added in their place.
2085 * Note: If @removed != @added, the positions of all later items
2086 * in the model change.
2093 * GListModelInterface:
2094 * @g_iface: parent #GTypeInterface
2095 * @get_item_type: the virtual function pointer for g_list_model_get_item_type()
2096 * @get_n_items: the virtual function pointer for g_list_model_get_n_items()
2097 * @get_item: the virtual function pointer for g_list_model_get_item()
2099 * The virtual function table for #GListModel.
2106 * GListModelInterface::get_item:
2107 * @list: a #GListModel
2108 * @position: the position of the item to fetch
2110 * Get the item at @position. If @position is greater than the number of
2111 * items in @list, %NULL is returned.
2113 * %NULL is never returned for an index that is smaller than the length
2114 * of the list. See g_list_model_get_n_items().
2116 * Returns: (type GObject) (transfer full) (nullable): the object at @position.
2124 * #GListStore is an opaque data structure and can only be accessed
2125 * using the following functions.
2130 * GListStore:item-type:
2132 * The type of items contained in this list store. Items must be
2133 * subclasses of #GObject.
2142 * #GMemoryMonitor monitors system memory and indicates when
2143 * the system is low on memory.
2150 * GMemoryMonitor::low-memory-warning:
2151 * @monitor: a #GMemoryMonitor
2152 * @level: the #GMemoryMonitorWarningLevel warning level
2154 * Emitted when the system is running low on free memory. The signal
2155 * handler should then take the appropriate action depending on the
2156 * warning level. See the #GMemoryMonitorWarningLevel documentation for
2164 * GMemoryMonitorInterface:
2165 * @g_iface: The parent interface.
2166 * @low_memory_warning: the virtual function pointer for the
2167 * #GMemoryMonitor::low-memory-warning signal.
2169 * The virtual function table for #GMemoryMonitor.
2176 * GMemoryOutputStream:data:
2178 * Pointer to buffer where data will be written.
2185 * GMemoryOutputStream:data-size:
2187 * Size of data written to the buffer.
2194 * GMemoryOutputStream:destroy-function: (skip)
2196 * Function called with the buffer as argument when the stream is destroyed.
2203 * GMemoryOutputStream:realloc-function: (skip)
2205 * Function with realloc semantics called to enlarge the buffer.
2212 * GMemoryOutputStream:size:
2214 * Current size of the data buffer.
2223 * #GMenu is an opaque structure type. You must access it using the
2231 * GMenuAttributeIter:
2233 * #GMenuAttributeIter is an opaque structure type. You must access it
2234 * using the functions below.
2243 * #GMenuItem is an opaque structure type. You must access it using the
2253 * #GMenuLinkIter is an opaque structure type. You must access it using
2254 * the functions below.
2263 * #GMenuModel is an opaque structure type. You must access it using the
2271 * GMenuModel::items-changed:
2272 * @model: the #GMenuModel that is changing
2273 * @position: the position of the change
2274 * @removed: the number of items removed
2275 * @added: the number of items added
2277 * Emitted when a change has occurred to the menu.
2279 * The only changes that can occur to a menu is that items are removed
2280 * or added. Items may not change (except by being removed and added
2281 * back in the same location). This signal is capable of describing
2282 * both of those changes (at the same time).
2284 * The signal means that starting at the index @position, @removed
2285 * items were removed and @added items were added in their place. If
2286 * @removed is zero then only items were added. If @added is zero
2287 * then only items were removed.
2289 * As an example, if the menu contains items a, b, c, d (in that
2290 * order) and the signal (2, 1, 3) occurs then the new composition of
2291 * the menu will be a, b, _, _, _, d (with each _ representing some
2294 * Signal handlers may query the model (particularly the added items)
2295 * and expect to see the results of the modification that is being
2296 * reported. The signal is emitted after the modification.
2302 * @mount: the object on which the signal is emitted
2304 * Emitted when the mount has been changed.
2309 * GMount::pre-unmount:
2310 * @mount: the object on which the signal is emitted
2312 * This signal may be emitted when the #GMount is about to be
2315 * This signal depends on the backend and is only emitted if
2316 * GIO was used to unmount.
2323 * GMount::unmounted:
2324 * @mount: the object on which the signal is emitted
2326 * This signal is emitted when the #GMount have been
2327 * unmounted. If the recipient is holding references to the
2328 * object they should release them so the object can be
2334 * GMountOperation::aborted:
2336 * Emitted by the backend when e.g. a device becomes unavailable
2337 * while a mount operation is in progress.
2339 * Implementations of GMountOperation should handle this signal
2340 * by dismissing open password dialogs.
2347 * GMountOperation::ask-password:
2348 * @op: a #GMountOperation requesting a password.
2349 * @message: string containing a message to display to the user.
2350 * @default_user: string containing the default user name.
2351 * @default_domain: string containing the default domain.
2352 * @flags: a set of #GAskPasswordFlags.
2354 * Emitted when a mount operation asks the user for a password.
2356 * If the message contains a line break, the first line should be
2357 * presented as a heading. For example, it may be used as the
2358 * primary text in a #GtkMessageDialog.
2363 * GMountOperation::ask-question:
2364 * @op: a #GMountOperation asking a question.
2365 * @message: string containing a message to display to the user.
2366 * @choices: an array of strings for each possible choice.
2368 * Emitted when asking the user a question and gives a list of
2369 * choices for the user to choose from.
2371 * If the message contains a line break, the first line should be
2372 * presented as a heading. For example, it may be used as the
2373 * primary text in a #GtkMessageDialog.
2378 * GMountOperation::reply:
2379 * @op: a #GMountOperation.
2380 * @result: a #GMountOperationResult indicating how the request was handled
2382 * Emitted when the user has replied to the mount operation.
2387 * GMountOperation::show-processes:
2388 * @op: a #GMountOperation.
2389 * @message: string containing a message to display to the user.
2390 * @processes: (element-type GPid): an array of #GPid for processes
2391 * blocking the operation.
2392 * @choices: an array of strings for each possible choice.
2394 * Emitted when one or more processes are blocking an operation
2395 * e.g. unmounting/ejecting a #GMount or stopping a #GDrive.
2397 * Note that this signal may be emitted several times to update the
2398 * list of blocking processes as processes close files. The
2399 * application should only respond with g_mount_operation_reply() to
2400 * the latest signal (setting #GMountOperation:choice to the choice
2403 * If the message contains a line break, the first line should be
2404 * presented as a heading. For example, it may be used as the
2405 * primary text in a #GtkMessageDialog.
2412 * GMountOperation::show-unmount-progress:
2413 * @op: a #GMountOperation:
2414 * @message: string containing a message to display to the user
2415 * @time_left: the estimated time left before the operation completes,
2416 * in microseconds, or -1
2417 * @bytes_left: the amount of bytes to be written before the operation
2418 * completes (or -1 if such amount is not known), or zero if the operation
2421 * Emitted when an unmount operation has been busy for more than some time
2422 * (typically 1.5 seconds).
2424 * When unmounting or ejecting a volume, the kernel might need to flush
2425 * pending data in its buffers to the volume stable storage, and this operation
2426 * can take a considerable amount of time. This signal may be emitted several
2427 * times as long as the unmount operation is outstanding, and then one
2428 * last time when the operation is completed, with @bytes_left set to zero.
2430 * Implementations of GMountOperation should handle this signal by
2431 * showing an UI notification, and then dismiss it, or show another notification
2432 * of completion, when @bytes_left reaches zero.
2434 * If the message contains a line break, the first line should be
2435 * presented as a heading. For example, it may be used as the
2436 * primary text in a #GtkMessageDialog.
2443 * GMountOperation:anonymous:
2445 * Whether to use an anonymous user when authenticating.
2450 * GMountOperation:choice:
2452 * The index of the user's choice when a question is asked during the
2453 * mount operation. See the #GMountOperation::ask-question signal.
2458 * GMountOperation:domain:
2460 * The domain to use for the mount operation.
2465 * GMountOperation:is-tcrypt-hidden-volume:
2467 * Whether the device to be unlocked is a TCRYPT hidden volume.
2468 * See [the VeraCrypt documentation](https://www.veracrypt.fr/en/Hidden%20Volume.html).
2475 * GMountOperation:is-tcrypt-system-volume:
2477 * Whether the device to be unlocked is a TCRYPT system volume.
2478 * In this context, a system volume is a volume with a bootloader
2479 * and operating system installed. This is only supported for Windows
2480 * operating systems. For further documentation, see
2481 * [the VeraCrypt documentation](https://www.veracrypt.fr/en/System%20Encryption.html).
2488 * GMountOperation:password:
2490 * The password that is used for authentication when carrying out
2491 * the mount operation.
2496 * GMountOperation:password-save:
2498 * Determines if and how the password information should be saved.
2503 * GMountOperation:pim:
2505 * The VeraCrypt PIM value, when unlocking a VeraCrypt volume. See
2506 * [the VeraCrypt documentation](https://www.veracrypt.fr/en/Personal%20Iterations%20Multiplier%20(PIM).html).
2513 * GMountOperation:username:
2515 * The user name that is used for authentication when carrying out
2516 * the mount operation.
2521 * GNativeSocketAddress:
2523 * A socket address, corresponding to a general struct
2524 * sockadd address of a type not otherwise handled by glib.
2531 * A #GSocketConnectable for resolving a hostname and connecting to
2539 * #GNetworkMonitor monitors the status of network connections and
2540 * indicates when a possibly-user-visible change has occurred.
2547 * GNetworkMonitor::network-changed:
2548 * @monitor: a #GNetworkMonitor
2549 * @network_available: the current value of #GNetworkMonitor:network-available
2551 * Emitted when the network configuration changes.
2558 * GNetworkMonitor:connectivity:
2560 * More detailed information about the host's network connectivity.
2561 * See g_network_monitor_get_connectivity() and
2562 * #GNetworkConnectivity for more details.
2569 * GNetworkMonitor:network-available:
2571 * Whether the network is considered available. That is, whether the
2572 * system has a default route for at least one of IPv4 or IPv6.
2574 * Real-world networks are of course much more complicated than
2575 * this; the machine may be connected to a wifi hotspot that
2576 * requires payment before allowing traffic through, or may be
2577 * connected to a functioning router that has lost its own upstream
2578 * connectivity. Some hosts might only be accessible when a VPN is
2579 * active. Other hosts might only be accessible when the VPN is
2580 * not active. Thus, it is best to use g_network_monitor_can_reach()
2581 * or g_network_monitor_can_reach_async() to test for reachability
2582 * on a host-by-host basis. (On the other hand, when the property is
2583 * %FALSE, the application can reasonably expect that no remote
2584 * hosts at all are reachable, and should indicate this to the user
2587 * See also #GNetworkMonitor::network-changed.
2594 * GNetworkMonitor:network-metered:
2596 * Whether the network is considered metered. That is, whether the
2597 * system has traffic flowing through the default connection that is
2598 * subject to limitations set by service providers. For example, traffic
2599 * might be billed by the amount of data transmitted, or there might be a
2600 * quota on the amount of traffic per month. This is typical with tethered
2601 * connections (3G and 4G) and in such situations, bandwidth intensive
2602 * applications may wish to avoid network activity where possible if it will
2603 * cost the user money or use up their limited quota.
2605 * If more information is required about specific devices then the
2606 * system network management API should be used instead (for example,
2607 * NetworkManager or ConnMan).
2609 * If this information is not available then no networks will be
2610 * marked as metered.
2612 * See also #GNetworkMonitor:network-available.
2619 * GNetworkMonitorInterface:
2620 * @g_iface: The parent interface.
2621 * @network_changed: the virtual function pointer for the
2622 * GNetworkMonitor::network-changed signal.
2623 * @can_reach: the virtual function pointer for g_network_monitor_can_reach()
2624 * @can_reach_async: the virtual function pointer for
2625 * g_network_monitor_can_reach_async()
2626 * @can_reach_finish: the virtual function pointer for
2627 * g_network_monitor_can_reach_finish()
2629 * The virtual function table for #GNetworkMonitor.
2638 * A #GSocketConnectable for resolving a SRV record and connecting to
2646 * This structure type is private and should only be accessed using the
2656 * #GPermission is an opaque data structure and can only be accessed
2657 * using the following functions.
2662 * GPermission:allowed:
2664 * %TRUE if the caller currently has permission to perform the action that
2665 * @permission represents the permission to perform.
2670 * GPermission:can-acquire:
2672 * %TRUE if it is generally possible to acquire the permission by calling
2673 * g_permission_acquire().
2678 * GPermission:can-release:
2680 * %TRUE if it is generally possible to release the permission by calling
2681 * g_permission_release().
2686 * GPowerProfileMonitor:
2688 * #GPowerProfileMonitor monitors system power profile and notifies on
2696 * GPowerProfileMonitor:power-saver-enabled:
2698 * Whether “Power Saver” mode is enabled on the system.
2705 * GPowerProfileMonitorInterface:
2706 * @g_iface: The parent interface.
2708 * The virtual function table for #GPowerProfileMonitor.
2717 * This type is opaque.
2724 * GPropertyAction:enabled:
2726 * If @action is currently enabled.
2728 * If the action is disabled then calls to g_action_activate() and
2729 * g_action_change_state() have no effect.
2736 * GPropertyAction:invert-boolean:
2738 * If %TRUE, the state of the action will be the negation of the
2739 * property value, provided the property is boolean.
2746 * GPropertyAction:name:
2748 * The name of the action. This is mostly meaningful for identifying
2749 * the action once it has been added to a #GActionMap.
2756 * GPropertyAction:object:
2758 * The object to wrap a property on.
2760 * The object must be a non-%NULL #GObject with properties.
2767 * GPropertyAction:parameter-type:
2769 * The type of the parameter that must be given when activating the
2777 * GPropertyAction:property-name:
2779 * The name of the property to wrap on the object.
2781 * The property must exist on the passed-in object and it must be
2782 * readable and writable (and not construct-only).
2789 * GPropertyAction:state:
2791 * The state of the action, or %NULL if the action is stateless.
2798 * GPropertyAction:state-type:
2800 * The #GVariantType of the state that the action has, or %NULL if the
2801 * action is stateless.
2810 * A #GInetSocketAddress representing a connection via a proxy server
2817 * GProxyAddress:destination-protocol:
2819 * The protocol being spoke to the destination host, or %NULL if
2820 * the #GProxyAddress doesn't know.
2827 * GProxyAddress:uri:
2829 * The URI string that the proxy was constructed from (or %NULL
2830 * if the creator didn't specify this).
2837 * GProxyAddressClass:
2839 * Class structure for #GProxyAddress.
2846 * GProxyAddressEnumerator:default-port:
2848 * The default port to use if #GProxyAddressEnumerator:uri does not
2856 * GProxyAddressEnumerator:proxy-resolver:
2858 * The proxy resolver to use.
2865 * GProxyResolverInterface:
2866 * @g_iface: The parent interface.
2867 * @is_supported: the virtual function pointer for g_proxy_resolver_is_supported()
2868 * @lookup: the virtual function pointer for g_proxy_resolver_lookup()
2869 * @lookup_async: the virtual function pointer for
2870 * g_proxy_resolver_lookup_async()
2871 * @lookup_finish: the virtual function pointer for
2872 * g_proxy_resolver_lookup_finish()
2874 * The virtual function table for #GProxyResolver.
2879 * GRemoteActionGroup:
2881 * #GRemoteActionGroup is an opaque data structure and can only be accessed
2882 * using the following functions.
2887 * GRemoteActionGroupInterface:
2888 * @activate_action_full: the virtual function pointer for g_remote_action_group_activate_action_full()
2889 * @change_action_state_full: the virtual function pointer for g_remote_action_group_change_action_state_full()
2891 * The virtual function table for #GRemoteActionGroup.
2900 * The object that handles DNS resolution. Use g_resolver_get_default()
2901 * to get the default resolver.
2903 * This is an abstract type; subclasses of it implement different resolvers for
2904 * different platforms and situations.
2909 * GResolver::reload:
2910 * @resolver: a #GResolver
2912 * Emitted when the resolver notices that the system resolver
2913 * configuration has changed.
2920 * #GSettings is an opaque data structure and can only be accessed
2921 * using the following functions.
2926 * GSettings::change-event:
2927 * @settings: the object on which the signal was emitted
2928 * @keys: (array length=n_keys) (element-type GQuark) (nullable):
2929 * an array of #GQuarks for the changed keys, or %NULL
2930 * @n_keys: the length of the @keys array, or 0
2932 * The "change-event" signal is emitted once per change event that
2933 * affects this settings object. You should connect to this signal
2934 * only if you are interested in viewing groups of changes before they
2935 * are split out into multiple emissions of the "changed" signal.
2936 * For most use cases it is more appropriate to use the "changed" signal.
2938 * In the event that the change event applies to one or more specified
2939 * keys, @keys will be an array of #GQuark of length @n_keys. In the
2940 * event that the change event applies to the #GSettings object as a
2941 * whole (ie: potentially every key has been changed) then @keys will
2942 * be %NULL and @n_keys will be 0.
2944 * The default handler for this signal invokes the "changed" signal
2945 * for each affected key. If any other connected handler returns
2946 * %TRUE then this default functionality will be suppressed.
2948 * Returns: %TRUE to stop other handlers from being invoked for the
2949 * event. FALSE to propagate the event further.
2954 * GSettings::changed:
2955 * @settings: the object on which the signal was emitted
2956 * @key: the name of the key that changed
2958 * The "changed" signal is emitted when a key has potentially changed.
2959 * You should call one of the g_settings_get() calls to check the new
2962 * This signal supports detailed connections. You can connect to the
2963 * detailed signal "changed::x" in order to only receive callbacks
2964 * when key "x" changes.
2966 * Note that @settings only emits this signal if you have read @key at
2967 * least once while a signal handler was already connected for @key.
2972 * GSettings::writable-change-event:
2973 * @settings: the object on which the signal was emitted
2974 * @key: the quark of the key, or 0
2976 * The "writable-change-event" signal is emitted once per writability
2977 * change event that affects this settings object. You should connect
2978 * to this signal if you are interested in viewing groups of changes
2979 * before they are split out into multiple emissions of the
2980 * "writable-changed" signal. For most use cases it is more
2981 * appropriate to use the "writable-changed" signal.
2983 * In the event that the writability change applies only to a single
2984 * key, @key will be set to the #GQuark for that key. In the event
2985 * that the writability change affects the entire settings object,
2988 * The default handler for this signal invokes the "writable-changed"
2989 * and "changed" signals for each affected key. This is done because
2990 * changes in writability might also imply changes in value (if for
2991 * example, a new mandatory setting is introduced). If any other
2992 * connected handler returns %TRUE then this default functionality
2993 * will be suppressed.
2995 * Returns: %TRUE to stop other handlers from being invoked for the
2996 * event. FALSE to propagate the event further.
3001 * GSettings::writable-changed:
3002 * @settings: the object on which the signal was emitted
3005 * The "writable-changed" signal is emitted when the writability of a
3006 * key has potentially changed. You should call
3007 * g_settings_is_writable() in order to determine the new status.
3009 * This signal supports detailed connections. You can connect to the
3010 * detailed signal "writable-changed::x" in order to only receive
3011 * callbacks when the writability of "x" changes.
3016 * GSettings:backend:
3018 * The name of the context that the settings are stored in.
3023 * GSettings:delay-apply:
3025 * Whether the #GSettings object is in 'delay-apply' mode. See
3026 * g_settings_delay() for details.
3033 * GSettings:has-unapplied:
3035 * If this property is %TRUE, the #GSettings object has outstanding
3036 * changes that will be applied when g_settings_apply() is called.
3043 * The path within the backend where the settings are stored.
3050 * The name of the schema that describes the types of keys
3051 * for this #GSettings object.
3053 * The type of this property is *not* #GSettingsSchema.
3054 * #GSettingsSchema has only existed since version 2.32 and
3055 * unfortunately this name was used in previous versions to refer to
3056 * the schema ID rather than the schema itself. Take care to use the
3057 * 'settings-schema' property if you wish to pass in a
3060 * Deprecated: 2.32: Use the 'schema-id' property instead. In a future
3061 * version, this property may instead refer to a #GSettingsSchema.
3066 * GSettings:schema-id:
3068 * The name of the schema that describes the types of keys
3069 * for this #GSettings object.
3074 * GSettings:settings-schema:
3076 * The #GSettingsSchema describing the types of keys for this
3077 * #GSettings object.
3079 * Ideally, this property would be called 'schema'. #GSettingsSchema
3080 * has only existed since version 2.32, however, and before then the
3081 * 'schema' property was used to refer to the ID of the schema rather
3082 * than the schema itself. Take care.
3089 * This is an opaque structure type. You may not access it directly.
3096 * GSettingsSchemaKey:
3098 * #GSettingsSchemaKey is an opaque data structure and can only be accessed
3099 * using the following functions.
3104 * GSettingsSchemaSource:
3106 * This is an opaque structure type. You may not access it directly.
3115 * #GSimpleAction is an opaque data structure and can only be accessed
3116 * using the following functions.
3121 * GSimpleAction::activate:
3122 * @simple: the #GSimpleAction
3123 * @parameter: (nullable): the parameter to the activation, or %NULL if it has
3126 * Indicates that the action was just activated.
3128 * @parameter will always be of the expected type, i.e. the parameter type
3129 * specified when the action was created. If an incorrect type is given when
3130 * activating the action, this signal is not emitted.
3132 * Since GLib 2.40, if no handler is connected to this signal then the
3133 * default behaviour for boolean-stated actions with a %NULL parameter
3134 * type is to toggle them via the #GSimpleAction::change-state signal.
3135 * For stateful actions where the state type is equal to the parameter
3136 * type, the default is to forward them directly to
3137 * #GSimpleAction::change-state. This should allow almost all users
3138 * of #GSimpleAction to connect only one handler or the other.
3145 * GSimpleAction::change-state:
3146 * @simple: the #GSimpleAction
3147 * @value: (nullable): the requested value for the state
3149 * Indicates that the action just received a request to change its
3152 * @value will always be of the correct state type, i.e. the type of the
3153 * initial state passed to g_simple_action_new_stateful(). If an incorrect
3154 * type is given when requesting to change the state, this signal is not
3157 * If no handler is connected to this signal then the default
3158 * behaviour is to call g_simple_action_set_state() to set the state
3159 * to the requested value. If you connect a signal handler then no
3160 * default action is taken. If the state should change then you must
3161 * call g_simple_action_set_state() from the handler.
3163 * An example of a 'change-state' handler:
3164 * |[<!-- language="C" -->
3166 * change_volume_state (GSimpleAction *action,
3168 * gpointer user_data)
3172 * requested = g_variant_get_int32 (value);
3174 * // Volume only goes from 0 to 10
3175 * if (0 <= requested && requested <= 10)
3176 * g_simple_action_set_state (action, value);
3180 * The handler need not set the state to the requested value.
3181 * It could set it to any value at all, or take some other action.
3188 * GSimpleAction:enabled:
3190 * If @action is currently enabled.
3192 * If the action is disabled then calls to g_action_activate() and
3193 * g_action_change_state() have no effect.
3200 * GSimpleAction:name:
3202 * The name of the action. This is mostly meaningful for identifying
3203 * the action once it has been added to a #GSimpleActionGroup.
3210 * GSimpleAction:parameter-type:
3212 * The type of the parameter that must be given when activating the
3220 * GSimpleAction:state:
3222 * The state of the action, or %NULL if the action is stateless.
3229 * GSimpleAction:state-type:
3231 * The #GVariantType of the state that the action has, or %NULL if the
3232 * action is stateless.
3241 * A wrapper around a #GInputStream and a #GOutputStream.
3248 * GSimpleIOStream:input-stream:
3255 * GSimpleIOStream:output-stream:
3262 * GSimplePermission:
3264 * #GSimplePermission is an opaque data structure. There are no methods
3265 * except for those defined by #GPermission.
3270 * GSimpleProxyResolver:default-proxy:
3272 * The default proxy URI that will be used for any URI that doesn't
3273 * match #GSimpleProxyResolver:ignore-hosts, and doesn't match any
3274 * of the schemes set with g_simple_proxy_resolver_set_uri_proxy().
3276 * Note that as a special case, if this URI starts with
3277 * "socks://", #GSimpleProxyResolver will treat it as referring
3278 * to all three of the socks5, socks4a, and socks4 proxy types.
3283 * GSimpleProxyResolver:ignore-hosts:
3285 * A list of hostnames and IP addresses that the resolver should
3286 * allow direct connections to.
3288 * Entries can be in one of 4 formats:
3290 * - A hostname, such as "example.com", ".example.com", or
3291 * "*.example.com", any of which match "example.com" or
3292 * any subdomain of it.
3294 * - An IPv4 or IPv6 address, such as "192.168.1.1",
3295 * which matches only that address.
3297 * - A hostname or IP address followed by a port, such as
3298 * "example.com:80", which matches whatever the hostname or IP
3299 * address would match, but only for URLs with the (explicitly)
3300 * indicated port. In the case of an IPv6 address, the address
3301 * part must appear in brackets: "[::1]:443"
3303 * - An IP address range, given by a base address and prefix length,
3304 * such as "fe80::/10", which matches any address in that range.
3306 * Note that when dealing with Unicode hostnames, the matching is
3307 * done against the ASCII form of the name.
3309 * Also note that hostname exclusions apply only to connections made
3310 * to hosts identified by name, and IP address exclusions apply only
3311 * to connections made to hosts identified by address. That is, if
3312 * example.com has an address of 192.168.1.1, and the :ignore-hosts list
3313 * contains only "192.168.1.1", then a connection to "example.com"
3314 * (eg, via a #GNetworkAddress) will use the proxy, and a connection to
3315 * "192.168.1.1" (eg, via a #GInetSocketAddress) will not.
3317 * These rules match the "ignore-hosts"/"noproxy" rules most
3318 * commonly used by other applications.
3323 * GSocket:broadcast:
3325 * Whether the socket should allow sending to broadcast addresses.
3332 * GSocket:multicast-loopback:
3334 * Whether outgoing multicast packets loop back to the local host.
3341 * GSocket:multicast-ttl:
3343 * Time-to-live out outgoing multicast packets
3352 * The timeout in seconds on socket I/O
3361 * Time-to-live for outgoing unicast packets
3370 * A socket endpoint address, corresponding to struct sockaddr
3371 * or one of its subtypes.
3376 * GSocketClient::event:
3377 * @client: the #GSocketClient
3378 * @event: the event that is occurring
3379 * @connectable: the #GSocketConnectable that @event is occurring on
3380 * @connection: (nullable): the current representation of the connection
3382 * Emitted when @client's activity on @connectable changes state.
3383 * Among other things, this can be used to provide progress
3384 * information about a network connection in the UI. The meanings of
3385 * the different @event values are as follows:
3387 * - %G_SOCKET_CLIENT_RESOLVING: @client is about to look up @connectable
3388 * in DNS. @connection will be %NULL.
3390 * - %G_SOCKET_CLIENT_RESOLVED: @client has successfully resolved
3391 * @connectable in DNS. @connection will be %NULL.
3393 * - %G_SOCKET_CLIENT_CONNECTING: @client is about to make a connection
3394 * to a remote host; either a proxy server or the destination server
3395 * itself. @connection is the #GSocketConnection, which is not yet
3396 * connected. Since GLib 2.40, you can access the remote
3397 * address via g_socket_connection_get_remote_address().
3399 * - %G_SOCKET_CLIENT_CONNECTED: @client has successfully connected
3400 * to a remote host. @connection is the connected #GSocketConnection.
3402 * - %G_SOCKET_CLIENT_PROXY_NEGOTIATING: @client is about to negotiate
3403 * with a proxy to get it to connect to @connectable. @connection is
3404 * the #GSocketConnection to the proxy server.
3406 * - %G_SOCKET_CLIENT_PROXY_NEGOTIATED: @client has negotiated a
3407 * connection to @connectable through a proxy server. @connection is
3408 * the stream returned from g_proxy_connect(), which may or may not
3409 * be a #GSocketConnection.
3411 * - %G_SOCKET_CLIENT_TLS_HANDSHAKING: @client is about to begin a TLS
3412 * handshake. @connection is a #GTlsClientConnection.
3414 * - %G_SOCKET_CLIENT_TLS_HANDSHAKED: @client has successfully completed
3415 * the TLS handshake. @connection is a #GTlsClientConnection.
3417 * - %G_SOCKET_CLIENT_COMPLETE: @client has either successfully connected
3418 * to @connectable (in which case @connection is the #GSocketConnection
3419 * that it will be returning to the caller) or has failed (in which
3420 * case @connection is %NULL and the client is about to return an error).
3422 * Each event except %G_SOCKET_CLIENT_COMPLETE may be emitted
3423 * multiple times (or not at all) for a given connectable (in
3424 * particular, if @client ends up attempting to connect to more than
3425 * one address). However, if @client emits the #GSocketClient::event
3426 * signal at all for a given connectable, then it will always emit
3427 * it with %G_SOCKET_CLIENT_COMPLETE when it is done.
3429 * Note that there may be additional #GSocketClientEvent values in
3430 * the future; unrecognized @event values should be ignored.
3437 * GSocketClient:proxy-resolver:
3439 * The proxy resolver to use
3446 * GSocketListener::event:
3447 * @listener: the #GSocketListener
3448 * @event: the event that is occurring
3449 * @socket: the #GSocket the event is occurring on
3451 * Emitted when @listener's activity on @socket changes state.
3452 * Note that when @listener is used to listen on both IPv4 and
3453 * IPv6, a separate set of signals will be emitted for each, and
3454 * the order they happen in is undefined.
3461 * GSocketService::incoming:
3462 * @service: the #GSocketService
3463 * @connection: a new #GSocketConnection object
3464 * @source_object: (nullable): the source_object passed to
3465 * g_socket_listener_add_address()
3467 * The ::incoming signal is emitted when a new incoming connection
3468 * to @service needs to be handled. The handler must initiate the
3469 * handling of @connection, but may not block; in essence,
3470 * asynchronous operations must be used.
3472 * @connection will be unreffed once the signal handler returns,
3473 * so you need to ref it yourself if you are planning to use it.
3475 * Returns: %TRUE to stop other handlers from being called
3481 * GSocketService:active:
3483 * Whether the service is currently accepting connections.
3492 * A single target host/port that a network service is running on.
3499 * #GStaticResource is an opaque data structure and can only be accessed
3500 * using the following functions.
3507 * The opaque object representing a synchronous or asynchronous task
3515 * Whether the task has completed, meaning its callback (if set) has been
3516 * invoked. This can only happen after g_task_return_pointer(),
3517 * g_task_return_error() or one of the other return functions have been called
3520 * This property is guaranteed to change from %FALSE to %TRUE exactly once.
3522 * The #GObject::notify signal for this change is emitted in the same main
3523 * context as the task’s callback, immediately after that callback is invoked.
3532 * @source_object: (type GObject): @task's source object
3533 * @task_data: @task's task data
3534 * @cancellable: @task's #GCancellable, or %NULL
3536 * The prototype for a task function to be run in a thread via
3537 * g_task_run_in_thread() or g_task_run_in_thread_sync().
3539 * If the return-on-cancel flag is set on @task, and @cancellable gets
3540 * cancelled, then the #GTask will be completed immediately (as though
3541 * g_task_return_error_if_cancelled() had been called), without
3542 * waiting for the task function to complete. However, the task
3543 * function will continue running in its thread in the background. The
3544 * function therefore needs to be careful about how it uses
3545 * externally-visible state in this case. See
3546 * g_task_set_return_on_cancel() for more details.
3548 * Other than in that case, @task will be completed when the
3549 * #GTaskThreadFunc returns, not when it calls a
3550 * `g_task_return_` function.
3557 * GTcpWrapperConnection:
3559 * #GTcpWrapperConnection is an opaque data structure and can only be accessed
3560 * using the following functions.
3567 * The #GTestDBus structure contains only private data and
3568 * should only be accessed using the provided API.
3577 * #GTestDBusFlags specifying the behaviour of the D-Bus session.
3591 * GThemedIcon:names:
3593 * A %NULL-terminated array of icon names.
3598 * GThemedIcon:use-default-fallbacks:
3600 * Whether to use the default fallbacks found by shortening the icon name
3601 * at '-' characters. If the "names" array has more than one element,
3602 * ignores any past the first.
3604 * For example, if the icon name was "gnome-dev-cdrom-audio", the array
3606 * |[<!-- language="C" -->
3608 * "gnome-dev-cdrom-audio",
3609 * "gnome-dev-cdrom",
3619 * GThreadedSocketService::run:
3620 * @service: the #GThreadedSocketService.
3621 * @connection: a new #GSocketConnection object.
3622 * @source_object: (nullable): the source_object passed to g_socket_listener_add_address().
3624 * The ::run signal is emitted in a worker thread in response to an
3625 * incoming connection. This thread is dedicated to handling
3626 * @connection and may perform blocking IO. The signal handler need
3627 * not return until the connection is closed.
3629 * Returns: %TRUE to stop further signal handlers from being called
3636 * TLS (Transport Layer Security, aka SSL) and DTLS backend. This is an
3637 * internal type used to coordinate the different classes implemented
3647 * Abstract base class for TLS certificate types.
3654 * GTlsCertificate:certificate:
3656 * The DER (binary) encoded representation of the certificate.
3657 * This property and the #GTlsCertificate:certificate-pem property
3658 * represent the same data, just in different forms.
3665 * GTlsCertificate:certificate-pem:
3667 * The PEM (ASCII) encoded representation of the certificate.
3668 * This property and the #GTlsCertificate:certificate
3669 * property represent the same data, just in different forms.
3676 * GTlsCertificate:dns-names: (nullable) (element-type GBytes) (transfer container)
3678 * The DNS names from the certificate's Subject Alternative Names (SANs),
3679 * %NULL if unavailable.
3686 * GTlsCertificate:ip-addresses: (nullable) (element-type GInetAddress) (transfer container)
3688 * The IP addresses from the certificate's Subject Alternative Names (SANs),
3689 * %NULL if unavailable.
3696 * GTlsCertificate:issuer:
3698 * A #GTlsCertificate representing the entity that issued this
3699 * certificate. If %NULL, this means that the certificate is either
3700 * self-signed, or else the certificate of the issuer is not
3703 * Beware the issuer certificate may not be the same as the
3704 * certificate that would actually be used to construct a valid
3705 * certification path during certificate verification.
3706 * [RFC 4158](https://datatracker.ietf.org/doc/html/rfc4158) explains
3707 * why an issuer certificate cannot be naively assumed to be part of the
3708 * the certification path (though GLib's TLS backends may not follow the
3709 * path building strategies outlined in this RFC). Due to the complexity
3710 * of certification path building, GLib does not provide any way to know
3711 * which certification path will actually be used. Accordingly, this
3712 * property cannot be used to make security-related decisions. Only
3713 * GLib itself should make security decisions about TLS certificates.
3720 * GTlsCertificate:issuer-name: (nullable)
3722 * The issuer from the certificate,
3723 * %NULL if unavailable.
3730 * GTlsCertificate:not-valid-after: (nullable)
3732 * The time at which this cert is no longer valid,
3733 * %NULL if unavailable.
3740 * GTlsCertificate:not-valid-before: (nullable)
3742 * The time at which this cert is considered to be valid,
3743 * %NULL if unavailable.
3750 * GTlsCertificate:pkcs11-uri: (nullable)
3752 * A URI referencing the [PKCS \#11](https://docs.oasis-open.org/pkcs11/pkcs11-base/v3.0/os/pkcs11-base-v3.0-os.html)
3753 * objects containing an X.509 certificate and optionally a private key.
3755 * If %NULL, the certificate is either not backed by PKCS \#11 or the
3756 * #GTlsBackend does not support PKCS \#11.
3763 * GTlsCertificate:private-key: (nullable)
3765 * The DER (binary) encoded representation of the certificate's
3766 * private key, in either [PKCS \#1 format](https://datatracker.ietf.org/doc/html/rfc8017)
3767 * or unencrypted [PKCS \#8 format.](https://datatracker.ietf.org/doc/html/rfc5208)
3768 * PKCS \#8 format is supported since 2.32; earlier releases only
3769 * support PKCS \#1. You can use the `openssl rsa` tool to convert
3770 * PKCS \#8 keys to PKCS \#1.
3772 * This property (or the #GTlsCertificate:private-key-pem property)
3773 * can be set when constructing a key (for example, from a file).
3774 * Since GLib 2.70, it is now also readable; however, be aware that if
3775 * the private key is backed by a PKCS \#11 URI – for example, if it
3776 * is stored on a smartcard – then this property will be %NULL. If so,
3777 * the private key must be referenced via its PKCS \#11 URI,
3778 * #GTlsCertificate:private-key-pkcs11-uri. You must check both
3779 * properties to see if the certificate really has a private key.
3780 * When this property is read, the output format will be unencrypted
3788 * GTlsCertificate:private-key-pem: (nullable)
3790 * The PEM (ASCII) encoded representation of the certificate's
3791 * private key in either [PKCS \#1 format](https://datatracker.ietf.org/doc/html/rfc8017)
3792 * ("`BEGIN RSA PRIVATE KEY`") or unencrypted
3793 * [PKCS \#8 format](https://datatracker.ietf.org/doc/html/rfc5208)
3794 * ("`BEGIN PRIVATE KEY`"). PKCS \#8 format is supported since 2.32;
3795 * earlier releases only support PKCS \#1. You can use the `openssl rsa`
3796 * tool to convert PKCS \#8 keys to PKCS \#1.
3798 * This property (or the #GTlsCertificate:private-key property)
3799 * can be set when constructing a key (for example, from a file).
3800 * Since GLib 2.70, it is now also readable; however, be aware that if
3801 * the private key is backed by a PKCS \#11 URI - for example, if it
3802 * is stored on a smartcard - then this property will be %NULL. If so,
3803 * the private key must be referenced via its PKCS \#11 URI,
3804 * #GTlsCertificate:private-key-pkcs11-uri. You must check both
3805 * properties to see if the certificate really has a private key.
3806 * When this property is read, the output format will be unencrypted
3814 * GTlsCertificate:private-key-pkcs11-uri: (nullable)
3816 * A URI referencing a [PKCS \#11](https://docs.oasis-open.org/pkcs11/pkcs11-base/v3.0/os/pkcs11-base-v3.0-os.html)
3817 * object containing a private key.
3824 * GTlsCertificate:subject-name: (nullable)
3826 * The subject from the cert,
3827 * %NULL if unavailable.
3834 * GTlsClientConnection:
3836 * Abstract base class for the backend-specific client connection
3844 * GTlsClientConnection:accepted-cas: (type GLib.List) (element-type GLib.ByteArray)
3846 * A list of the distinguished names of the Certificate Authorities
3847 * that the server will accept client certificates signed by. If the
3848 * server requests a client certificate during the handshake, then
3849 * this property will be set after the handshake completes.
3851 * Each item in the list is a #GByteArray which contains the complete
3852 * subject DN of the certificate authority.
3859 * GTlsClientConnection:server-identity:
3861 * A #GSocketConnectable describing the identity of the server that
3862 * is expected on the other end of the connection.
3864 * If the %G_TLS_CERTIFICATE_BAD_IDENTITY flag is set in
3865 * #GTlsClientConnection:validation-flags, this object will be used
3866 * to determine the expected identify of the remote end of the
3867 * connection; if #GTlsClientConnection:server-identity is not set,
3868 * or does not match the identity presented by the server, then the
3869 * %G_TLS_CERTIFICATE_BAD_IDENTITY validation will fail.
3871 * In addition to its use in verifying the server certificate,
3872 * this is also used to give a hint to the server about what
3873 * certificate we expect, which is useful for servers that serve
3881 * GTlsClientConnection:use-ssl3:
3883 * SSL 3.0 is no longer supported. See
3884 * g_tls_client_connection_set_use_ssl3() for details.
3887 * Deprecated: 2.56: SSL 3.0 is insecure.
3892 * GTlsClientConnection:validation-flags:
3894 * What steps to perform when validating a certificate received from
3895 * a server. Server certificates that fail to validate in any of the
3896 * ways indicated here will be rejected unless the application
3897 * overrides the default via #GTlsConnection::accept-certificate.
3906 * Abstract base class for the backend-specific #GTlsClientConnection
3907 * and #GTlsServerConnection types.
3914 * GTlsConnection::accept-certificate:
3915 * @conn: a #GTlsConnection
3916 * @peer_cert: the peer's #GTlsCertificate
3917 * @errors: the problems with @peer_cert.
3919 * Emitted during the TLS handshake after the peer certificate has
3920 * been received. You can examine @peer_cert's certification path by
3921 * calling g_tls_certificate_get_issuer() on it.
3923 * For a client-side connection, @peer_cert is the server's
3924 * certificate, and the signal will only be emitted if the
3925 * certificate was not acceptable according to @conn's
3926 * #GTlsClientConnection:validation_flags. If you would like the
3927 * certificate to be accepted despite @errors, return %TRUE from the
3928 * signal handler. Otherwise, if no handler accepts the certificate,
3929 * the handshake will fail with %G_TLS_ERROR_BAD_CERTIFICATE.
3931 * For a server-side connection, @peer_cert is the certificate
3932 * presented by the client, if this was requested via the server's
3933 * #GTlsServerConnection:authentication_mode. On the server side,
3934 * the signal is always emitted when the client presents a
3935 * certificate, and the certificate will only be accepted if a
3936 * handler returns %TRUE.
3938 * Note that if this signal is emitted as part of asynchronous I/O
3939 * in the main thread, then you should not attempt to interact with
3940 * the user before returning from the signal handler. If you want to
3941 * let the user decide whether or not to accept the certificate, you
3942 * would have to return %FALSE from the signal handler on the first
3943 * attempt, and then after the connection attempt returns a
3944 * %G_TLS_ERROR_BAD_CERTIFICATE, you can interact with the user, and
3945 * if the user decides to accept the certificate, remember that fact,
3946 * create a new connection, and return %TRUE from the signal handler
3949 * If you are doing I/O in another thread, you do not
3950 * need to worry about this, and can simply block in the signal
3951 * handler until the UI thread returns an answer.
3953 * Returns: %TRUE to accept @peer_cert (which will also
3954 * immediately end the signal emission). %FALSE to allow the signal
3955 * emission to continue, which will cause the handshake to fail if
3956 * no one else overrides it.
3962 * GTlsConnection:advertised-protocols: (nullable)
3964 * The list of application-layer protocols that the connection
3965 * advertises that it is willing to speak. See
3966 * g_tls_connection_set_advertised_protocols().
3973 * GTlsConnection:base-io-stream:
3975 * The #GIOStream that the connection wraps. The connection holds a reference
3976 * to this stream, and may run operations on the stream from other threads
3977 * throughout its lifetime. Consequently, after the #GIOStream has been
3978 * constructed, application code may only run its own operations on this
3979 * stream when no #GIOStream operations are running.
3986 * GTlsConnection:certificate:
3988 * The connection's certificate; see
3989 * g_tls_connection_set_certificate().
3996 * GTlsConnection:ciphersuite-name: (nullable)
3998 * The name of the TLS ciphersuite in use. See g_tls_connection_get_ciphersuite_name().
4005 * GTlsConnection:database: (nullable)
4007 * The certificate database to use when verifying this TLS connection.
4008 * If no certificate database is set, then the default database will be
4009 * used. See g_tls_backend_get_default_database().
4016 * GTlsConnection:interaction: (nullable)
4018 * A #GTlsInteraction object to be used when the connection or certificate
4019 * database need to interact with the user. This will be used to prompt the
4020 * user for passwords where necessary.
4027 * GTlsConnection:negotiated-protocol:
4029 * The application-layer protocol negotiated during the TLS
4030 * handshake. See g_tls_connection_get_negotiated_protocol().
4037 * GTlsConnection:peer-certificate: (nullable)
4039 * The connection's peer's certificate, after the TLS handshake has
4040 * completed or failed. Note in particular that this is not yet set
4041 * during the emission of #GTlsConnection::accept-certificate.
4043 * (You can watch for a #GObject::notify signal on this property to
4044 * detect when a handshake has occurred.)
4051 * GTlsConnection:peer-certificate-errors:
4053 * The errors noticed while verifying
4054 * #GTlsConnection:peer-certificate. Normally this should be 0, but
4055 * it may not be if #GTlsClientConnection:validation-flags is not
4056 * %G_TLS_CERTIFICATE_VALIDATE_ALL, or if
4057 * #GTlsConnection::accept-certificate overrode the default
4065 * GTlsConnection:protocol-version:
4067 * The TLS protocol version in use. See g_tls_connection_get_protocol_version().
4074 * GTlsConnection:rehandshake-mode:
4076 * The rehandshaking mode. See
4077 * g_tls_connection_set_rehandshake_mode().
4080 * Deprecated: 2.60: The rehandshake mode is ignored.
4085 * GTlsConnection:require-close-notify:
4087 * Whether or not proper TLS close notification is required.
4088 * See g_tls_connection_set_require_close_notify().
4095 * GTlsConnection:use-system-certdb:
4097 * Whether or not the system certificate database will be used to
4098 * verify peer certificates. See
4099 * g_tls_connection_set_use_system_certdb().
4101 * Deprecated: 2.30: Use GTlsConnection:database instead
4108 * Abstract base class for the backend-specific database types.
4115 * GTlsDatabaseClass:
4116 * @verify_chain: Virtual method implementing
4117 * g_tls_database_verify_chain().
4118 * @verify_chain_async: Virtual method implementing
4119 * g_tls_database_verify_chain_async().
4120 * @verify_chain_finish: Virtual method implementing
4121 * g_tls_database_verify_chain_finish().
4122 * @create_certificate_handle: Virtual method implementing
4123 * g_tls_database_create_certificate_handle().
4124 * @lookup_certificate_for_handle: Virtual method implementing
4125 * g_tls_database_lookup_certificate_for_handle().
4126 * @lookup_certificate_for_handle_async: Virtual method implementing
4127 * g_tls_database_lookup_certificate_for_handle_async().
4128 * @lookup_certificate_for_handle_finish: Virtual method implementing
4129 * g_tls_database_lookup_certificate_for_handle_finish().
4130 * @lookup_certificate_issuer: Virtual method implementing
4131 * g_tls_database_lookup_certificate_issuer().
4132 * @lookup_certificate_issuer_async: Virtual method implementing
4133 * g_tls_database_lookup_certificate_issuer_async().
4134 * @lookup_certificate_issuer_finish: Virtual method implementing
4135 * g_tls_database_lookup_certificate_issuer_finish().
4136 * @lookup_certificates_issued_by: Virtual method implementing
4137 * g_tls_database_lookup_certificates_issued_by().
4138 * @lookup_certificates_issued_by_async: Virtual method implementing
4139 * g_tls_database_lookup_certificates_issued_by_async().
4140 * @lookup_certificates_issued_by_finish: Virtual method implementing
4141 * g_tls_database_lookup_certificates_issued_by_finish().
4143 * The class for #GTlsDatabase. Derived classes should implement the various
4144 * virtual methods. _async and _finish methods have a default
4145 * implementation that runs the corresponding sync method in a thread.
4154 * Implemented by a #GTlsDatabase which allows you to load certificates
4162 * GTlsFileDatabase:anchors:
4164 * The path to a file containing PEM encoded certificate authority
4165 * root anchors. The certificates in this file will be treated as
4166 * root authorities for the purpose of verifying other certificates
4167 * via the g_tls_database_verify_chain() operation.
4176 * An object representing interaction that the TLS connection and database
4177 * might have with the user.
4184 * GTlsInteractionClass:
4185 * @ask_password: ask for a password synchronously. If the implementation
4186 * returns %G_TLS_INTERACTION_HANDLED, then the password argument should
4187 * have been filled in by using g_tls_password_set_value() or a similar
4189 * @ask_password_async: ask for a password asynchronously.
4190 * @ask_password_finish: complete operation to ask for a password asynchronously.
4191 * If the implementation returns %G_TLS_INTERACTION_HANDLED, then the
4192 * password argument of the async method should have been filled in by using
4193 * g_tls_password_set_value() or a similar function.
4194 * @request_certificate: ask for a certificate synchronously. If the
4195 * implementation returns %G_TLS_INTERACTION_HANDLED, then the connection
4196 * argument should have been filled in by using
4197 * g_tls_connection_set_certificate().
4198 * @request_certificate_async: ask for a certificate asynchronously.
4199 * @request_certificate_finish: complete operation to ask for a certificate
4200 * asynchronously. If the implementation returns %G_TLS_INTERACTION_HANDLED,
4201 * then the connection argument of the async method should have been
4202 * filled in by using g_tls_connection_set_certificate().
4204 * The class for #GTlsInteraction. Derived classes implement the various
4205 * virtual interaction methods to handle TLS interactions.
4207 * Derived classes can choose to implement whichever interactions methods they'd
4208 * like to support by overriding those virtual methods in their class
4209 * initialization function. If a derived class implements an async method,
4210 * it must also implement the corresponding finish method.
4212 * The synchronous interaction methods should implement to display modal dialogs,
4213 * and the asynchronous methods to display modeless dialogs.
4215 * If the user cancels an interaction, then the result should be
4216 * %G_TLS_INTERACTION_FAILED and the error should be set with a domain of
4217 * %G_IO_ERROR and code of %G_IO_ERROR_CANCELLED.
4226 * An abstract interface representing a password used in TLS. Often used in
4227 * user interaction such as unlocking a key storage token.
4234 * GTlsServerConnection:authentication-mode:
4236 * The #GTlsAuthenticationMode for the server. This can be changed
4237 * before calling g_tls_connection_handshake() if you want to
4238 * rehandshake with a different mode from the initial handshake.
4247 * #GUnixConnection is an opaque data structure and can only be accessed
4248 * using the following functions.
4253 * GUnixCredentialsMessage:credentials:
4255 * The credentials stored in the message.
4264 * #GUnixFDList is an opaque data structure and can only be accessed
4265 * using the following functions.
4272 * #GUnixFDMessage is an opaque data structure and can only be accessed
4273 * using the following functions.
4278 * GUnixInputStream:close-fd:
4280 * Whether to close the file descriptor when the stream is closed.
4287 * GUnixInputStream:fd:
4289 * The file descriptor that the stream reads from.
4296 * GUnixMountMonitor::mountpoints-changed:
4297 * @monitor: the object on which the signal is emitted
4299 * Emitted when the unix mount points have changed.
4304 * GUnixMountMonitor::mounts-changed:
4305 * @monitor: the object on which the signal is emitted
4307 * Emitted when the unix mounts have changed.
4313 * @G_UNIX_MOUNT_TYPE_UNKNOWN: Unknown UNIX mount type.
4314 * @G_UNIX_MOUNT_TYPE_FLOPPY: Floppy disk UNIX mount type.
4315 * @G_UNIX_MOUNT_TYPE_CDROM: CDROM UNIX mount type.
4316 * @G_UNIX_MOUNT_TYPE_NFS: Network File System (NFS) UNIX mount type.
4317 * @G_UNIX_MOUNT_TYPE_ZIP: ZIP UNIX mount type.
4318 * @G_UNIX_MOUNT_TYPE_JAZ: JAZZ UNIX mount type.
4319 * @G_UNIX_MOUNT_TYPE_MEMSTICK: Memory Stick UNIX mount type.
4320 * @G_UNIX_MOUNT_TYPE_CF: Compact Flash UNIX mount type.
4321 * @G_UNIX_MOUNT_TYPE_SM: Smart Media UNIX mount type.
4322 * @G_UNIX_MOUNT_TYPE_SDMMC: SD/MMC UNIX mount type.
4323 * @G_UNIX_MOUNT_TYPE_IPOD: iPod UNIX mount type.
4324 * @G_UNIX_MOUNT_TYPE_CAMERA: Digital camera UNIX mount type.
4325 * @G_UNIX_MOUNT_TYPE_HD: Hard drive UNIX mount type.
4327 * Types of UNIX mounts.
4332 * GUnixOutputStream:close-fd:
4334 * Whether to close the file descriptor when the stream is closed.
4341 * GUnixOutputStream:fd:
4343 * The file descriptor that the stream writes to.
4350 * GUnixSocketAddress:
4352 * A UNIX-domain (local) socket address, corresponding to a
4353 * struct sockaddr_un.
4358 * GUnixSocketAddress:abstract:
4360 * Whether or not this is an abstract address
4362 * Deprecated: Use #GUnixSocketAddress:address-type, which
4363 * distinguishes between zero-padded and non-zero-padded
4364 * abstract addresses.
4371 * Emitted when the volume has been changed.
4378 * This signal is emitted when the #GVolume have been removed. If
4379 * the recipient is holding references to the object they should
4380 * release them so the object can be finalized.
4385 * GVolumeMonitor::drive-changed:
4386 * @volume_monitor: The volume monitor emitting the signal.
4387 * @drive: the drive that changed
4389 * Emitted when a drive changes.
4394 * GVolumeMonitor::drive-connected:
4395 * @volume_monitor: The volume monitor emitting the signal.
4396 * @drive: a #GDrive that was connected.
4398 * Emitted when a drive is connected to the system.
4403 * GVolumeMonitor::drive-disconnected:
4404 * @volume_monitor: The volume monitor emitting the signal.
4405 * @drive: a #GDrive that was disconnected.
4407 * Emitted when a drive is disconnected from the system.
4412 * GVolumeMonitor::drive-eject-button:
4413 * @volume_monitor: The volume monitor emitting the signal.
4414 * @drive: the drive where the eject button was pressed
4416 * Emitted when the eject button is pressed on @drive.
4423 * GVolumeMonitor::drive-stop-button:
4424 * @volume_monitor: The volume monitor emitting the signal.
4425 * @drive: the drive where the stop button was pressed
4427 * Emitted when the stop button is pressed on @drive.
4434 * GVolumeMonitor::mount-added:
4435 * @volume_monitor: The volume monitor emitting the signal.
4436 * @mount: a #GMount that was added.
4438 * Emitted when a mount is added.
4443 * GVolumeMonitor::mount-changed:
4444 * @volume_monitor: The volume monitor emitting the signal.
4445 * @mount: a #GMount that changed.
4447 * Emitted when a mount changes.
4452 * GVolumeMonitor::mount-pre-unmount:
4453 * @volume_monitor: The volume monitor emitting the signal.
4454 * @mount: a #GMount that is being unmounted.
4456 * May be emitted when a mount is about to be removed.
4458 * This signal depends on the backend and is only emitted if
4459 * GIO was used to unmount.
4464 * GVolumeMonitor::mount-removed:
4465 * @volume_monitor: The volume monitor emitting the signal.
4466 * @mount: a #GMount that was removed.
4468 * Emitted when a mount is removed.
4473 * GVolumeMonitor::volume-added:
4474 * @volume_monitor: The volume monitor emitting the signal.
4475 * @volume: a #GVolume that was added.
4477 * Emitted when a mountable volume is added to the system.
4482 * GVolumeMonitor::volume-changed:
4483 * @volume_monitor: The volume monitor emitting the signal.
4484 * @volume: a #GVolume that changed.
4486 * Emitted when mountable volume is changed.
4491 * GVolumeMonitor::volume-removed:
4492 * @volume_monitor: The volume monitor emitting the signal.
4493 * @volume: a #GVolume that was removed.
4495 * Emitted when a mountable volume is removed from the system.
4500 * GWin32InputStream:close-handle:
4502 * Whether to close the file handle when the stream is closed.
4509 * GWin32InputStream:handle:
4511 * The handle that the stream reads from.
4518 * GWin32OutputStream:close-handle:
4520 * Whether to close the file handle when the stream is closed.
4527 * GWin32OutputStream:handle:
4529 * The file handle that the stream writes to.
4536 * GWin32RegistryKey:path:
4538 * A path to the key in the registry, in UTF-8.
4545 * GWin32RegistryKey:path-utf16:
4547 * A path to the key in the registry, in UTF-16.
4556 * Zlib decompression
4561 * GZlibCompressor:file-info:
4563 * If set to a non-%NULL #GFileInfo object, and #GZlibCompressor:format is
4564 * %G_ZLIB_COMPRESSOR_FORMAT_GZIP, the compressor will write the file name
4565 * and modification time from the file info to the GZIP header.
4572 * GZlibDecompressor:
4574 * Zlib decompression
4579 * GZlibDecompressor:file-info:
4581 * A #GFileInfo containing the information found in the GZIP header
4582 * of the data stream processed, or %NULL if the header was not yet
4583 * fully processed, is not present at all, or the compressor's
4584 * #GZlibDecompressor:format property is not %G_ZLIB_COMPRESSOR_FORMAT_GZIP.
4591 * G_TLS_DATABASE_PURPOSE_AUTHENTICATE_CLIENT:
4593 * The purpose used to verify the client certificate in a TLS connection.
4594 * Used by TLS servers.
4599 * G_TLS_DATABASE_PURPOSE_AUTHENTICATE_SERVER:
4601 * The purpose used to verify the server certificate in a TLS connection. This
4602 * is the most common purpose in use. Used by TLS clients.
4607 * G_TYPE_SETTINGS_SCHEMA:
4609 * A boxed #GType corresponding to #GSettingsSchema.
4616 * G_TYPE_SETTINGS_SCHEMA_SOURCE:
4618 * A boxed #GType corresponding to #GSettingsSchemaSource.
4625 * SECTION:extensionpoints
4626 * @short_description: Extension Points
4628 * @see_also: [Extending GIO][extending-gio]
4630 * #GIOExtensionPoint provides a mechanism for modules to extend the
4631 * functionality of the library or application that loaded it in an
4632 * organized fashion.
4634 * An extension point is identified by a name, and it may optionally
4635 * require that any implementation must be of a certain type (or derived
4636 * thereof). Use g_io_extension_point_register() to register an
4637 * extension point, and g_io_extension_point_set_required_type() to
4638 * set a required type.
4640 * A module can implement an extension point by specifying the #GType
4641 * that implements the functionality. Additionally, each implementation
4642 * of an extension point has a name, and a priority. Use
4643 * g_io_extension_point_implement() to implement an extension point.
4645 * |[<!-- language="C" -->
4646 * GIOExtensionPoint *ep;
4648 * // Register an extension point
4649 * ep = g_io_extension_point_register ("my-extension-point");
4650 * g_io_extension_point_set_required_type (ep, MY_TYPE_EXAMPLE);
4653 * |[<!-- language="C" -->
4654 * // Implement an extension point
4655 * G_DEFINE_TYPE (MyExampleImpl, my_example_impl, MY_TYPE_EXAMPLE)
4656 * g_io_extension_point_implement ("my-extension-point",
4657 * my_example_impl_get_type (),
4662 * It is up to the code that registered the extension point how
4663 * it uses the implementations that have been associated with it.
4664 * Depending on the use case, it may use all implementations, or
4665 * only the one with the highest priority, or pick a specific
4668 * To avoid opening all modules just to find out what extension
4669 * points they implement, GIO makes use of a caching mechanism,
4670 * see [gio-querymodules][gio-querymodules].
4671 * You are expected to run this command after installing a
4674 * The `GIO_EXTRA_MODULES` environment variable can be used to
4675 * specify additional directories to automatically load modules
4676 * from. This environment variable has the same syntax as the
4677 * `PATH`. If two modules have the same base name in different
4678 * directories, then the latter one will be ignored. If additional
4679 * directories are specified GIO will load modules from the built-in
4687 * @short_description: An action interface
4688 * @include: gio/gio.h
4690 * #GAction represents a single named action.
4692 * The main interface to an action is that it can be activated with
4693 * g_action_activate(). This results in the 'activate' signal being
4694 * emitted. An activation has a #GVariant parameter (which may be
4695 * %NULL). The correct type for the parameter is determined by a static
4696 * parameter type (which is given at construction time).
4698 * An action may optionally have a state, in which case the state may be
4699 * set with g_action_change_state(). This call takes a #GVariant. The
4700 * correct type for the state is determined by a static state type
4701 * (which is given at construction time).
4703 * The state may have a hint associated with it, specifying its valid
4706 * #GAction is merely the interface to the concept of an action, as
4707 * described above. Various implementations of actions exist, including
4710 * In all cases, the implementing class is responsible for storing the
4711 * name of the action, the parameter type, the enabled state, the
4712 * optional state type and the state and emitting the appropriate
4713 * signals when these change. The implementor is responsible for filtering
4714 * calls to g_action_activate() and g_action_change_state() for type
4715 * safety and for the state being enabled.
4717 * Probably the only useful thing to do with a #GAction is to put it
4718 * inside of a #GSimpleActionGroup.
4723 * SECTION:gactiongroup
4724 * @title: GActionGroup
4725 * @short_description: A group of actions
4726 * @include: gio/gio.h
4727 * @see_also: #GAction
4729 * #GActionGroup represents a group of actions. Actions can be used to
4730 * expose functionality in a structured way, either from one part of a
4731 * program to another, or to the outside world. Action groups are often
4732 * used together with a #GMenuModel that provides additional
4733 * representation data for displaying the actions to the user, e.g. in
4736 * The main way to interact with the actions in a GActionGroup is to
4737 * activate them with g_action_group_activate_action(). Activating an
4738 * action may require a #GVariant parameter. The required type of the
4739 * parameter can be inquired with g_action_group_get_action_parameter_type().
4740 * Actions may be disabled, see g_action_group_get_action_enabled().
4741 * Activating a disabled action has no effect.
4743 * Actions may optionally have a state in the form of a #GVariant. The
4744 * current state of an action can be inquired with
4745 * g_action_group_get_action_state(). Activating a stateful action may
4746 * change its state, but it is also possible to set the state by calling
4747 * g_action_group_change_action_state().
4749 * As typical example, consider a text editing application which has an
4750 * option to change the current font to 'bold'. A good way to represent
4751 * this would be a stateful action, with a boolean state. Activating the
4752 * action would toggle the state.
4754 * Each action in the group has a unique name (which is a string). All
4755 * method calls, except g_action_group_list_actions() take the name of
4756 * an action as an argument.
4758 * The #GActionGroup API is meant to be the 'public' API to the action
4759 * group. The calls here are exactly the interaction that 'external
4760 * forces' (eg: UI, incoming D-Bus messages, etc.) are supposed to have
4761 * with actions. 'Internal' APIs (ie: ones meant only to be accessed by
4762 * the action group implementation) are found on subclasses. This is
4763 * why you will find - for example - g_action_group_get_action_enabled()
4764 * but not an equivalent set() call.
4766 * Signals are emitted on the action group in response to state changes
4767 * on individual actions.
4769 * Implementations of #GActionGroup should provide implementations for
4770 * the virtual functions g_action_group_list_actions() and
4771 * g_action_group_query_action(). The other virtual functions should
4772 * not be implemented - their "wrappers" are actually implemented with
4773 * calls to g_action_group_query_action().
4778 * SECTION:gactiongroupexporter
4779 * @title: GActionGroup exporter
4780 * @include: gio/gio.h
4781 * @short_description: Export GActionGroups on D-Bus
4782 * @see_also: #GActionGroup, #GDBusActionGroup
4784 * These functions support exporting a #GActionGroup on D-Bus.
4785 * The D-Bus interface that is used is a private implementation
4788 * To access an exported #GActionGroup remotely, use
4789 * g_dbus_action_group_get() to obtain a #GDBusActionGroup.
4794 * SECTION:gactionmap
4795 * @title: GActionMap
4796 * @include: gio/gio.h
4797 * @short_description: Interface for action containers
4799 * The GActionMap interface is implemented by #GActionGroup
4800 * implementations that operate by containing a number of
4801 * named #GAction instances, such as #GSimpleActionGroup.
4803 * One useful application of this interface is to map the
4804 * names of actions from various action groups to unique,
4805 * prefixed names (e.g. by prepending "app." or "win.").
4806 * This is the motivation for the 'Map' part of the interface
4815 * @short_description: Application information and launch contexts
4816 * @include: gio/gio.h
4817 * @see_also: #GAppInfoMonitor
4819 * #GAppInfo and #GAppLaunchContext are used for describing and launching
4820 * applications installed on the system.
4822 * As of GLib 2.20, URIs will always be converted to POSIX paths
4823 * (using g_file_get_path()) when using g_app_info_launch() even if
4824 * the application requested an URI and not a POSIX path. For example
4825 * for a desktop-file based application with Exec key `totem
4826 * %U` and a single URI, `sftp://foo/file.avi`, then
4827 * `/home/user/.gvfs/sftp on foo/file.avi` will be passed. This will
4828 * only work if a set of suitable GIO extensions (such as gvfs 2.26
4829 * compiled with FUSE support), is available and operational; if this
4830 * is not the case, the URI will be passed unmodified to the application.
4831 * Some URIs, such as `mailto:`, of course cannot be mapped to a POSIX
4832 * path (in gvfs there's no FUSE mount for it); such URIs will be
4833 * passed unmodified to the application.
4835 * Specifically for gvfs 2.26 and later, the POSIX URI will be mapped
4836 * back to the GIO URI in the #GFile constructors (since gvfs
4837 * implements the #GVfs extension point). As such, if the application
4838 * needs to examine the URI, it needs to use g_file_get_uri() or
4839 * similar on #GFile. In other words, an application cannot assume
4840 * that the URI passed to e.g. g_file_new_for_commandline_arg() is
4841 * equal to the result of g_file_get_uri(). The following snippet
4848 * file = g_file_new_for_commandline_arg (uri_from_commandline);
4850 * uri = g_file_get_uri (file);
4851 * strcmp (uri, uri_from_commandline) == 0;
4854 * if (g_file_has_uri_scheme (file, "cdda"))
4856 * // do something special with uri
4858 * g_object_unref (file);
4861 * This code will work when both `cdda://sr0/Track 1.wav` and
4862 * `/home/user/.gvfs/cdda on sr0/Track 1.wav` is passed to the
4863 * application. It should be noted that it's generally not safe
4864 * for applications to rely on the format of a particular URIs.
4865 * Different launcher applications (e.g. file managers) may have
4866 * different ideas of what a given URI means.
4871 * SECTION:gappinfomonitor
4872 * @short_description: Monitor application information for changes
4874 * #GAppInfoMonitor is a very simple object used for monitoring the app
4875 * info database for changes (ie: newly installed or removed
4878 * Call g_app_info_monitor_get() to get a #GAppInfoMonitor and connect
4879 * to the "changed" signal.
4881 * In the usual case, applications should try to make note of the change
4882 * (doing things like invalidating caches) but not act on it. In
4883 * particular, applications should avoid making calls to #GAppInfo APIs
4884 * in response to the change signal, deferring these until the time that
4885 * the data is actually required. The exception to this case is when
4886 * application information is actually being displayed on the screen
4887 * (eg: during a search or when the list of all applications is shown).
4888 * The reason for this is that changes to the list of installed
4889 * applications often come in groups (like during system updates) and
4890 * rescanning the list on every change is pointless and expensive.
4897 * SECTION:gapplication
4898 * @title: GApplication
4899 * @short_description: Core application class
4900 * @include: gio/gio.h
4902 * A #GApplication is the foundation of an application. It wraps some
4903 * low-level platform-specific services and is intended to act as the
4904 * foundation for higher-level application classes such as
4905 * #GtkApplication or #MxApplication. In general, you should not use
4906 * this class outside of a higher level framework.
4908 * GApplication provides convenient life cycle management by maintaining
4909 * a "use count" for the primary application instance. The use count can
4910 * be changed using g_application_hold() and g_application_release(). If
4911 * it drops to zero, the application exits. Higher-level classes such as
4912 * #GtkApplication employ the use count to ensure that the application
4913 * stays alive as long as it has any opened windows.
4915 * Another feature that GApplication (optionally) provides is process
4916 * uniqueness. Applications can make use of this functionality by
4917 * providing a unique application ID. If given, only one application
4918 * with this ID can be running at a time per session. The session
4919 * concept is platform-dependent, but corresponds roughly to a graphical
4920 * desktop login. When your application is launched again, its
4921 * arguments are passed through platform communication to the already
4922 * running program. The already running instance of the program is
4923 * called the "primary instance"; for non-unique applications this is
4924 * always the current instance. On Linux, the D-Bus session bus
4925 * is used for communication.
4927 * The use of #GApplication differs from some other commonly-used
4928 * uniqueness libraries (such as libunique) in important ways. The
4929 * application is not expected to manually register itself and check
4930 * if it is the primary instance. Instead, the main() function of a
4931 * #GApplication should do very little more than instantiating the
4932 * application instance, possibly connecting signal handlers, then
4933 * calling g_application_run(). All checks for uniqueness are done
4934 * internally. If the application is the primary instance then the
4935 * startup signal is emitted and the mainloop runs. If the application
4936 * is not the primary instance then a signal is sent to the primary
4937 * instance and g_application_run() promptly returns. See the code
4940 * If used, the expected form of an application identifier is the same as
4942 * [D-Bus well-known bus name](https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus).
4943 * Examples include: `com.example.MyApp`, `org.example.internal_apps.Calculator`,
4944 * `org._7_zip.Archiver`.
4945 * For details on valid application identifiers, see g_application_id_is_valid().
4947 * On Linux, the application identifier is claimed as a well-known bus name
4948 * on the user's session bus. This means that the uniqueness of your
4949 * application is scoped to the current session. It also means that your
4950 * application may provide additional services (through registration of other
4951 * object paths) at that bus name. The registration of these object paths
4952 * should be done with the shared GDBus session bus. Note that due to the
4953 * internal architecture of GDBus, method calls can be dispatched at any time
4954 * (even if a main loop is not running). For this reason, you must ensure that
4955 * any object paths that you wish to register are registered before #GApplication
4956 * attempts to acquire the bus name of your application (which happens in
4957 * g_application_register()). Unfortunately, this means that you cannot use
4958 * g_application_get_is_remote() to decide if you want to register object paths.
4960 * GApplication also implements the #GActionGroup and #GActionMap
4961 * interfaces and lets you easily export actions by adding them with
4962 * g_action_map_add_action(). When invoking an action by calling
4963 * g_action_group_activate_action() on the application, it is always
4964 * invoked in the primary instance. The actions are also exported on
4965 * the session bus, and GIO provides the #GDBusActionGroup wrapper to
4966 * conveniently access them remotely. GIO provides a #GDBusMenuModel wrapper
4967 * for remote access to exported #GMenuModels.
4969 * There is a number of different entry points into a GApplication:
4971 * - via 'Activate' (i.e. just starting the application)
4973 * - via 'Open' (i.e. opening some files)
4975 * - by handling a command-line
4977 * - via activating an action
4979 * The #GApplication::startup signal lets you handle the application
4980 * initialization for all of these in a single place.
4982 * Regardless of which of these entry points is used to start the
4983 * application, GApplication passes some ‘platform data’ from the
4984 * launching instance to the primary instance, in the form of a
4985 * #GVariant dictionary mapping strings to variants. To use platform
4986 * data, override the @before_emit or @after_emit virtual functions
4987 * in your #GApplication subclass. When dealing with
4988 * #GApplicationCommandLine objects, the platform data is
4989 * directly available via g_application_command_line_get_cwd(),
4990 * g_application_command_line_get_environ() and
4991 * g_application_command_line_get_platform_data().
4993 * As the name indicates, the platform data may vary depending on the
4994 * operating system, but it always includes the current directory (key
4995 * "cwd"), and optionally the environment (ie the set of environment
4996 * variables and their values) of the calling process (key "environ").
4997 * The environment is only added to the platform data if the
4998 * %G_APPLICATION_SEND_ENVIRONMENT flag is set. #GApplication subclasses
4999 * can add their own platform data by overriding the @add_platform_data
5000 * virtual function. For instance, #GtkApplication adds startup notification
5003 * To parse commandline arguments you may handle the
5004 * #GApplication::command-line signal or override the local_command_line()
5005 * vfunc, to parse them in either the primary instance or the local instance,
5008 * For an example of opening files with a GApplication, see
5009 * [gapplication-example-open.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-open.c).
5011 * For an example of using actions with GApplication, see
5012 * [gapplication-example-actions.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-actions.c).
5014 * For an example of using extra D-Bus hooks with GApplication, see
5015 * [gapplication-example-dbushooks.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-dbushooks.c).
5020 * SECTION:gapplicationcommandline
5021 * @title: GApplicationCommandLine
5022 * @short_description: A command-line invocation of an application
5023 * @include: gio/gio.h
5024 * @see_also: #GApplication
5026 * #GApplicationCommandLine represents a command-line invocation of
5027 * an application. It is created by #GApplication and emitted
5028 * in the #GApplication::command-line signal and virtual function.
5030 * The class contains the list of arguments that the program was invoked
5031 * with. It is also possible to query if the commandline invocation was
5032 * local (ie: the current process is running in direct response to the
5033 * invocation) or remote (ie: some other process forwarded the
5034 * commandline to this process).
5036 * The GApplicationCommandLine object can provide the @argc and @argv
5037 * parameters for use with the #GOptionContext command-line parsing API,
5038 * with the g_application_command_line_get_arguments() function. See
5039 * [gapplication-example-cmdline3.c][gapplication-example-cmdline3]
5042 * The exit status of the originally-invoked process may be set and
5043 * messages can be printed to stdout or stderr of that process. The
5044 * lifecycle of the originally-invoked process is tied to the lifecycle
5045 * of this object (ie: the process exits when the last reference is
5048 * The main use for #GApplicationCommandLine (and the
5049 * #GApplication::command-line signal) is 'Emacs server' like use cases:
5050 * You can set the `EDITOR` environment variable to have e.g. git use
5051 * your favourite editor to edit commit messages, and if you already
5052 * have an instance of the editor running, the editing will happen
5053 * in the running instance, instead of opening a new one. An important
5054 * aspect of this use case is that the process that gets started by git
5055 * does not return until the editing is done.
5057 * Normally, the commandline is completely handled in the
5058 * #GApplication::command-line handler. The launching instance exits
5059 * once the signal handler in the primary instance has returned, and
5060 * the return value of the signal handler becomes the exit status
5061 * of the launching instance.
5062 * |[<!-- language="C" -->
5064 * command_line (GApplication *application,
5065 * GApplicationCommandLine *cmdline)
5071 * argv = g_application_command_line_get_arguments (cmdline, &argc);
5073 * g_application_command_line_print (cmdline,
5074 * "This text is written back\n"
5075 * "to stdout of the caller\n");
5077 * for (i = 0; i < argc; i++)
5078 * g_print ("argument %d: %s\n", i, argv[i]);
5080 * g_strfreev (argv);
5085 * The complete example can be found here:
5086 * [gapplication-example-cmdline.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-cmdline.c)
5088 * In more complicated cases, the handling of the comandline can be
5089 * split between the launcher and the primary instance.
5090 * |[<!-- language="C" -->
5092 * test_local_cmdline (GApplication *application,
5093 * gchar ***arguments,
5094 * gint *exit_status)
5099 * argv = *arguments;
5104 * if (g_str_has_prefix (argv[i], "--local-"))
5106 * g_print ("handling argument %s locally\n", argv[i]);
5108 * for (j = i; argv[j]; j++)
5109 * argv[j] = argv[j + 1];
5113 * g_print ("not handling argument %s locally\n", argv[i]);
5124 * test_application_class_init (TestApplicationClass *class)
5126 * G_APPLICATION_CLASS (class)->local_command_line = test_local_cmdline;
5131 * In this example of split commandline handling, options that start
5132 * with `--local-` are handled locally, all other options are passed
5133 * to the #GApplication::command-line handler which runs in the primary
5136 * The complete example can be found here:
5137 * [gapplication-example-cmdline2.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-cmdline2.c)
5139 * If handling the commandline requires a lot of work, it may
5140 * be better to defer it.
5141 * |[<!-- language="C" -->
5143 * my_cmdline_handler (gpointer data)
5145 * GApplicationCommandLine *cmdline = data;
5147 * // do the heavy lifting in an idle
5149 * g_application_command_line_set_exit_status (cmdline, 0);
5150 * g_object_unref (cmdline); // this releases the application
5152 * return G_SOURCE_REMOVE;
5156 * command_line (GApplication *application,
5157 * GApplicationCommandLine *cmdline)
5159 * // keep the application running until we are done with this commandline
5160 * g_application_hold (application);
5162 * g_object_set_data_full (G_OBJECT (cmdline),
5163 * "application", application,
5164 * (GDestroyNotify)g_application_release);
5166 * g_object_ref (cmdline);
5167 * g_idle_add (my_cmdline_handler, cmdline);
5172 * In this example the commandline is not completely handled before
5173 * the #GApplication::command-line handler returns. Instead, we keep
5174 * a reference to the #GApplicationCommandLine object and handle it
5175 * later (in this example, in an idle). Note that it is necessary to
5176 * hold the application until you are done with the commandline.
5178 * The complete example can be found here:
5179 * [gapplication-example-cmdline3.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-cmdline3.c)
5184 * SECTION:gasyncinitable
5185 * @short_description: Asynchronously failable object initialization interface
5186 * @include: gio/gio.h
5187 * @see_also: #GInitable
5189 * This is the asynchronous version of #GInitable; it behaves the same
5190 * in all ways except that initialization is asynchronous. For more details
5191 * see the descriptions on #GInitable.
5193 * A class may implement both the #GInitable and #GAsyncInitable interfaces.
5195 * Users of objects implementing this are not intended to use the interface
5196 * method directly; instead it will be used automatically in various ways.
5197 * For C applications you generally just call g_async_initable_new_async()
5198 * directly, or indirectly via a foo_thing_new_async() wrapper. This will call
5199 * g_async_initable_init_async() under the cover, calling back with %NULL and
5200 * a set %GError on failure.
5202 * A typical implementation might look something like this:
5204 * |[<!-- language="C" -->
5212 * _foo_ready_cb (Foo *self)
5216 * self->priv->state = INITIALIZED;
5218 * for (l = self->priv->init_results; l != NULL; l = l->next)
5220 * GTask *task = l->data;
5222 * if (self->priv->success)
5223 * g_task_return_boolean (task, TRUE);
5225 * g_task_return_new_error (task, ...);
5226 * g_object_unref (task);
5229 * g_list_free (self->priv->init_results);
5230 * self->priv->init_results = NULL;
5234 * foo_init_async (GAsyncInitable *initable,
5236 * GCancellable *cancellable,
5237 * GAsyncReadyCallback callback,
5238 * gpointer user_data)
5240 * Foo *self = FOO (initable);
5243 * task = g_task_new (initable, cancellable, callback, user_data);
5244 * g_task_set_name (task, G_STRFUNC);
5246 * switch (self->priv->state)
5248 * case NOT_INITIALIZED:
5249 * _foo_get_ready (self);
5250 * self->priv->init_results = g_list_append (self->priv->init_results,
5252 * self->priv->state = INITIALIZING;
5254 * case INITIALIZING:
5255 * self->priv->init_results = g_list_append (self->priv->init_results,
5259 * if (!self->priv->success)
5260 * g_task_return_new_error (task, ...);
5262 * g_task_return_boolean (task, TRUE);
5263 * g_object_unref (task);
5269 * foo_init_finish (GAsyncInitable *initable,
5270 * GAsyncResult *result,
5273 * g_return_val_if_fail (g_task_is_valid (result, initable), FALSE);
5275 * return g_task_propagate_boolean (G_TASK (result), error);
5279 * foo_async_initable_iface_init (gpointer g_iface,
5282 * GAsyncInitableIface *iface = g_iface;
5284 * iface->init_async = foo_init_async;
5285 * iface->init_finish = foo_init_finish;
5292 * SECTION:gasyncresult
5293 * @short_description: Asynchronous Function Results
5294 * @include: gio/gio.h
5297 * Provides a base class for implementing asynchronous function results.
5299 * Asynchronous operations are broken up into two separate operations
5300 * which are chained together by a #GAsyncReadyCallback. To begin
5301 * an asynchronous operation, provide a #GAsyncReadyCallback to the
5302 * asynchronous function. This callback will be triggered when the
5303 * operation has completed, and must be run in a later iteration of
5304 * the [thread-default main context][g-main-context-push-thread-default]
5305 * from where the operation was initiated. It will be passed a
5306 * #GAsyncResult instance filled with the details of the operation's
5307 * success or failure, the object the asynchronous function was
5308 * started for and any error codes returned. The asynchronous callback
5309 * function is then expected to call the corresponding "_finish()"
5310 * function, passing the object the function was called for, the
5311 * #GAsyncResult instance, and (optionally) an @error to grab any
5312 * error conditions that may have occurred.
5314 * The "_finish()" function for an operation takes the generic result
5315 * (of type #GAsyncResult) and returns the specific result that the
5316 * operation in question yields (e.g. a #GFileEnumerator for a
5317 * "enumerate children" operation). If the result or error status of the
5318 * operation is not needed, there is no need to call the "_finish()"
5319 * function; GIO will take care of cleaning up the result and error
5320 * information after the #GAsyncReadyCallback returns. You can pass
5321 * %NULL for the #GAsyncReadyCallback if you don't need to take any
5322 * action at all after the operation completes. Applications may also
5323 * take a reference to the #GAsyncResult and call "_finish()" later;
5324 * however, the "_finish()" function may be called at most once.
5326 * Example of a typical asynchronous operation flow:
5327 * |[<!-- language="C" -->
5328 * void _theoretical_frobnitz_async (Theoretical *t,
5330 * GAsyncReadyCallback cb,
5333 * gboolean _theoretical_frobnitz_finish (Theoretical *t,
5334 * GAsyncResult *res,
5338 * frobnitz_result_func (GObject *source_object,
5339 * GAsyncResult *res,
5340 * gpointer user_data)
5342 * gboolean success = FALSE;
5344 * success = _theoretical_frobnitz_finish (source_object, res, NULL);
5347 * g_printf ("Hurray!\n");
5349 * g_printf ("Uh oh!\n");
5355 * int main (int argc, void *argv[])
5359 * _theoretical_frobnitz_async (theoretical_data,
5361 * frobnitz_result_func,
5368 * The callback for an asynchronous operation is called only once, and is
5369 * always called, even in the case of a cancelled operation. On cancellation
5370 * the result is a %G_IO_ERROR_CANCELLED error.
5372 * ## I/O Priority # {#io-priority}
5374 * Many I/O-related asynchronous operations have a priority parameter,
5375 * which is used in certain cases to determine the order in which
5376 * operations are executed. They are not used to determine system-wide
5377 * I/O scheduling. Priorities are integers, with lower numbers indicating
5378 * higher priority. It is recommended to choose priorities between
5379 * %G_PRIORITY_LOW and %G_PRIORITY_HIGH, with %G_PRIORITY_DEFAULT
5385 * SECTION:gbufferedinputstream
5386 * @short_description: Buffered Input Stream
5387 * @include: gio/gio.h
5388 * @see_also: #GFilterInputStream, #GInputStream
5390 * Buffered input stream implements #GFilterInputStream and provides
5391 * for buffered reads.
5393 * By default, #GBufferedInputStream's buffer size is set at 4 kilobytes.
5395 * To create a buffered input stream, use g_buffered_input_stream_new(),
5396 * or g_buffered_input_stream_new_sized() to specify the buffer's size at
5399 * To get the size of a buffer within a buffered input stream, use
5400 * g_buffered_input_stream_get_buffer_size(). To change the size of a
5401 * buffered input stream's buffer, use
5402 * g_buffered_input_stream_set_buffer_size(). Note that the buffer's size
5403 * cannot be reduced below the size of the data within the buffer.
5408 * SECTION:gbufferedoutputstream
5409 * @short_description: Buffered Output Stream
5410 * @include: gio/gio.h
5411 * @see_also: #GFilterOutputStream, #GOutputStream
5413 * Buffered output stream implements #GFilterOutputStream and provides
5414 * for buffered writes.
5416 * By default, #GBufferedOutputStream's buffer size is set at 4 kilobytes.
5418 * To create a buffered output stream, use g_buffered_output_stream_new(),
5419 * or g_buffered_output_stream_new_sized() to specify the buffer's size
5422 * To get the size of a buffer within a buffered input stream, use
5423 * g_buffered_output_stream_get_buffer_size(). To change the size of a
5424 * buffered output stream's buffer, use
5425 * g_buffered_output_stream_set_buffer_size(). Note that the buffer's
5426 * size cannot be reduced below the size of the data within the buffer.
5431 * SECTION:gbytesicon
5432 * @short_description: An icon stored in memory as a GBytes
5433 * @include: gio/gio.h
5434 * @see_also: #GIcon, #GLoadableIcon, #GBytes
5436 * #GBytesIcon specifies an image held in memory in a common format (usually
5437 * png) to be used as icon.
5444 * SECTION:gcancellable
5445 * @short_description: Thread-safe Operation Cancellation Stack
5446 * @include: gio/gio.h
5448 * GCancellable is a thread-safe operation cancellation stack used
5449 * throughout GIO to allow for cancellation of synchronous and
5450 * asynchronous operations.
5455 * SECTION:gcharsetconverter
5456 * @short_description: Convert between charsets
5457 * @include: gio/gio.h
5459 * #GCharsetConverter is an implementation of #GConverter based on
5465 * SECTION:gcontenttype
5466 * @short_description: Platform-specific content typing
5467 * @include: gio/gio.h
5469 * A content type is a platform specific string that defines the type
5470 * of a file. On UNIX it is a
5471 * [MIME type](http://www.wikipedia.org/wiki/Internet_media_type)
5472 * like `text/plain` or `image/png`.
5473 * On Win32 it is an extension string like `.doc`, `.txt` or a perceived
5474 * string like `audio`. Such strings can be looked up in the registry at
5475 * `HKEY_CLASSES_ROOT`.
5476 * On macOS it is a [Uniform Type Identifier](https://en.wikipedia.org/wiki/Uniform_Type_Identifier)
5477 * such as `com.apple.application`.
5482 * SECTION:gconverter
5483 * @short_description: Data conversion interface
5484 * @include: gio/gio.h
5485 * @see_also: #GInputStream, #GOutputStream
5487 * #GConverter is implemented by objects that convert
5488 * binary data in various ways. The conversion can be
5489 * stateful and may fail at any place.
5491 * Some example conversions are: character set conversion,
5492 * compression, decompression and regular expression
5500 * SECTION:gconverterinputstream
5501 * @short_description: Converter Input Stream
5502 * @include: gio/gio.h
5503 * @see_also: #GInputStream, #GConverter
5505 * Converter input stream implements #GInputStream and allows
5506 * conversion of data of various types during reading.
5508 * As of GLib 2.34, #GConverterInputStream implements
5509 * #GPollableInputStream.
5514 * SECTION:gconverteroutputstream
5515 * @short_description: Converter Output Stream
5516 * @include: gio/gio.h
5517 * @see_also: #GOutputStream, #GConverter
5519 * Converter output stream implements #GOutputStream and allows
5520 * conversion of data of various types during reading.
5522 * As of GLib 2.34, #GConverterOutputStream implements
5523 * #GPollableOutputStream.
5528 * SECTION:gcredentials
5529 * @short_description: An object containing credentials
5530 * @include: gio/gio.h
5532 * The #GCredentials type is a reference-counted wrapper for native
5533 * credentials. This information is typically used for identifying,
5534 * authenticating and authorizing other processes.
5536 * Some operating systems supports looking up the credentials of the
5537 * remote peer of a communication endpoint - see e.g.
5538 * g_socket_get_credentials().
5540 * Some operating systems supports securely sending and receiving
5541 * credentials over a Unix Domain Socket, see
5542 * #GUnixCredentialsMessage, g_unix_connection_send_credentials() and
5543 * g_unix_connection_receive_credentials() for details.
5545 * On Linux, the native credential type is a `struct ucred` - see the
5546 * unix(7) man page for details. This corresponds to
5547 * %G_CREDENTIALS_TYPE_LINUX_UCRED.
5549 * On Apple operating systems (including iOS, tvOS, and macOS),
5550 * the native credential type is a `struct xucred`.
5551 * This corresponds to %G_CREDENTIALS_TYPE_APPLE_XUCRED.
5553 * On FreeBSD, Debian GNU/kFreeBSD, and GNU/Hurd, the native
5554 * credential type is a `struct cmsgcred`. This corresponds
5555 * to %G_CREDENTIALS_TYPE_FREEBSD_CMSGCRED.
5557 * On NetBSD, the native credential type is a `struct unpcbid`.
5558 * This corresponds to %G_CREDENTIALS_TYPE_NETBSD_UNPCBID.
5560 * On OpenBSD, the native credential type is a `struct sockpeercred`.
5561 * This corresponds to %G_CREDENTIALS_TYPE_OPENBSD_SOCKPEERCRED.
5563 * On Solaris (including OpenSolaris and its derivatives), the native
5564 * credential type is a `ucred_t`. This corresponds to
5565 * %G_CREDENTIALS_TYPE_SOLARIS_UCRED.
5570 * SECTION:gdatagrambased
5571 * @short_description: Low-level datagram communications interface
5572 * @include: gio/gio.h
5573 * @see_also: #GSocket, [<gnetworking.h>][gio-gnetworking.h]
5575 * A #GDatagramBased is a networking interface for representing datagram-based
5576 * communications. It is a more or less direct mapping of the core parts of the
5577 * BSD socket API in a portable GObject interface. It is implemented by
5578 * #GSocket, which wraps the UNIX socket API on UNIX and winsock2 on Windows.
5580 * #GDatagramBased is entirely platform independent, and is intended to be used
5581 * alongside higher-level networking APIs such as #GIOStream.
5583 * It uses vectored scatter/gather I/O by default, allowing for many messages
5584 * to be sent or received in a single call. Where possible, implementations of
5585 * the interface should take advantage of vectored I/O to minimise processing
5586 * or system calls. For example, #GSocket uses recvmmsg() and sendmmsg() where
5587 * possible. Callers should take advantage of scatter/gather I/O (the use of
5588 * multiple buffers per message) to avoid unnecessary copying of data to
5589 * assemble or disassemble a message.
5591 * Each #GDatagramBased operation has a timeout parameter which may be negative
5592 * for blocking behaviour, zero for non-blocking behaviour, or positive for
5593 * timeout behaviour. A blocking operation blocks until finished or there is an
5594 * error. A non-blocking operation will return immediately with a
5595 * %G_IO_ERROR_WOULD_BLOCK error if it cannot make progress. A timeout operation
5596 * will block until the operation is complete or the timeout expires; if the
5597 * timeout expires it will return what progress it made, or
5598 * %G_IO_ERROR_TIMED_OUT if no progress was made. To know when a call would
5599 * successfully run you can call g_datagram_based_condition_check() or
5600 * g_datagram_based_condition_wait(). You can also use
5601 * g_datagram_based_create_source() and attach it to a #GMainContext to get
5602 * callbacks when I/O is possible.
5604 * When running a non-blocking operation applications should always be able to
5605 * handle getting a %G_IO_ERROR_WOULD_BLOCK error even when some other function
5606 * said that I/O was possible. This can easily happen in case of a race
5607 * condition in the application, but it can also happen for other reasons. For
5608 * instance, on Windows a socket is always seen as writable until a write
5609 * returns %G_IO_ERROR_WOULD_BLOCK.
5611 * As with #GSocket, #GDatagramBaseds can be either connection oriented (for
5612 * example, SCTP) or connectionless (for example, UDP). #GDatagramBaseds must be
5613 * datagram-based, not stream-based. The interface does not cover connection
5614 * establishment — use methods on the underlying type to establish a connection
5615 * before sending and receiving data through the #GDatagramBased API. For
5616 * connectionless socket types the target/source address is specified or
5617 * received in each I/O operation.
5619 * Like most other APIs in GLib, #GDatagramBased is not inherently thread safe.
5620 * To use a #GDatagramBased concurrently from multiple threads, you must
5621 * implement your own locking.
5628 * SECTION:gdatainputstream
5629 * @short_description: Data Input Stream
5630 * @include: gio/gio.h
5631 * @see_also: #GInputStream
5633 * Data input stream implements #GInputStream and includes functions for
5634 * reading structured data directly from a binary input stream.
5639 * SECTION:gdataoutputstream
5640 * @short_description: Data Output Stream
5641 * @include: gio/gio.h
5642 * @see_also: #GOutputStream
5644 * Data output stream implements #GOutputStream and includes functions for
5645 * writing data directly to an output stream.
5650 * SECTION:gdbusactiongroup
5651 * @title: GDBusActionGroup
5652 * @short_description: A D-Bus GActionGroup implementation
5653 * @include: gio/gio.h
5654 * @see_also: [GActionGroup exporter][gio-GActionGroup-exporter]
5656 * #GDBusActionGroup is an implementation of the #GActionGroup
5657 * interface that can be used as a proxy for an action group
5658 * that is exported over D-Bus with g_dbus_connection_export_action_group().
5663 * SECTION:gdbusaddress
5664 * @title: D-Bus Addresses
5665 * @short_description: D-Bus connection endpoints
5666 * @include: gio/gio.h
5668 * Routines for working with D-Bus addresses. A D-Bus address is a string
5669 * like `unix:tmpdir=/tmp/my-app-name`. The exact format of addresses
5670 * is explained in detail in the
5671 * [D-Bus specification](http://dbus.freedesktop.org/doc/dbus-specification.html#addresses).
5673 * TCP D-Bus connections are supported, but accessing them via a proxy is
5674 * currently not supported.
5679 * SECTION:gdbusauthobserver
5680 * @short_description: Object used for authenticating connections
5681 * @include: gio/gio.h
5683 * The #GDBusAuthObserver type provides a mechanism for participating
5684 * in how a #GDBusServer (or a #GDBusConnection) authenticates remote
5685 * peers. Simply instantiate a #GDBusAuthObserver and connect to the
5686 * signals you are interested in. Note that new signals may be added
5689 * ## Controlling Authentication Mechanisms
5691 * By default, a #GDBusServer or server-side #GDBusConnection will allow
5692 * any authentication mechanism to be used. If you only
5693 * want to allow D-Bus connections with the `EXTERNAL` mechanism,
5694 * which makes use of credentials passing and is the recommended
5695 * mechanism for modern Unix platforms such as Linux and the BSD family,
5696 * you would use a signal handler like this:
5698 * |[<!-- language="C" -->
5700 * on_allow_mechanism (GDBusAuthObserver *observer,
5701 * const gchar *mechanism,
5702 * gpointer user_data)
5704 * if (g_strcmp0 (mechanism, "EXTERNAL") == 0)
5713 * ## Controlling Authorization # {#auth-observer}
5715 * By default, a #GDBusServer or server-side #GDBusConnection will accept
5716 * connections from any successfully authenticated user (but not from
5717 * anonymous connections using the `ANONYMOUS` mechanism). If you only
5718 * want to allow D-Bus connections from processes owned by the same uid
5719 * as the server, since GLib 2.68, you should use the
5720 * %G_DBUS_SERVER_FLAGS_AUTHENTICATION_REQUIRE_SAME_USER flag. It’s equivalent
5721 * to the following signal handler:
5723 * |[<!-- language="C" -->
5725 * on_authorize_authenticated_peer (GDBusAuthObserver *observer,
5726 * GIOStream *stream,
5727 * GCredentials *credentials,
5728 * gpointer user_data)
5730 * gboolean authorized;
5732 * authorized = FALSE;
5733 * if (credentials != NULL)
5735 * GCredentials *own_credentials;
5736 * own_credentials = g_credentials_new ();
5737 * if (g_credentials_is_same_user (credentials, own_credentials, NULL))
5738 * authorized = TRUE;
5739 * g_object_unref (own_credentials);
5742 * return authorized;
5749 * SECTION:gdbusconnection
5750 * @short_description: D-Bus Connections
5751 * @include: gio/gio.h
5753 * The #GDBusConnection type is used for D-Bus connections to remote
5754 * peers such as a message buses. It is a low-level API that offers a
5755 * lot of flexibility. For instance, it lets you establish a connection
5756 * over any transport that can by represented as a #GIOStream.
5758 * This class is rarely used directly in D-Bus clients. If you are writing
5759 * a D-Bus client, it is often easier to use the g_bus_own_name(),
5760 * g_bus_watch_name() or g_dbus_proxy_new_for_bus() APIs.
5762 * As an exception to the usual GLib rule that a particular object must not
5763 * be used by two threads at the same time, #GDBusConnection's methods may be
5764 * called from any thread. This is so that g_bus_get() and g_bus_get_sync()
5765 * can safely return the same #GDBusConnection when called from any thread.
5767 * Most of the ways to obtain a #GDBusConnection automatically initialize it
5768 * (i.e. connect to D-Bus): for instance, g_dbus_connection_new() and
5769 * g_bus_get(), and the synchronous versions of those methods, give you an
5770 * initialized connection. Language bindings for GIO should use
5771 * g_initable_new() or g_async_initable_new_async(), which also initialize the
5774 * If you construct an uninitialized #GDBusConnection, such as via
5775 * g_object_new(), you must initialize it via g_initable_init() or
5776 * g_async_initable_init_async() before using its methods or properties.
5777 * Calling methods or accessing properties on a #GDBusConnection that has not
5778 * completed initialization successfully is considered to be invalid, and leads
5779 * to undefined behaviour. In particular, if initialization fails with a
5780 * #GError, the only valid thing you can do with that #GDBusConnection is to
5781 * free it with g_object_unref().
5783 * ## An example D-Bus server # {#gdbus-server}
5785 * Here is an example for a D-Bus server:
5786 * [gdbus-example-server.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-server.c)
5788 * ## An example for exporting a subtree # {#gdbus-subtree-server}
5790 * Here is an example for exporting a subtree:
5791 * [gdbus-example-subtree.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-subtree.c)
5793 * ## An example for file descriptor passing # {#gdbus-unix-fd-client}
5795 * Here is an example for passing UNIX file descriptors:
5796 * [gdbus-unix-fd-client.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-unix-fd-client.c)
5798 * ## An example for exporting a GObject # {#gdbus-export}
5800 * Here is an example for exporting a #GObject:
5801 * [gdbus-example-export.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-export.c)
5806 * SECTION:gdbuserror
5807 * @title: GDBusError
5808 * @short_description: Mapping D-Bus errors to and from GError
5809 * @include: gio/gio.h
5811 * All facilities that return errors from remote methods (such as
5812 * g_dbus_connection_call_sync()) use #GError to represent both D-Bus
5813 * errors (e.g. errors returned from the other peer) and locally
5814 * in-process generated errors.
5816 * To check if a returned #GError is an error from a remote peer, use
5817 * g_dbus_error_is_remote_error(). To get the actual D-Bus error name,
5818 * use g_dbus_error_get_remote_error(). Before presenting an error,
5819 * always use g_dbus_error_strip_remote_error().
5821 * In addition, facilities used to return errors to a remote peer also
5822 * use #GError. See g_dbus_method_invocation_return_error() for
5823 * discussion about how the D-Bus error name is set.
5825 * Applications can associate a #GError error domain with a set of D-Bus errors in order to
5826 * automatically map from D-Bus errors to #GError and back. This
5827 * is typically done in the function returning the #GQuark for the
5829 * |[<!-- language="C" -->
5830 * // foo-bar-error.h:
5832 * #define FOO_BAR_ERROR (foo_bar_error_quark ())
5833 * GQuark foo_bar_error_quark (void);
5837 * FOO_BAR_ERROR_FAILED,
5838 * FOO_BAR_ERROR_ANOTHER_ERROR,
5839 * FOO_BAR_ERROR_SOME_THIRD_ERROR,
5840 * FOO_BAR_N_ERRORS / *< skip >* /
5843 * // foo-bar-error.c:
5845 * static const GDBusErrorEntry foo_bar_error_entries[] =
5847 * {FOO_BAR_ERROR_FAILED, "org.project.Foo.Bar.Error.Failed"},
5848 * {FOO_BAR_ERROR_ANOTHER_ERROR, "org.project.Foo.Bar.Error.AnotherError"},
5849 * {FOO_BAR_ERROR_SOME_THIRD_ERROR, "org.project.Foo.Bar.Error.SomeThirdError"},
5852 * // Ensure that every error code has an associated D-Bus error name
5853 * G_STATIC_ASSERT (G_N_ELEMENTS (foo_bar_error_entries) == FOO_BAR_N_ERRORS);
5856 * foo_bar_error_quark (void)
5858 * static gsize quark = 0;
5859 * g_dbus_error_register_error_domain ("foo-bar-error-quark",
5861 * foo_bar_error_entries,
5862 * G_N_ELEMENTS (foo_bar_error_entries));
5863 * return (GQuark) quark;
5866 * With this setup, a D-Bus peer can transparently pass e.g. %FOO_BAR_ERROR_ANOTHER_ERROR and
5867 * other peers will see the D-Bus error name org.project.Foo.Bar.Error.AnotherError.
5869 * If the other peer is using GDBus, and has registered the association with
5870 * g_dbus_error_register_error_domain() in advance (e.g. by invoking the %FOO_BAR_ERROR quark
5871 * generation itself in the previous example) the peer will see also %FOO_BAR_ERROR_ANOTHER_ERROR instead
5872 * of %G_IO_ERROR_DBUS_ERROR. Note that GDBus clients can still recover
5873 * org.project.Foo.Bar.Error.AnotherError using g_dbus_error_get_remote_error().
5875 * Note that the %G_DBUS_ERROR error domain is intended only
5876 * for returning errors from a remote message bus process. Errors
5877 * generated locally in-process by e.g. #GDBusConnection should use the
5878 * %G_IO_ERROR domain.
5883 * SECTION:gdbusinterface
5884 * @short_description: Base type for D-Bus interfaces
5885 * @include: gio/gio.h
5887 * The #GDBusInterface type is the base type for D-Bus interfaces both
5888 * on the service side (see #GDBusInterfaceSkeleton) and client side
5889 * (see #GDBusProxy).
5894 * SECTION:gdbusinterfaceskeleton
5895 * @short_description: Service-side D-Bus interface
5896 * @include: gio/gio.h
5898 * Abstract base class for D-Bus interfaces on the service side.
5903 * SECTION:gdbusintrospection
5904 * @title: D-Bus Introspection Data
5905 * @short_description: Node and interface description data structures
5906 * @include: gio/gio.h
5908 * Various data structures and convenience routines to parse and
5909 * generate D-Bus introspection XML. Introspection information is
5910 * used when registering objects with g_dbus_connection_register_object().
5912 * The format of D-Bus introspection XML is specified in the
5913 * [D-Bus specification](http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format)
5918 * SECTION:gdbusmenumodel
5919 * @title: GDBusMenuModel
5920 * @short_description: A D-Bus GMenuModel implementation
5921 * @include: gio/gio.h
5922 * @see_also: [GMenuModel Exporter][gio-GMenuModel-exporter]
5924 * #GDBusMenuModel is an implementation of #GMenuModel that can be used
5925 * as a proxy for a menu model that is exported over D-Bus with
5926 * g_dbus_connection_export_menu_model().
5931 * SECTION:gdbusmessage
5932 * @short_description: D-Bus Message
5933 * @include: gio/gio.h
5935 * A type for representing D-Bus messages that can be sent or received
5936 * on a #GDBusConnection.
5941 * SECTION:gdbusmethodinvocation
5942 * @short_description: Object for handling remote calls
5943 * @include: gio/gio.h
5945 * Instances of the #GDBusMethodInvocation class are used when
5946 * handling D-Bus method calls. It provides a way to asynchronously
5947 * return results and errors.
5949 * The normal way to obtain a #GDBusMethodInvocation object is to receive
5950 * it as an argument to the handle_method_call() function in a
5951 * #GDBusInterfaceVTable that was passed to g_dbus_connection_register_object().
5956 * SECTION:gdbusnameowning
5957 * @title: Owning Bus Names
5958 * @short_description: Simple API for owning bus names
5959 * @include: gio/gio.h
5961 * Convenience API for owning bus names.
5963 * A simple example for owning a name can be found in
5964 * [gdbus-example-own-name.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-own-name.c)
5969 * SECTION:gdbusnamewatching
5970 * @title: Watching Bus Names
5971 * @short_description: Simple API for watching bus names
5972 * @include: gio/gio.h
5974 * Convenience API for watching bus names.
5976 * A simple example for watching a name can be found in
5977 * [gdbus-example-watch-name.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-watch-name.c)
5982 * SECTION:gdbusobject
5983 * @short_description: Base type for D-Bus objects
5984 * @include: gio/gio.h
5986 * The #GDBusObject type is the base type for D-Bus objects on both
5987 * the service side (see #GDBusObjectSkeleton) and the client side
5988 * (see #GDBusObjectProxy). It is essentially just a container of
5994 * SECTION:gdbusobjectmanager
5995 * @short_description: Base type for D-Bus object managers
5996 * @include: gio/gio.h
5998 * The #GDBusObjectManager type is the base type for service- and
5999 * client-side implementations of the standardized
6000 * [org.freedesktop.DBus.ObjectManager](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager)
6003 * See #GDBusObjectManagerClient for the client-side implementation
6004 * and #GDBusObjectManagerServer for the service-side implementation.
6009 * SECTION:gdbusobjectmanagerclient
6010 * @short_description: Client-side object manager
6011 * @include: gio/gio.h
6013 * #GDBusObjectManagerClient is used to create, monitor and delete object
6014 * proxies for remote objects exported by a #GDBusObjectManagerServer (or any
6015 * code implementing the
6016 * [org.freedesktop.DBus.ObjectManager](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager)
6019 * Once an instance of this type has been created, you can connect to
6020 * the #GDBusObjectManager::object-added and
6021 * #GDBusObjectManager::object-removed signals and inspect the
6022 * #GDBusObjectProxy objects returned by
6023 * g_dbus_object_manager_get_objects().
6025 * If the name for a #GDBusObjectManagerClient is not owned by anyone at
6026 * object construction time, the default behavior is to request the
6027 * message bus to launch an owner for the name. This behavior can be
6028 * disabled using the %G_DBUS_OBJECT_MANAGER_CLIENT_FLAGS_DO_NOT_AUTO_START
6029 * flag. It's also worth noting that this only works if the name of
6030 * interest is activatable in the first place. E.g. in some cases it
6031 * is not possible to launch an owner for the requested name. In this
6032 * case, #GDBusObjectManagerClient object construction still succeeds but
6033 * there will be no object proxies
6034 * (e.g. g_dbus_object_manager_get_objects() returns the empty list) and
6035 * the #GDBusObjectManagerClient:name-owner property is %NULL.
6037 * The owner of the requested name can come and go (for example
6038 * consider a system service being restarted) – #GDBusObjectManagerClient
6039 * handles this case too; simply connect to the #GObject::notify
6040 * signal to watch for changes on the #GDBusObjectManagerClient:name-owner
6041 * property. When the name owner vanishes, the behavior is that
6042 * #GDBusObjectManagerClient:name-owner is set to %NULL (this includes
6043 * emission of the #GObject::notify signal) and then
6044 * #GDBusObjectManager::object-removed signals are synthesized
6045 * for all currently existing object proxies. Since
6046 * #GDBusObjectManagerClient:name-owner is %NULL when this happens, you can
6047 * use this information to disambiguate a synthesized signal from a
6048 * genuine signal caused by object removal on the remote
6049 * #GDBusObjectManager. Similarly, when a new name owner appears,
6050 * #GDBusObjectManager::object-added signals are synthesized
6051 * while #GDBusObjectManagerClient:name-owner is still %NULL. Only when all
6052 * object proxies have been added, the #GDBusObjectManagerClient:name-owner
6053 * is set to the new name owner (this includes emission of the
6054 * #GObject::notify signal). Furthermore, you are guaranteed that
6055 * #GDBusObjectManagerClient:name-owner will alternate between a name owner
6056 * (e.g. `:1.42`) and %NULL even in the case where
6057 * the name of interest is atomically replaced
6059 * Ultimately, #GDBusObjectManagerClient is used to obtain #GDBusProxy
6060 * instances. All signals (including the
6061 * org.freedesktop.DBus.Properties::PropertiesChanged signal)
6062 * delivered to #GDBusProxy instances are guaranteed to originate
6063 * from the name owner. This guarantee along with the behavior
6064 * described above, means that certain race conditions including the
6065 * "half the proxy is from the old owner and the other half is from
6066 * the new owner" problem cannot happen.
6068 * To avoid having the application connect to signals on the returned
6069 * #GDBusObjectProxy and #GDBusProxy objects, the
6070 * #GDBusObject::interface-added,
6071 * #GDBusObject::interface-removed,
6072 * #GDBusProxy::g-properties-changed and
6073 * #GDBusProxy::g-signal signals
6074 * are also emitted on the #GDBusObjectManagerClient instance managing these
6075 * objects. The signals emitted are
6076 * #GDBusObjectManager::interface-added,
6077 * #GDBusObjectManager::interface-removed,
6078 * #GDBusObjectManagerClient::interface-proxy-properties-changed and
6079 * #GDBusObjectManagerClient::interface-proxy-signal.
6081 * Note that all callbacks and signals are emitted in the
6082 * [thread-default main context][g-main-context-push-thread-default]
6083 * that the #GDBusObjectManagerClient object was constructed
6084 * in. Additionally, the #GDBusObjectProxy and #GDBusProxy objects
6085 * originating from the #GDBusObjectManagerClient object will be created in
6086 * the same context and, consequently, will deliver signals in the
6092 * SECTION:gdbusobjectmanagerserver
6093 * @short_description: Service-side object manager
6094 * @include: gio/gio.h
6096 * #GDBusObjectManagerServer is used to export #GDBusObject instances using
6098 * [org.freedesktop.DBus.ObjectManager](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager)
6099 * interface. For example, remote D-Bus clients can get all objects
6100 * and properties in a single call. Additionally, any change in the
6101 * object hierarchy is broadcast using signals. This means that D-Bus
6102 * clients can keep caches up to date by only listening to D-Bus
6105 * The recommended path to export an object manager at is the path form of the
6106 * well-known name of a D-Bus service, or below. For example, if a D-Bus service
6107 * is available at the well-known name `net.example.ExampleService1`, the object
6108 * manager should typically be exported at `/net/example/ExampleService1`, or
6109 * below (to allow for multiple object managers in a service).
6111 * It is supported, but not recommended, to export an object manager at the root
6114 * See #GDBusObjectManagerClient for the client-side code that is
6115 * intended to be used with #GDBusObjectManagerServer or any D-Bus
6116 * object implementing the org.freedesktop.DBus.ObjectManager
6122 * SECTION:gdbusobjectproxy
6123 * @short_description: Client-side D-Bus object
6124 * @include: gio/gio.h
6126 * A #GDBusObjectProxy is an object used to represent a remote object
6127 * with one or more D-Bus interfaces. Normally, you don't instantiate
6128 * a #GDBusObjectProxy yourself - typically #GDBusObjectManagerClient
6129 * is used to obtain it.
6136 * SECTION:gdbusobjectskeleton
6137 * @short_description: Service-side D-Bus object
6138 * @include: gio/gio.h
6140 * A #GDBusObjectSkeleton instance is essentially a group of D-Bus
6141 * interfaces. The set of exported interfaces on the object may be
6142 * dynamic and change at runtime.
6144 * This type is intended to be used with #GDBusObjectManager.
6149 * SECTION:gdbusproxy
6150 * @short_description: Client-side D-Bus interface proxy
6151 * @include: gio/gio.h
6153 * #GDBusProxy is a base class used for proxies to access a D-Bus
6154 * interface on a remote object. A #GDBusProxy can be constructed for
6155 * both well-known and unique names.
6157 * By default, #GDBusProxy will cache all properties (and listen to
6158 * changes) of the remote object, and proxy all signals that get
6159 * emitted. This behaviour can be changed by passing suitable
6160 * #GDBusProxyFlags when the proxy is created. If the proxy is for a
6161 * well-known name, the property cache is flushed when the name owner
6162 * vanishes and reloaded when a name owner appears.
6164 * The unique name owner of the proxy's name is tracked and can be read from
6165 * #GDBusProxy:g-name-owner. Connect to the #GObject::notify signal to
6166 * get notified of changes. Additionally, only signals and property
6167 * changes emitted from the current name owner are considered and
6168 * calls are always sent to the current name owner. This avoids a
6169 * number of race conditions when the name is lost by one owner and
6170 * claimed by another. However, if no name owner currently exists,
6171 * then calls will be sent to the well-known name which may result in
6172 * the message bus launching an owner (unless
6173 * %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START is set).
6175 * If the proxy is for a stateless D-Bus service, where the name owner may
6176 * be started and stopped between calls, the #GDBusProxy:g-name-owner tracking
6177 * of #GDBusProxy will cause the proxy to drop signal and property changes from
6178 * the service after it has restarted for the first time. When interacting
6179 * with a stateless D-Bus service, do not use #GDBusProxy — use direct D-Bus
6180 * method calls and signal connections.
6182 * The generic #GDBusProxy::g-properties-changed and
6183 * #GDBusProxy::g-signal signals are not very convenient to work with.
6184 * Therefore, the recommended way of working with proxies is to subclass
6185 * #GDBusProxy, and have more natural properties and signals in your derived
6186 * class. This [example][gdbus-example-gdbus-codegen] shows how this can
6187 * easily be done using the [gdbus-codegen][gdbus-codegen] tool.
6189 * A #GDBusProxy instance can be used from multiple threads but note
6190 * that all signals (e.g. #GDBusProxy::g-signal, #GDBusProxy::g-properties-changed
6191 * and #GObject::notify) are emitted in the
6192 * [thread-default main context][g-main-context-push-thread-default]
6193 * of the thread where the instance was constructed.
6195 * An example using a proxy for a well-known name can be found in
6196 * [gdbus-example-watch-proxy.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-watch-proxy.c)
6201 * SECTION:gdbusserver
6202 * @short_description: Helper for accepting connections
6203 * @include: gio/gio.h
6205 * #GDBusServer is a helper for listening to and accepting D-Bus
6206 * connections. This can be used to create a new D-Bus server, allowing two
6207 * peers to use the D-Bus protocol for their own specialized communication.
6208 * A server instance provided in this way will not perform message routing or
6209 * implement the org.freedesktop.DBus interface.
6211 * To just export an object on a well-known name on a message bus, such as the
6212 * session or system bus, you should instead use g_bus_own_name().
6214 * An example of peer-to-peer communication with GDBus can be found
6215 * in [gdbus-example-peer.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-peer.c).
6217 * Note that a minimal #GDBusServer will accept connections from any
6218 * peer. In many use-cases it will be necessary to add a #GDBusAuthObserver
6219 * that only accepts connections that have successfully authenticated
6220 * as the same user that is running the #GDBusServer. Since GLib 2.68 this can
6221 * be achieved more simply by passing the
6222 * %G_DBUS_SERVER_FLAGS_AUTHENTICATION_REQUIRE_SAME_USER flag to the server.
6227 * SECTION:gdbusutils
6228 * @title: D-Bus Utilities
6229 * @short_description: Various utilities related to D-Bus
6230 * @include: gio/gio.h
6232 * Various utility routines related to D-Bus.
6237 * SECTION:gdesktopappinfo
6238 * @title: GDesktopAppInfo
6239 * @short_description: Application information from desktop files
6240 * @include: gio/gdesktopappinfo.h
6242 * #GDesktopAppInfo is an implementation of #GAppInfo based on
6245 * Note that `<gio/gdesktopappinfo.h>` belongs to the UNIX-specific
6246 * GIO interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config
6247 * file when using it.
6253 * @short_description: Drive management
6254 * @include: gio/gio.h
6256 * #GDrive - this represent a piece of hardware connected to the machine.
6257 * It's generally only created for removable hardware or hardware with
6260 * #GDrive is a container class for #GVolume objects that stem from
6261 * the same piece of media. As such, #GDrive abstracts a drive with
6262 * (or without) removable media and provides operations for querying
6263 * whether media is available, determining whether media change is
6264 * automatically detected and ejecting the media.
6266 * If the #GDrive reports that media isn't automatically detected, one
6267 * can poll for media; typically one should not do this periodically
6268 * as a poll for media operation is potentially expensive and may
6269 * spin up the drive creating noise.
6271 * #GDrive supports starting and stopping drives with authentication
6272 * support for the former. This can be used to support a diverse set
6273 * of use cases including connecting/disconnecting iSCSI devices,
6274 * powering down external disk enclosures and starting/stopping
6275 * multi-disk devices such as RAID devices. Note that the actual
6276 * semantics and side-effects of starting/stopping a #GDrive may vary
6277 * according to implementation. To choose the correct verbs in e.g. a
6278 * file manager, use g_drive_get_start_stop_type().
6280 * For porting from GnomeVFS note that there is no equivalent of
6281 * #GDrive in that API.
6286 * SECTION:gdtlsclientconnection
6287 * @short_description: DTLS client-side connection
6288 * @include: gio/gio.h
6290 * #GDtlsClientConnection is the client-side subclass of
6291 * #GDtlsConnection, representing a client-side DTLS connection.
6298 * SECTION:gdtlsconnection
6299 * @short_description: DTLS connection type
6300 * @include: gio/gio.h
6302 * #GDtlsConnection is the base DTLS connection class type, which wraps
6303 * a #GDatagramBased and provides DTLS encryption on top of it. Its
6304 * subclasses, #GDtlsClientConnection and #GDtlsServerConnection,
6305 * implement client-side and server-side DTLS, respectively.
6307 * For TLS support, see #GTlsConnection.
6309 * As DTLS is datagram based, #GDtlsConnection implements #GDatagramBased,
6310 * presenting a datagram-socket-like API for the encrypted connection. This
6311 * operates over a base datagram connection, which is also a #GDatagramBased
6312 * (#GDtlsConnection:base-socket).
6314 * To close a DTLS connection, use g_dtls_connection_close().
6316 * Neither #GDtlsServerConnection or #GDtlsClientConnection set the peer address
6317 * on their base #GDatagramBased if it is a #GSocket — it is up to the caller to
6318 * do that if they wish. If they do not, and g_socket_close() is called on the
6319 * base socket, the #GDtlsConnection will not raise a %G_IO_ERROR_NOT_CONNECTED
6320 * error on further I/O.
6327 * SECTION:gdtlsserverconnection
6328 * @short_description: DTLS server-side connection
6329 * @include: gio/gio.h
6331 * #GDtlsServerConnection is the server-side subclass of #GDtlsConnection,
6332 * representing a server-side DTLS connection.
6340 * @short_description: An object for emblems
6341 * @include: gio/gio.h
6342 * @see_also: #GIcon, #GEmblemedIcon, #GLoadableIcon, #GThemedIcon
6344 * #GEmblem is an implementation of #GIcon that supports
6345 * having an emblem, which is an icon with additional properties.
6346 * It can than be added to a #GEmblemedIcon.
6348 * Currently, only metainformation about the emblem's origin is
6349 * supported. More may be added in the future.
6354 * SECTION:gemblemedicon
6355 * @short_description: Icon with emblems
6356 * @include: gio/gio.h
6357 * @see_also: #GIcon, #GLoadableIcon, #GThemedIcon, #GEmblem
6359 * #GEmblemedIcon is an implementation of #GIcon that supports
6360 * adding an emblem to an icon. Adding multiple emblems to an
6361 * icon is ensured via g_emblemed_icon_add_emblem().
6363 * Note that #GEmblemedIcon allows no control over the position
6364 * of the emblems. See also #GEmblem for more information.
6370 * @short_description: File and Directory Handling
6371 * @include: gio/gio.h
6372 * @see_also: #GFileInfo, #GFileEnumerator
6374 * #GFile is a high level abstraction for manipulating files on a
6375 * virtual file system. #GFiles are lightweight, immutable objects
6376 * that do no I/O upon creation. It is necessary to understand that
6377 * #GFile objects do not represent files, merely an identifier for a
6378 * file. All file content I/O is implemented as streaming operations
6379 * (see #GInputStream and #GOutputStream).
6381 * To construct a #GFile, you can use:
6382 * - g_file_new_for_path() if you have a path.
6383 * - g_file_new_for_uri() if you have a URI.
6384 * - g_file_new_for_commandline_arg() for a command line argument.
6385 * - g_file_new_tmp() to create a temporary file from a template.
6386 * - g_file_parse_name() from a UTF-8 string gotten from g_file_get_parse_name().
6387 * - g_file_new_build_filename() to create a file from path elements.
6389 * One way to think of a #GFile is as an abstraction of a pathname. For
6390 * normal files the system pathname is what is stored internally, but as
6391 * #GFiles are extensible it could also be something else that corresponds
6392 * to a pathname in a userspace implementation of a filesystem.
6394 * #GFiles make up hierarchies of directories and files that correspond to
6395 * the files on a filesystem. You can move through the file system with
6396 * #GFile using g_file_get_parent() to get an identifier for the parent
6397 * directory, g_file_get_child() to get a child within a directory,
6398 * g_file_resolve_relative_path() to resolve a relative path between two
6399 * #GFiles. There can be multiple hierarchies, so you may not end up at
6400 * the same root if you repeatedly call g_file_get_parent() on two different
6403 * All #GFiles have a basename (get with g_file_get_basename()). These names
6404 * are byte strings that are used to identify the file on the filesystem
6405 * (relative to its parent directory) and there is no guarantees that they
6406 * have any particular charset encoding or even make any sense at all. If
6407 * you want to use filenames in a user interface you should use the display
6408 * name that you can get by requesting the
6409 * %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME attribute with g_file_query_info().
6410 * This is guaranteed to be in UTF-8 and can be used in a user interface.
6411 * But always store the real basename or the #GFile to use to actually
6412 * access the file, because there is no way to go from a display name to
6415 * Using #GFile as an identifier has the same weaknesses as using a path
6416 * in that there may be multiple aliases for the same file. For instance,
6417 * hard or soft links may cause two different #GFiles to refer to the same
6418 * file. Other possible causes for aliases are: case insensitive filesystems,
6419 * short and long names on FAT/NTFS, or bind mounts in Linux. If you want to
6420 * check if two #GFiles point to the same file you can query for the
6421 * %G_FILE_ATTRIBUTE_ID_FILE attribute. Note that #GFile does some trivial
6422 * canonicalization of pathnames passed in, so that trivial differences in
6423 * the path string used at creation (duplicated slashes, slash at end of
6424 * path, "." or ".." path segments, etc) does not create different #GFiles.
6426 * Many #GFile operations have both synchronous and asynchronous versions
6427 * to suit your application. Asynchronous versions of synchronous functions
6428 * simply have _async() appended to their function names. The asynchronous
6429 * I/O functions call a #GAsyncReadyCallback which is then used to finalize
6430 * the operation, producing a GAsyncResult which is then passed to the
6431 * function's matching _finish() operation.
6433 * It is highly recommended to use asynchronous calls when running within a
6434 * shared main loop, such as in the main thread of an application. This avoids
6435 * I/O operations blocking other sources on the main loop from being dispatched.
6436 * Synchronous I/O operations should be performed from worker threads. See the
6437 * [introduction to asynchronous programming section][async-programming] for
6440 * Some #GFile operations almost always take a noticeable amount of time, and
6441 * so do not have synchronous analogs. Notable cases include:
6442 * - g_file_mount_mountable() to mount a mountable file.
6443 * - g_file_unmount_mountable_with_operation() to unmount a mountable file.
6444 * - g_file_eject_mountable_with_operation() to eject a mountable file.
6446 * ## Entity Tags # {#gfile-etag}
6448 * One notable feature of #GFiles are entity tags, or "etags" for
6449 * short. Entity tags are somewhat like a more abstract version of the
6450 * traditional mtime, and can be used to quickly determine if the file
6451 * has been modified from the version on the file system. See the
6453 * [specification](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html)
6454 * for HTTP Etag headers, which are a very similar concept.
6459 * SECTION:gfileattribute
6460 * @short_description: Key-Value Paired File Attributes
6461 * @include: gio/gio.h
6462 * @see_also: #GFile, #GFileInfo
6464 * File attributes in GIO consist of a list of key-value pairs.
6466 * Keys are strings that contain a key namespace and a key name, separated
6467 * by a colon, e.g. "namespace::keyname". Namespaces are included to sort
6468 * key-value pairs by namespaces for relevance. Keys can be retrieved
6469 * using wildcards, e.g. "standard::*" will return all of the keys in the
6470 * "standard" namespace.
6472 * The list of possible attributes for a filesystem (pointed to by a #GFile) is
6473 * available as a #GFileAttributeInfoList. This list is queryable by key names
6474 * as indicated earlier.
6476 * Information is stored within the list in #GFileAttributeInfo structures.
6477 * The info structure can store different types, listed in the enum
6478 * #GFileAttributeType. Upon creation of a #GFileAttributeInfo, the type will
6479 * be set to %G_FILE_ATTRIBUTE_TYPE_INVALID.
6481 * Classes that implement #GFileIface will create a #GFileAttributeInfoList and
6482 * install default keys and values for their given file system, architecture,
6483 * and other possible implementation details (e.g., on a UNIX system, a file
6484 * attribute key will be registered for the user id for a given file).
6486 * ## Default Namespaces
6488 * - `"standard"`: The "Standard" namespace. General file information that
6489 * any application may need should be put in this namespace. Examples
6490 * include the file's name, type, and size.
6491 * - `"etag`: The [Entity Tag][gfile-etag] namespace. Currently, the only key
6492 * in this namespace is "value", which contains the value of the current
6494 * - `"id"`: The "Identification" namespace. This namespace is used by file
6495 * managers and applications that list directories to check for loops and
6496 * to uniquely identify files.
6497 * - `"access"`: The "Access" namespace. Used to check if a user has the
6498 * proper privileges to access files and perform file operations. Keys in
6499 * this namespace are made to be generic and easily understood, e.g. the
6500 * "can_read" key is %TRUE if the current user has permission to read the
6501 * file. UNIX permissions and NTFS ACLs in Windows should be mapped to
6503 * - `"mountable"`: The "Mountable" namespace. Includes simple boolean keys
6504 * for checking if a file or path supports mount operations, e.g. mount,
6505 * unmount, eject. These are used for files of type %G_FILE_TYPE_MOUNTABLE.
6506 * - `"time"`: The "Time" namespace. Includes file access, changed, created
6508 * - `"unix"`: The "Unix" namespace. Includes UNIX-specific information and
6509 * may not be available for all files. Examples include the UNIX "UID",
6511 * - `"dos"`: The "DOS" namespace. Includes DOS-specific information and may
6512 * not be available for all files. Examples include "is_system" for checking
6513 * if a file is marked as a system file, and "is_archive" for checking if a
6514 * file is marked as an archive file.
6515 * - `"owner"`: The "Owner" namespace. Includes information about who owns a
6516 * file. May not be available for all file systems. Examples include "user"
6517 * for getting the user name of the file owner. This information is often
6518 * mapped from some backend specific data such as a UNIX UID.
6519 * - `"thumbnail"`: The "Thumbnail" namespace. Includes information about file
6520 * thumbnails and their location within the file system. Examples of keys in
6521 * this namespace include "path" to get the location of a thumbnail, "failed"
6522 * to check if thumbnailing of the file failed, and "is-valid" to check if
6523 * the thumbnail is outdated.
6524 * - `"filesystem"`: The "Filesystem" namespace. Gets information about the
6525 * file system where a file is located, such as its type, how much space is
6526 * left available, and the overall size of the file system.
6527 * - `"gvfs"`: The "GVFS" namespace. Keys in this namespace contain information
6528 * about the current GVFS backend in use.
6529 * - `"xattr"`: The "xattr" namespace. Gets information about extended
6530 * user attributes. See attr(5). The "user." prefix of the extended user
6531 * attribute name is stripped away when constructing keys in this namespace,
6532 * e.g. "xattr::mime_type" for the extended attribute with the name
6533 * "user.mime_type". Note that this information is only available if
6534 * GLib has been built with extended attribute support.
6535 * - `"xattr-sys"`: The "xattr-sys" namespace. Gets information about
6536 * extended attributes which are not user-specific. See attr(5). Note
6537 * that this information is only available if GLib has been built with
6538 * extended attribute support.
6539 * - `"selinux"`: The "SELinux" namespace. Includes information about the
6540 * SELinux context of files. Note that this information is only available
6541 * if GLib has been built with SELinux support.
6543 * Please note that these are not all of the possible namespaces.
6544 * More namespaces can be added from GIO modules or by individual applications.
6545 * For more information about writing GIO modules, see #GIOModule.
6547 * <!-- TODO: Implementation note about using extended attributes on supported
6552 * For a list of the built-in keys and their types, see the
6553 * [GFileInfo][GFileInfo] documentation.
6555 * Note that there are no predefined keys in the "xattr" and "xattr-sys"
6556 * namespaces. Keys for the "xattr" namespace are constructed by stripping
6557 * away the "user." prefix from the extended user attribute, and prepending
6558 * "xattr::". Keys for the "xattr-sys" namespace are constructed by
6559 * concatenating "xattr-sys::" with the extended attribute name. All extended
6560 * attribute values are returned as hex-encoded strings in which bytes outside
6561 * the ASCII range are encoded as escape sequences of the form \x`nn`
6562 * where `nn` is a 2-digit hexadecimal number.
6567 * SECTION:gfiledescriptorbased
6568 * @short_description: Interface for file descriptor based IO
6569 * @include: gio/gfiledescriptorbased.h
6570 * @see_also: #GInputStream, #GOutputStream
6572 * #GFileDescriptorBased is implemented by streams (implementations of
6573 * #GInputStream or #GOutputStream) that are based on file descriptors.
6575 * Note that `<gio/gfiledescriptorbased.h>` belongs to the UNIX-specific
6576 * GIO interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config
6577 * file when using it.
6584 * SECTION:gfileenumerator
6585 * @short_description: Enumerated Files Routines
6586 * @include: gio/gio.h
6588 * #GFileEnumerator allows you to operate on a set of #GFiles,
6589 * returning a #GFileInfo structure for each file enumerated (e.g.
6590 * g_file_enumerate_children() will return a #GFileEnumerator for each
6591 * of the children within a directory).
6593 * To get the next file's information from a #GFileEnumerator, use
6594 * g_file_enumerator_next_file() or its asynchronous version,
6595 * g_file_enumerator_next_files_async(). Note that the asynchronous
6596 * version will return a list of #GFileInfos, whereas the
6597 * synchronous will only return the next file in the enumerator.
6599 * The ordering of returned files is unspecified for non-Unix
6600 * platforms; for more information, see g_dir_read_name(). On Unix,
6601 * when operating on local files, returned files will be sorted by
6602 * inode number. Effectively you can assume that the ordering of
6603 * returned files will be stable between successive calls (and
6604 * applications) assuming the directory is unchanged.
6606 * If your application needs a specific ordering, such as by name or
6607 * modification time, you will have to implement that in your
6610 * To close a #GFileEnumerator, use g_file_enumerator_close(), or
6611 * its asynchronous version, g_file_enumerator_close_async(). Once
6612 * a #GFileEnumerator is closed, no further actions may be performed
6613 * on it, and it should be freed with g_object_unref().
6619 * @short_description: Icons pointing to an image file
6620 * @include: gio/gio.h
6621 * @see_also: #GIcon, #GLoadableIcon
6623 * #GFileIcon specifies an icon by pointing to an image file
6624 * to be used as icon.
6630 * @short_description: File Information and Attributes
6631 * @include: gio/gio.h
6632 * @see_also: #GFile, [GFileAttribute][gio-GFileAttribute]
6634 * Functionality for manipulating basic metadata for files. #GFileInfo
6635 * implements methods for getting information that all files should
6636 * contain, and allows for manipulation of extended attributes.
6638 * See [GFileAttribute][gio-GFileAttribute] for more information on how
6639 * GIO handles file attributes.
6641 * To obtain a #GFileInfo for a #GFile, use g_file_query_info() (or its
6642 * async variant). To obtain a #GFileInfo for a file input or output
6643 * stream, use g_file_input_stream_query_info() or
6644 * g_file_output_stream_query_info() (or their async variants).
6646 * To change the actual attributes of a file, you should then set the
6647 * attribute in the #GFileInfo and call g_file_set_attributes_from_info()
6648 * or g_file_set_attributes_async() on a GFile.
6650 * However, not all attributes can be changed in the file. For instance,
6651 * the actual size of a file cannot be changed via g_file_info_set_size().
6652 * You may call g_file_query_settable_attributes() and
6653 * g_file_query_writable_namespaces() to discover the settable attributes
6654 * of a particular file at runtime.
6656 * The direct accessors, such as g_file_info_get_name(), are slightly more
6657 * optimized than the generic attribute accessors, such as
6658 * g_file_info_get_attribute_byte_string().This optimization will matter
6659 * only if calling the API in a tight loop.
6661 * #GFileAttributeMatcher allows for searching through a #GFileInfo for
6667 * SECTION:gfileinputstream
6668 * @short_description: File input streaming operations
6669 * @include: gio/gio.h
6670 * @see_also: #GInputStream, #GDataInputStream, #GSeekable
6672 * GFileInputStream provides input streams that take their
6673 * content from a file.
6675 * GFileInputStream implements #GSeekable, which allows the input
6676 * stream to jump to arbitrary positions in the file, provided the
6677 * filesystem of the file allows it. To find the position of a file
6678 * input stream, use g_seekable_tell(). To find out if a file input
6679 * stream supports seeking, use g_seekable_can_seek().
6680 * To position a file input stream, use g_seekable_seek().
6685 * SECTION:gfileiostream
6686 * @short_description: File read and write streaming operations
6687 * @include: gio/gio.h
6688 * @see_also: #GIOStream, #GFileInputStream, #GFileOutputStream, #GSeekable
6690 * GFileIOStream provides io streams that both read and write to the same
6693 * GFileIOStream implements #GSeekable, which allows the io
6694 * stream to jump to arbitrary positions in the file and to truncate
6695 * the file, provided the filesystem of the file supports these
6698 * To find the position of a file io stream, use
6699 * g_seekable_tell().
6701 * To find out if a file io stream supports seeking, use g_seekable_can_seek().
6702 * To position a file io stream, use g_seekable_seek().
6703 * To find out if a file io stream supports truncating, use
6704 * g_seekable_can_truncate(). To truncate a file io
6705 * stream, use g_seekable_truncate().
6707 * The default implementation of all the #GFileIOStream operations
6708 * and the implementation of #GSeekable just call into the same operations
6709 * on the output stream.
6716 * SECTION:gfilemonitor
6717 * @short_description: File Monitor
6718 * @include: gio/gio.h
6720 * Monitors a file or directory for changes.
6722 * To obtain a #GFileMonitor for a file or directory, use
6723 * g_file_monitor(), g_file_monitor_file(), or
6724 * g_file_monitor_directory().
6726 * To get informed about changes to the file or directory you are
6727 * monitoring, connect to the #GFileMonitor::changed signal. The
6728 * signal will be emitted in the
6729 * [thread-default main context][g-main-context-push-thread-default]
6730 * of the thread that the monitor was created in
6731 * (though if the global default main context is blocked, this may
6732 * cause notifications to be blocked even if the thread-default
6733 * context is still running).
6738 * SECTION:gfilenamecompleter
6739 * @short_description: Filename Completer
6740 * @include: gio/gio.h
6742 * Completes partial file and directory names given a partial string by
6743 * looking in the file system for clues. Can return a list of possible
6744 * completion strings for widget implementations.
6749 * SECTION:gfileoutputstream
6750 * @short_description: File output streaming operations
6751 * @include: gio/gio.h
6752 * @see_also: #GOutputStream, #GDataOutputStream, #GSeekable
6754 * GFileOutputStream provides output streams that write their
6755 * content to a file.
6757 * GFileOutputStream implements #GSeekable, which allows the output
6758 * stream to jump to arbitrary positions in the file and to truncate
6759 * the file, provided the filesystem of the file supports these
6762 * To find the position of a file output stream, use g_seekable_tell().
6763 * To find out if a file output stream supports seeking, use
6764 * g_seekable_can_seek().To position a file output stream, use
6765 * g_seekable_seek(). To find out if a file output stream supports
6766 * truncating, use g_seekable_can_truncate(). To truncate a file output
6767 * stream, use g_seekable_truncate().
6772 * SECTION:gfilterinputstream
6773 * @short_description: Filter Input Stream
6774 * @include: gio/gio.h
6776 * Base class for input stream implementations that perform some
6777 * kind of filtering operation on a base stream. Typical examples
6778 * of filtering operations are character set conversion, compression
6779 * and byte order flipping.
6784 * SECTION:gfilteroutputstream
6785 * @short_description: Filter Output Stream
6786 * @include: gio/gio.h
6788 * Base class for output stream implementations that perform some
6789 * kind of filtering operation on a base stream. Typical examples
6790 * of filtering operations are character set conversion, compression
6791 * and byte order flipping.
6797 * @short_description: Interface for icons
6798 * @include: gio/gio.h
6800 * #GIcon is a very minimal interface for icons. It provides functions
6801 * for checking the equality of two icons, hashing of icons and
6802 * serializing an icon to and from strings.
6804 * #GIcon does not provide the actual pixmap for the icon as this is out
6805 * of GIO's scope, however implementations of #GIcon may contain the name
6806 * of an icon (see #GThemedIcon), or the path to an icon (see #GLoadableIcon).
6808 * To obtain a hash of a #GIcon, see g_icon_hash().
6810 * To check if two #GIcons are equal, see g_icon_equal().
6812 * For serializing a #GIcon, use g_icon_serialize() and
6813 * g_icon_deserialize().
6815 * If you want to consume #GIcon (for example, in a toolkit) you must
6816 * be prepared to handle at least the three following cases:
6817 * #GLoadableIcon, #GThemedIcon and #GEmblemedIcon. It may also make
6818 * sense to have fast-paths for other cases (like handling #GdkPixbuf
6819 * directly, for example) but all compliant #GIcon implementations
6820 * outside of GIO must implement #GLoadableIcon.
6822 * If your application or library provides one or more #GIcon
6823 * implementations you need to ensure that your new implementation also
6824 * implements #GLoadableIcon. Additionally, you must provide an
6825 * implementation of g_icon_serialize() that gives a result that is
6826 * understood by g_icon_deserialize(), yielding one of the built-in icon
6832 * SECTION:ginetaddress
6833 * @short_description: An IPv4/IPv6 address
6834 * @include: gio/gio.h
6836 * #GInetAddress represents an IPv4 or IPv6 internet address. Use
6837 * g_resolver_lookup_by_name() or g_resolver_lookup_by_name_async() to
6838 * look up the #GInetAddress for a hostname. Use
6839 * g_resolver_lookup_by_address() or
6840 * g_resolver_lookup_by_address_async() to look up the hostname for a
6843 * To actually connect to a remote host, you will need a
6844 * #GInetSocketAddress (which includes a #GInetAddress as well as a
6850 * SECTION:ginetaddressmask
6851 * @short_description: An IPv4/IPv6 address mask
6852 * @include: gio/gio.h
6854 * #GInetAddressMask represents a range of IPv4 or IPv6 addresses
6855 * described by a base address and a length indicating how many bits
6856 * of the base address are relevant for matching purposes. These are
6857 * often given in string form. Eg, "10.0.0.0/8", or "fe80::/10".
6862 * SECTION:ginetsocketaddress
6863 * @short_description: Internet GSocketAddress
6864 * @include: gio/gio.h
6866 * An IPv4 or IPv6 socket address; that is, the combination of a
6867 * #GInetAddress and a port number.
6873 * @short_description: Failable object initialization interface
6874 * @include: gio/gio.h
6875 * @see_also: #GAsyncInitable
6877 * #GInitable is implemented by objects that can fail during
6878 * initialization. If an object implements this interface then
6879 * it must be initialized as the first thing after construction,
6880 * either via g_initable_init() or g_async_initable_init_async()
6881 * (the latter is only available if it also implements #GAsyncInitable).
6883 * If the object is not initialized, or initialization returns with an
6884 * error, then all operations on the object except g_object_ref() and
6885 * g_object_unref() are considered to be invalid, and have undefined
6886 * behaviour. They will often fail with g_critical() or g_warning(), but
6887 * this must not be relied on.
6889 * Users of objects implementing this are not intended to use
6890 * the interface method directly, instead it will be used automatically
6891 * in various ways. For C applications you generally just call
6892 * g_initable_new() directly, or indirectly via a foo_thing_new() wrapper.
6893 * This will call g_initable_init() under the cover, returning %NULL and
6894 * setting a #GError on failure (at which point the instance is
6897 * For bindings in languages where the native constructor supports
6898 * exceptions the binding could check for objects implementing %GInitable
6899 * during normal construction and automatically initialize them, throwing
6900 * an exception on failure.
6905 * SECTION:ginputstream
6906 * @short_description: Base class for implementing streaming input
6907 * @include: gio/gio.h
6909 * #GInputStream has functions to read from a stream (g_input_stream_read()),
6910 * to close a stream (g_input_stream_close()) and to skip some content
6911 * (g_input_stream_skip()).
6913 * To copy the content of an input stream to an output stream without
6914 * manually handling the reads and writes, use g_output_stream_splice().
6916 * See the documentation for #GIOStream for details of thread safety of
6919 * All of these functions have async variants too.
6925 * @short_description: Error helper functions
6926 * @include: gio/gio.h
6928 * Contains helper functions for reporting errors to the user.
6934 * @short_description: Loadable GIO Modules
6935 * @include: gio/gio.h
6937 * Provides an interface and default functions for loading and unloading
6938 * modules. This is used internally to make GIO extensible, but can also
6939 * be used by others to implement module loading.
6944 * SECTION:gioscheduler
6945 * @short_description: I/O Scheduler
6946 * @include: gio/gio.h
6948 * As of GLib 2.36, #GIOScheduler is deprecated in favor of
6949 * #GThreadPool and #GTask.
6951 * Schedules asynchronous I/O operations. #GIOScheduler integrates
6952 * into the main event loop (#GMainLoop) and uses threads.
6958 * @short_description: Base class for implementing read/write streams
6959 * @include: gio/gio.h
6960 * @see_also: #GInputStream, #GOutputStream
6962 * GIOStream represents an object that has both read and write streams.
6963 * Generally the two streams act as separate input and output streams,
6964 * but they share some common resources and state. For instance, for
6965 * seekable streams, both streams may use the same position.
6967 * Examples of #GIOStream objects are #GSocketConnection, which represents
6968 * a two-way network connection; and #GFileIOStream, which represents a
6969 * file handle opened in read-write mode.
6971 * To do the actual reading and writing you need to get the substreams
6972 * with g_io_stream_get_input_stream() and g_io_stream_get_output_stream().
6974 * The #GIOStream object owns the input and the output streams, not the other
6975 * way around, so keeping the substreams alive will not keep the #GIOStream
6976 * object alive. If the #GIOStream object is freed it will be closed, thus
6977 * closing the substreams, so even if the substreams stay alive they will
6978 * always return %G_IO_ERROR_CLOSED for all operations.
6980 * To close a stream use g_io_stream_close() which will close the common
6981 * stream object and also the individual substreams. You can also close
6982 * the substreams themselves. In most cases this only marks the
6983 * substream as closed, so further I/O on it fails but common state in the
6984 * #GIOStream may still be open. However, some streams may support
6985 * "half-closed" states where one direction of the stream is actually shut down.
6987 * Operations on #GIOStreams cannot be started while another operation on the
6988 * #GIOStream or its substreams is in progress. Specifically, an application can
6989 * read from the #GInputStream and write to the #GOutputStream simultaneously
6990 * (either in separate threads, or as asynchronous operations in the same
6991 * thread), but an application cannot start any #GIOStream operation while there
6992 * is a #GIOStream, #GInputStream or #GOutputStream operation in progress, and
6993 * an application can’t start any #GInputStream or #GOutputStream operation
6994 * while there is a #GIOStream operation in progress.
6996 * This is a product of individual stream operations being associated with a
6997 * given #GMainContext (the thread-default context at the time the operation was
6998 * started), rather than entire streams being associated with a single
7001 * GIO may run operations on #GIOStreams from other (worker) threads, and this
7002 * may be exposed to application code in the behaviour of wrapper streams, such
7003 * as #GBufferedInputStream or #GTlsConnection. With such wrapper APIs,
7004 * application code may only run operations on the base (wrapped) stream when
7005 * the wrapper stream is idle. Note that the semantics of such operations may
7006 * not be well-defined due to the state the wrapper stream leaves the base
7007 * stream in (though they are guaranteed not to crash).
7014 * SECTION:glistmodel
7015 * @title: GListModel
7016 * @short_description: An interface describing a dynamic list of objects
7017 * @include: gio/gio.h
7018 * @see_also: #GListStore
7020 * #GListModel is an interface that represents a mutable list of
7021 * #GObjects. Its main intention is as a model for various widgets in
7022 * user interfaces, such as list views, but it can also be used as a
7023 * convenient method of returning lists of data, with support for
7026 * Each object in the list may also report changes in itself via some
7027 * mechanism (normally the #GObject::notify signal). Taken together
7028 * with the #GListModel::items-changed signal, this provides for a list
7029 * that can change its membership, and in which the members can change
7030 * their individual properties.
7032 * A good example would be the list of visible wireless network access
7033 * points, where each access point can report dynamic properties such as
7036 * It is important to note that the #GListModel itself does not report
7037 * changes to the individual items. It only reports changes to the list
7038 * membership. If you want to observe changes to the objects themselves
7039 * then you need to connect signals to the objects that you are
7042 * All items in a #GListModel are of (or derived from) the same type.
7043 * g_list_model_get_item_type() returns that type. The type may be an
7044 * interface, in which case all objects in the list must implement it.
7046 * The semantics are close to that of an array:
7047 * g_list_model_get_n_items() returns the number of items in the list and
7048 * g_list_model_get_item() returns an item at a (0-based) position. In
7049 * order to allow implementations to calculate the list length lazily,
7050 * you can also iterate over items: starting from 0, repeatedly call
7051 * g_list_model_get_item() until it returns %NULL.
7053 * An implementation may create objects lazily, but must take care to
7054 * return the same object for a given position until all references to
7057 * On the other side, a consumer is expected only to hold references on
7058 * objects that are currently "user visible", in order to facilitate the
7059 * maximum level of laziness in the implementation of the list and to
7060 * reduce the required number of signal connections at a given time.
7062 * This interface is intended only to be used from a single thread. The
7063 * thread in which it is appropriate to use it depends on the particular
7064 * implementation, but typically it will be from the thread that owns
7065 * the [thread-default main context][g-main-context-push-thread-default]
7066 * in effect at the time that the model was created.
7071 * SECTION:gliststore
7072 * @title: GListStore
7073 * @short_description: A simple implementation of #GListModel
7074 * @include: gio/gio.h
7076 * #GListStore is a simple implementation of #GListModel that stores all
7079 * It provides insertions, deletions, and lookups in logarithmic time
7080 * with a fast path for the common case of iterating the list linearly.
7085 * SECTION:gloadableicon
7086 * @short_description: Loadable Icons
7087 * @include: gio/gio.h
7088 * @see_also: #GIcon, #GThemedIcon
7090 * Extends the #GIcon interface and adds the ability to
7091 * load icons from streams.
7096 * SECTION:gmemoryinputstream
7097 * @short_description: Streaming input operations on memory chunks
7098 * @include: gio/gio.h
7099 * @see_also: #GMemoryOutputStream
7101 * #GMemoryInputStream is a class for using arbitrary
7102 * memory chunks as input for GIO streaming input operations.
7104 * As of GLib 2.34, #GMemoryInputStream implements
7105 * #GPollableInputStream.
7110 * SECTION:gmemorymonitor
7111 * @title: GMemoryMonitor
7112 * @short_description: Memory usage monitor
7113 * @include: gio/gio.h
7115 * #GMemoryMonitor will monitor system memory and suggest to the application
7116 * when to free memory so as to leave more room for other applications.
7117 * It is implemented on Linux using the [Low Memory Monitor](https://gitlab.freedesktop.org/hadess/low-memory-monitor/)
7118 * ([API documentation](https://hadess.pages.freedesktop.org/low-memory-monitor/)).
7120 * There is also an implementation for use inside Flatpak sandboxes.
7122 * Possible actions to take when the signal is received are:
7125 * - Save files that haven't been looked at in a while to disk, ready to be reopened when needed
7126 * - Run a garbage collection cycle
7127 * - Try and compress fragmented allocations
7128 * - Exit on idle if the process has no reason to stay around
7129 * - Call [`malloc_trim(3)`](man:malloc_trim) to return cached heap pages to
7130 * the kernel (if supported by your libc)
7132 * Note that some actions may not always improve system performance, and so
7133 * should be profiled for your application. `malloc_trim()`, for example, may
7134 * make future heap allocations slower (due to releasing cached heap pages back
7137 * See #GMemoryMonitorWarningLevel for details on the various warning levels.
7139 * |[<!-- language="C" -->
7141 * warning_cb (GMemoryMonitor *m, GMemoryMonitorWarningLevel level)
7143 * g_debug ("Warning level: %d", level);
7144 * if (warning_level > G_MEMORY_MONITOR_WARNING_LEVEL_LOW)
7148 * static GMemoryMonitor *
7149 * monitor_low_memory (void)
7151 * GMemoryMonitor *m;
7152 * m = g_memory_monitor_dup_default ();
7153 * g_signal_connect (G_OBJECT (m), "low-memory-warning",
7154 * G_CALLBACK (warning_cb), NULL);
7159 * Don't forget to disconnect the #GMemoryMonitor::low-memory-warning
7160 * signal, and unref the #GMemoryMonitor itself when exiting.
7167 * SECTION:gmemoryoutputstream
7168 * @short_description: Streaming output operations on memory chunks
7169 * @include: gio/gio.h
7170 * @see_also: #GMemoryInputStream
7172 * #GMemoryOutputStream is a class for using arbitrary
7173 * memory chunks as output for GIO streaming output operations.
7175 * As of GLib 2.34, #GMemoryOutputStream trivially implements
7176 * #GPollableOutputStream: it always polls as ready.
7183 * @short_description: A simple implementation of GMenuModel
7184 * @include: gio/gio.h
7186 * #GMenu is a simple implementation of #GMenuModel.
7187 * You populate a #GMenu by adding #GMenuItem instances to it.
7189 * There are some convenience functions to allow you to directly
7190 * add items (avoiding #GMenuItem) for the common cases. To add
7191 * a regular item, use g_menu_insert(). To add a section, use
7192 * g_menu_insert_section(). To add a submenu, use
7193 * g_menu_insert_submenu().
7198 * SECTION:gmenuexporter
7199 * @title: GMenuModel exporter
7200 * @short_description: Export GMenuModels on D-Bus
7201 * @include: gio/gio.h
7202 * @see_also: #GMenuModel, #GDBusMenuModel
7204 * These functions support exporting a #GMenuModel on D-Bus.
7205 * The D-Bus interface that is used is a private implementation
7208 * To access an exported #GMenuModel remotely, use
7209 * g_dbus_menu_model_get() to obtain a #GDBusMenuModel.
7214 * SECTION:gmenumodel
7215 * @title: GMenuModel
7216 * @short_description: An abstract class representing the contents of a menu
7217 * @include: gio/gio.h
7218 * @see_also: #GActionGroup
7220 * #GMenuModel represents the contents of a menu -- an ordered list of
7221 * menu items. The items are associated with actions, which can be
7222 * activated through them. Items can be grouped in sections, and may
7223 * have submenus associated with them. Both items and sections usually
7224 * have some representation data, such as labels or icons. The type of
7225 * the associated action (ie whether it is stateful, and what kind of
7226 * state it has) can influence the representation of the item.
7228 * The conceptual model of menus in #GMenuModel is hierarchical:
7229 * sections and submenus are again represented by #GMenuModels.
7230 * Menus themselves do not define their own roles. Rather, the role
7231 * of a particular #GMenuModel is defined by the item that references
7232 * it (or, in the case of the 'root' menu, is defined by the context
7233 * in which it is used).
7235 * As an example, consider the visible portions of this menu:
7237 * ## An example menu # {#menu-example}
7239 * ![](menu-example.png)
7241 * There are 8 "menus" visible in the screenshot: one menubar, two
7242 * submenus and 5 sections:
7244 * - the toplevel menubar (containing 4 items)
7245 * - the View submenu (containing 3 sections)
7246 * - the first section of the View submenu (containing 2 items)
7247 * - the second section of the View submenu (containing 1 item)
7248 * - the final section of the View submenu (containing 1 item)
7249 * - the Highlight Mode submenu (containing 2 sections)
7250 * - the Sources section (containing 2 items)
7251 * - the Markup section (containing 2 items)
7253 * The [example][menu-model] illustrates the conceptual connection between
7254 * these 8 menus. Each large block in the figure represents a menu and the
7255 * smaller blocks within the large block represent items in that menu. Some
7256 * items contain references to other menus.
7258 * ## A menu example # {#menu-model}
7260 * ![](menu-model.png)
7262 * Notice that the separators visible in the [example][menu-example]
7263 * appear nowhere in the [menu model][menu-model]. This is because
7264 * separators are not explicitly represented in the menu model. Instead,
7265 * a separator is inserted between any two non-empty sections of a menu.
7266 * Section items can have labels just like any other item. In that case,
7267 * a display system may show a section header instead of a separator.
7269 * The motivation for this abstract model of application controls is
7270 * that modern user interfaces tend to make these controls available
7271 * outside the application. Examples include global menus, jumplists,
7272 * dash boards, etc. To support such uses, it is necessary to 'export'
7273 * information about actions and their representation in menus, which
7274 * is exactly what the [GActionGroup exporter][gio-GActionGroup-exporter]
7275 * and the [GMenuModel exporter][gio-GMenuModel-exporter] do for
7276 * #GActionGroup and #GMenuModel. The client-side counterparts to
7277 * make use of the exported information are #GDBusActionGroup and
7280 * The API of #GMenuModel is very generic, with iterators for the
7281 * attributes and links of an item, see g_menu_model_iterate_item_attributes()
7282 * and g_menu_model_iterate_item_links(). The 'standard' attributes and
7283 * link types have predefined names: %G_MENU_ATTRIBUTE_LABEL,
7284 * %G_MENU_ATTRIBUTE_ACTION, %G_MENU_ATTRIBUTE_TARGET, %G_MENU_LINK_SECTION
7285 * and %G_MENU_LINK_SUBMENU.
7287 * Items in a #GMenuModel represent active controls if they refer to
7288 * an action that can get activated when the user interacts with the
7289 * menu item. The reference to the action is encoded by the string id
7290 * in the %G_MENU_ATTRIBUTE_ACTION attribute. An action id uniquely
7291 * identifies an action in an action group. Which action group(s) provide
7292 * actions depends on the context in which the menu model is used.
7293 * E.g. when the model is exported as the application menu of a
7294 * #GtkApplication, actions can be application-wide or window-specific
7295 * (and thus come from two different action groups). By convention, the
7296 * application-wide actions have names that start with "app.", while the
7297 * names of window-specific actions start with "win.".
7299 * While a wide variety of stateful actions is possible, the following
7300 * is the minimum that is expected to be supported by all users of exported
7302 * - an action with no parameter type and no state
7303 * - an action with no parameter type and boolean state
7304 * - an action with string parameter type and string state
7308 * A stateless action typically corresponds to an ordinary menu item.
7310 * Selecting such a menu item will activate the action (with no parameter).
7314 * An action with a boolean state will most typically be used with a "toggle"
7315 * or "switch" menu item. The state can be set directly, but activating the
7316 * action (with no parameter) results in the state being toggled.
7318 * Selecting a toggle menu item will activate the action. The menu item should
7319 * be rendered as "checked" when the state is true.
7321 * ## String Parameter and State
7323 * Actions with string parameters and state will most typically be used to
7324 * represent an enumerated choice over the items available for a group of
7325 * radio menu items. Activating the action with a string parameter is
7326 * equivalent to setting that parameter as the state.
7328 * Radio menu items, in addition to being associated with the action, will
7329 * have a target value. Selecting that menu item will result in activation
7330 * of the action with the target value as the parameter. The menu item should
7331 * be rendered as "selected" when the state of the action is equal to the
7332 * target value of the menu item.
7338 * @short_description: Mount management
7339 * @include: gio/gio.h
7340 * @see_also: GVolume, GUnixMountEntry, GUnixMountPoint
7342 * The #GMount interface represents user-visible mounts. Note, when
7343 * porting from GnomeVFS, #GMount is the moral equivalent of #GnomeVFSVolume.
7345 * #GMount is a "mounted" filesystem that you can access. Mounted is in
7346 * quotes because it's not the same as a unix mount, it might be a gvfs
7347 * mount, but you can still access the files on it if you use GIO. Might or
7348 * might not be related to a volume object.
7350 * Unmounting a #GMount instance is an asynchronous operation. For
7351 * more information about asynchronous operations, see #GAsyncResult
7352 * and #GTask. To unmount a #GMount instance, first call
7353 * g_mount_unmount_with_operation() with (at least) the #GMount instance and a
7354 * #GAsyncReadyCallback. The callback will be fired when the
7355 * operation has resolved (either with success or failure), and a
7356 * #GAsyncResult structure will be passed to the callback. That
7357 * callback should then call g_mount_unmount_with_operation_finish() with the #GMount
7358 * and the #GAsyncResult data to see if the operation was completed
7359 * successfully. If an @error is present when g_mount_unmount_with_operation_finish()
7360 * is called, then it will be filled with any error information.
7365 * SECTION:gmountoperation
7366 * @short_description: Object used for authentication and user interaction
7367 * @include: gio/gio.h
7369 * #GMountOperation provides a mechanism for interacting with the user.
7370 * It can be used for authenticating mountable operations, such as loop
7371 * mounting files, hard drive partitions or server locations. It can
7372 * also be used to ask the user questions or show a list of applications
7373 * preventing unmount or eject operations from completing.
7375 * Note that #GMountOperation is used for more than just #GMount
7376 * objects – for example it is also used in g_drive_start() and
7379 * Users should instantiate a subclass of this that implements all the
7380 * various callbacks to show the required dialogs, such as
7381 * #GtkMountOperation. If no user interaction is desired (for example
7382 * when automounting filesystems at login time), usually %NULL can be
7383 * passed, see each method taking a #GMountOperation for details.
7385 * The term ‘TCRYPT’ is used to mean ‘compatible with TrueCrypt and VeraCrypt’.
7386 * [TrueCrypt](https://en.wikipedia.org/wiki/TrueCrypt) is a discontinued system for
7387 * encrypting file containers, partitions or whole disks, typically used with Windows.
7388 * [VeraCrypt](https://www.veracrypt.fr/) is a maintained fork of TrueCrypt with various
7389 * improvements and auditing fixes.
7394 * SECTION:gnativesocketaddress
7395 * @short_description: Native GSocketAddress
7396 * @include: gio/gio.h
7398 * A socket address of some unknown native type.
7403 * SECTION:gnetworkaddress
7404 * @short_description: A GSocketConnectable for resolving hostnames
7405 * @include: gio/gio.h
7407 * #GNetworkAddress provides an easy way to resolve a hostname and
7408 * then attempt to connect to that host, handling the possibility of
7409 * multiple IP addresses and multiple address families.
7411 * The enumeration results of resolved addresses *may* be cached as long
7412 * as this object is kept alive which may have unexpected results if
7413 * alive for too long.
7415 * See #GSocketConnectable for an example of using the connectable
7421 * SECTION:gnetworking
7422 * @title: gnetworking.h
7423 * @short_description: System networking includes
7424 * @include: gio/gnetworking.h
7426 * The `<gio/gnetworking.h>` header can be included to get
7427 * various low-level networking-related system headers, automatically
7428 * taking care of certain portability issues for you.
7430 * This can be used, for example, if you want to call setsockopt()
7433 * Note that while WinSock has many of the same APIs as the
7434 * traditional UNIX socket API, most of them behave at least slightly
7435 * differently (particularly with respect to error handling). If you
7436 * want your code to work under both UNIX and Windows, you will need
7437 * to take these differences into account.
7439 * Also, under GNU libc, certain non-portable functions are only visible
7440 * in the headers if you define %_GNU_SOURCE before including them. Note
7441 * that this symbol must be defined before including any headers, or it
7442 * may not take effect.
7447 * SECTION:gnetworkmonitor
7448 * @title: GNetworkMonitor
7449 * @short_description: Network status monitor
7450 * @include: gio/gio.h
7452 * #GNetworkMonitor provides an easy-to-use cross-platform API
7453 * for monitoring network connectivity. On Linux, the available
7454 * implementations are based on the kernel's netlink interface and
7455 * on NetworkManager.
7457 * There is also an implementation for use inside Flatpak sandboxes.
7462 * SECTION:gnetworkservice
7463 * @short_description: A GSocketConnectable for resolving SRV records
7464 * @include: gio/gio.h
7466 * Like #GNetworkAddress does with hostnames, #GNetworkService
7467 * provides an easy way to resolve a SRV record, and then attempt to
7468 * connect to one of the hosts that implements that service, handling
7469 * service priority/weighting, multiple IP addresses, and multiple
7472 * See #GSrvTarget for more information about SRV records, and see
7473 * #GSocketConnectable for an example of using the connectable
7479 * SECTION:gnotification
7480 * @short_description: User Notifications (pop up messages)
7481 * @include: gio/gio.h
7483 * #GNotification is a mechanism for creating a notification to be shown
7484 * to the user -- typically as a pop-up notification presented by the
7485 * desktop environment shell.
7487 * The key difference between #GNotification and other similar APIs is
7488 * that, if supported by the desktop environment, notifications sent
7489 * with #GNotification will persist after the application has exited,
7490 * and even across system reboots.
7492 * Since the user may click on a notification while the application is
7493 * not running, applications using #GNotification should be able to be
7494 * started as a D-Bus service, using #GApplication.
7496 * In order for #GNotification to work, the application must have installed
7497 * a `.desktop` file. For example:
7500 * Name=Test Application
7501 * Comment=Description of what Test Application does
7502 * Exec=gnome-test-application
7503 * Icon=org.gnome.TestApplication
7506 * Categories=GNOME;GTK;TestApplication Category;
7507 * StartupNotify=true
7508 * DBusActivatable=true
7509 * X-GNOME-UsesNotifications=true
7512 * The `X-GNOME-UsesNotifications` key indicates to GNOME Control Center
7513 * that this application uses notifications, so it can be listed in the
7514 * Control Center’s ‘Notifications’ panel.
7516 * The `.desktop` file must be named as `org.gnome.TestApplication.desktop`,
7517 * where `org.gnome.TestApplication` is the ID passed to g_application_new().
7519 * User interaction with a notification (either the default action, or
7520 * buttons) must be associated with actions on the application (ie:
7521 * "app." actions). It is not possible to route user interaction
7522 * through the notification itself, because the object will not exist if
7523 * the application is autostarted as a result of a notification being
7526 * A notification can be sent with g_application_send_notification().
7533 * SECTION:goutputstream
7534 * @short_description: Base class for implementing streaming output
7535 * @include: gio/gio.h
7537 * #GOutputStream has functions to write to a stream (g_output_stream_write()),
7538 * to close a stream (g_output_stream_close()) and to flush pending writes
7539 * (g_output_stream_flush()).
7541 * To copy the content of an input stream to an output stream without
7542 * manually handling the reads and writes, use g_output_stream_splice().
7544 * See the documentation for #GIOStream for details of thread safety of
7547 * All of these functions have async variants too.
7552 * SECTION:gpermission
7553 * @title: GPermission
7554 * @short_description: An object representing the permission
7555 * to perform a certain action
7556 * @include: gio/gio.h
7558 * A #GPermission represents the status of the caller's permission to
7559 * perform a certain action.
7561 * You can query if the action is currently allowed and if it is
7562 * possible to acquire the permission so that the action will be allowed
7565 * There is also an API to actually acquire the permission and one to
7568 * As an example, a #GPermission might represent the ability for the
7569 * user to write to a #GSettings object. This #GPermission object could
7570 * then be used to decide if it is appropriate to show a "Click here to
7571 * unlock" button in a dialog and to provide the mechanism to invoke
7572 * when that button is clicked.
7577 * SECTION:gpollableinputstream
7578 * @short_description: Interface for pollable input streams
7579 * @include: gio/gio.h
7580 * @see_also: #GInputStream, #GPollableOutputStream, #GFileDescriptorBased
7582 * #GPollableInputStream is implemented by #GInputStreams that
7583 * can be polled for readiness to read. This can be used when
7584 * interfacing with a non-GIO API that expects
7585 * UNIX-file-descriptor-style asynchronous I/O rather than GIO-style.
7592 * SECTION:gpollableoutputstream
7593 * @short_description: Interface for pollable output streams
7594 * @include: gio/gio.h
7595 * @see_also: #GOutputStream, #GFileDescriptorBased, #GPollableInputStream
7597 * #GPollableOutputStream is implemented by #GOutputStreams that
7598 * can be polled for readiness to write. This can be used when
7599 * interfacing with a non-GIO API that expects
7600 * UNIX-file-descriptor-style asynchronous I/O rather than GIO-style.
7607 * SECTION:gpollableutils
7608 * @short_description: Utilities for pollable streams
7609 * @include: gio/gio.h
7611 * Utility functions for #GPollableInputStream and
7612 * #GPollableOutputStream implementations.
7617 * SECTION:gpowerprofilemonitor
7618 * @title: GPowerProfileMonitor
7619 * @short_description: Power profile monitor
7620 * @include: gio/gio.h
7622 * #GPowerProfileMonitor makes it possible for applications as well as OS components
7623 * to monitor system power profiles and act upon them. It currently only exports
7624 * whether the system is in “Power Saver” mode (known as “Low Power” mode on
7627 * When in “Low Power” mode, it is recommended that applications:
7628 * - disabling automatic downloads
7629 * - reduce the rate of refresh from online sources such as calendar or
7630 * email synchronisation
7631 * - if the application has expensive visual effects, reduce them
7633 * It is also likely that OS components providing services to applications will
7634 * lower their own background activity, for the sake of the system.
7636 * There are a variety of tools that exist for power consumption analysis, but those
7637 * usually depend on the OS and hardware used. On Linux, one could use `upower` to
7638 * monitor the battery discharge rate, `powertop` to check on the background activity
7639 * or activity at all), `sysprof` to inspect CPU usage, and `intel_gpu_time` to
7640 * profile GPU usage.
7642 * Don't forget to disconnect the #GPowerProfileMonitor::notify::power-saver-enabled
7643 * signal, and unref the #GPowerProfileMonitor itself when exiting.
7650 * SECTION:gpropertyaction
7651 * @title: GPropertyAction
7652 * @short_description: A GAction reflecting a GObject property
7653 * @include: gio/gio.h
7655 * A #GPropertyAction is a way to get a #GAction with a state value
7656 * reflecting and controlling the value of a #GObject property.
7658 * The state of the action will correspond to the value of the property.
7659 * Changing it will change the property (assuming the requested value
7660 * matches the requirements as specified in the #GParamSpec).
7662 * Only the most common types are presently supported. Booleans are
7663 * mapped to booleans, strings to strings, signed/unsigned integers to
7664 * int32/uint32 and floats and doubles to doubles.
7666 * If the property is an enum then the state will be string-typed and
7667 * conversion will automatically be performed between the enum value and
7668 * "nick" string as per the #GEnumValue table.
7670 * Flags types are not currently supported.
7672 * Properties of object types, boxed types and pointer types are not
7673 * supported and probably never will be.
7675 * Properties of #GVariant types are not currently supported.
7677 * If the property is boolean-valued then the action will have a NULL
7678 * parameter type, and activating the action (with no parameter) will
7679 * toggle the value of the property.
7681 * In all other cases, the parameter type will correspond to the type of
7684 * The general idea here is to reduce the number of locations where a
7685 * particular piece of state is kept (and therefore has to be synchronised
7686 * between). #GPropertyAction does not have a separate state that is kept
7687 * in sync with the property value -- its state is the property value.
7689 * For example, it might be useful to create a #GAction corresponding to
7690 * the "visible-child-name" property of a #GtkStack so that the current
7691 * page can be switched from a menu. The active radio indication in the
7692 * menu is then directly determined from the active page of the
7695 * An anti-example would be binding the "active-id" property on a
7696 * #GtkComboBox. This is because the state of the combobox itself is
7697 * probably uninteresting and is actually being used to control
7700 * Another anti-example would be to bind to the "visible-child-name"
7701 * property of a #GtkStack if this value is actually stored in
7702 * #GSettings. In that case, the real source of the value is
7703 * #GSettings. If you want a #GAction to control a setting stored in
7704 * #GSettings, see g_settings_create_action() instead, and possibly
7705 * combine its use with g_settings_bind().
7713 * @short_description: Interface for proxy handling
7714 * @include: gio/gio.h
7716 * A #GProxy handles connecting to a remote host via a given type of
7717 * proxy server. It is implemented by the 'gio-proxy' extension point.
7718 * The extensions are named after their proxy protocol name. As an
7719 * example, a SOCKS5 proxy implementation can be retrieved with the
7720 * name 'socks5' using the function
7721 * g_io_extension_point_get_extension_by_name().
7728 * SECTION:gproxyaddress
7729 * @short_description: An internet address with proxy information
7730 * @include: gio/gio.h
7732 * Support for proxied #GInetSocketAddress.
7737 * SECTION:gproxyaddressenumerator
7738 * @short_description: Proxy wrapper enumerator for socket addresses
7739 * @include: gio/gio.h
7741 * #GProxyAddressEnumerator is a wrapper around #GSocketAddressEnumerator which
7742 * takes the #GSocketAddress instances returned by the #GSocketAddressEnumerator
7743 * and wraps them in #GProxyAddress instances, using the given
7744 * #GProxyAddressEnumerator:proxy-resolver.
7746 * This enumerator will be returned (for example, by
7747 * g_socket_connectable_enumerate()) as appropriate when a proxy is configured;
7748 * there should be no need to manually wrap a #GSocketAddressEnumerator instance
7754 * SECTION:gproxyresolver
7755 * @short_description: Asynchronous and cancellable network proxy resolver
7756 * @include: gio/gio.h
7758 * #GProxyResolver provides synchronous and asynchronous network proxy
7759 * resolution. #GProxyResolver is used within #GSocketClient through
7760 * the method g_socket_connectable_proxy_enumerate().
7762 * Implementations of #GProxyResolver based on libproxy and GNOME settings can
7763 * be found in glib-networking. GIO comes with an implementation for use inside
7769 * SECTION:gremoteactiongroup
7770 * @title: GRemoteActionGroup
7771 * @short_description: A GActionGroup that interacts with other processes
7772 * @include: gio/gio.h
7774 * The GRemoteActionGroup interface is implemented by #GActionGroup
7775 * instances that either transmit action invocations to other processes
7776 * or receive action invocations in the local process from other
7779 * The interface has `_full` variants of the two
7780 * methods on #GActionGroup used to activate actions:
7781 * g_action_group_activate_action() and
7782 * g_action_group_change_action_state(). These variants allow a
7783 * "platform data" #GVariant to be specified: a dictionary providing
7784 * context for the action invocation (for example: timestamps, startup
7785 * notification IDs, etc).
7787 * #GDBusActionGroup implements #GRemoteActionGroup. This provides a
7788 * mechanism to send platform data for action invocations over D-Bus.
7790 * Additionally, g_dbus_connection_export_action_group() will check if
7791 * the exported #GActionGroup implements #GRemoteActionGroup and use the
7792 * `_full` variants of the calls if available. This
7793 * provides a mechanism by which to receive platform data for action
7794 * invocations that arrive by way of D-Bus.
7802 * @short_description: Asynchronous and cancellable DNS resolver
7803 * @include: gio/gio.h
7805 * #GResolver provides cancellable synchronous and asynchronous DNS
7806 * resolution, for hostnames (g_resolver_lookup_by_address(),
7807 * g_resolver_lookup_by_name() and their async variants) and SRV
7808 * (service) records (g_resolver_lookup_service()).
7810 * #GNetworkAddress and #GNetworkService provide wrappers around
7811 * #GResolver functionality that also implement #GSocketConnectable,
7812 * making it easy to connect to a remote host/service.
7818 * @short_description: Resource framework
7819 * @include: gio/gio.h
7821 * Applications and libraries often contain binary or textual data that is
7822 * really part of the application, rather than user data. For instance
7823 * #GtkBuilder .ui files, splashscreen images, GMenu markup XML, CSS files,
7824 * icons, etc. These are often shipped as files in `$datadir/appname`, or
7825 * manually included as literal strings in the code.
7827 * The #GResource API and the [glib-compile-resources][glib-compile-resources] program
7828 * provide a convenient and efficient alternative to this which has some nice properties. You
7829 * maintain the files as normal files, so its easy to edit them, but during the build the files
7830 * are combined into a binary bundle that is linked into the executable. This means that loading
7831 * the resource files are efficient (as they are already in memory, shared with other instances) and
7832 * simple (no need to check for things like I/O errors or locate the files in the filesystem). It
7833 * also makes it easier to create relocatable applications.
7835 * Resource files can also be marked as compressed. Such files will be included in the resource bundle
7836 * in a compressed form, but will be automatically uncompressed when the resource is used. This
7837 * is very useful e.g. for larger text files that are parsed once (or rarely) and then thrown away.
7839 * Resource files can also be marked to be preprocessed, by setting the value of the
7840 * `preprocess` attribute to a comma-separated list of preprocessing options.
7841 * The only options currently supported are:
7843 * `xml-stripblanks` which will use the xmllint command
7844 * to strip ignorable whitespace from the XML file. For this to work,
7845 * the `XMLLINT` environment variable must be set to the full path to
7846 * the xmllint executable, or xmllint must be in the `PATH`; otherwise
7847 * the preprocessing step is skipped.
7849 * `to-pixdata` (deprecated since gdk-pixbuf 2.32) which will use the
7850 * `gdk-pixbuf-pixdata` command to convert images to the #GdkPixdata format,
7851 * which allows you to create pixbufs directly using the data inside the
7852 * resource file, rather than an (uncompressed) copy of it. For this, the
7853 * `gdk-pixbuf-pixdata` program must be in the `PATH`, or the
7854 * `GDK_PIXBUF_PIXDATA` environment variable must be set to the full path to the
7855 * `gdk-pixbuf-pixdata` executable; otherwise the resource compiler will abort.
7856 * `to-pixdata` has been deprecated since gdk-pixbuf 2.32, as #GResource
7857 * supports embedding modern image formats just as well. Instead of using it,
7858 * embed a PNG or SVG file in your #GResource.
7860 * `json-stripblanks` which will use the `json-glib-format` command to strip
7861 * ignorable whitespace from the JSON file. For this to work, the
7862 * `JSON_GLIB_FORMAT` environment variable must be set to the full path to the
7863 * `json-glib-format` executable, or it must be in the `PATH`;
7864 * otherwise the preprocessing step is skipped. In addition, at least version
7865 * 1.6 of `json-glib-format` is required.
7867 * Resource files will be exported in the GResource namespace using the
7868 * combination of the given `prefix` and the filename from the `file` element.
7869 * The `alias` attribute can be used to alter the filename to expose them at a
7870 * different location in the resource namespace. Typically, this is used to
7871 * include files from a different source directory without exposing the source
7872 * directory in the resource namespace, as in the example below.
7874 * Resource bundles are created by the [glib-compile-resources][glib-compile-resources] program
7875 * which takes an XML file that describes the bundle, and a set of files that the XML references. These
7876 * are combined into a binary resource bundle.
7878 * An example resource description:
7880 * <?xml version="1.0" encoding="UTF-8"?>
7882 * <gresource prefix="/org/gtk/Example">
7883 * <file>data/splashscreen.png</file>
7884 * <file compressed="true">dialog.ui</file>
7885 * <file preprocess="xml-stripblanks">menumarkup.xml</file>
7886 * <file alias="example.css">data/example.css</file>
7891 * This will create a resource bundle with the following files:
7893 * /org/gtk/Example/data/splashscreen.png
7894 * /org/gtk/Example/dialog.ui
7895 * /org/gtk/Example/menumarkup.xml
7896 * /org/gtk/Example/example.css
7899 * Note that all resources in the process share the same namespace, so use Java-style
7900 * path prefixes (like in the above example) to avoid conflicts.
7902 * You can then use [glib-compile-resources][glib-compile-resources] to compile the XML to a
7903 * binary bundle that you can load with g_resource_load(). However, its more common to use the --generate-source and
7904 * --generate-header arguments to create a source file and header to link directly into your application.
7905 * This will generate `get_resource()`, `register_resource()` and
7906 * `unregister_resource()` functions, prefixed by the `--c-name` argument passed
7907 * to [glib-compile-resources][glib-compile-resources]. `get_resource()` returns
7908 * the generated #GResource object. The register and unregister functions
7909 * register the resource so its files can be accessed using
7910 * g_resources_lookup_data().
7912 * Once a #GResource has been created and registered all the data in it can be accessed globally in the process by
7913 * using API calls like g_resources_open_stream() to stream the data or g_resources_lookup_data() to get a direct pointer
7914 * to the data. You can also use URIs like "resource:///org/gtk/Example/data/splashscreen.png" with #GFile to access
7915 * the resource data.
7917 * Some higher-level APIs, such as #GtkApplication, will automatically load
7918 * resources from certain well-known paths in the resource namespace as a
7919 * convenience. See the documentation for those APIs for details.
7921 * There are two forms of the generated source, the default version uses the compiler support for constructor
7922 * and destructor functions (where available) to automatically create and register the #GResource on startup
7923 * or library load time. If you pass `--manual-register`, two functions to register/unregister the resource are created
7924 * instead. This requires an explicit initialization call in your application/library, but it works on all platforms,
7925 * even on the minor ones where constructors are not supported. (Constructor support is available for at least Win32, Mac OS and Linux.)
7927 * Note that resource data can point directly into the data segment of e.g. a library, so if you are unloading libraries
7928 * during runtime you need to be very careful with keeping around pointers to data from a resource, as this goes away
7929 * when the library is unloaded. However, in practice this is not generally a problem, since most resource accesses
7930 * are for your own resources, and resource data is often used once, during parsing, and then released.
7932 * When debugging a program or testing a change to an installed version, it is often useful to be able to
7933 * replace resources in the program or library, without recompiling, for debugging or quick hacking and testing
7934 * purposes. Since GLib 2.50, it is possible to use the `G_RESOURCE_OVERLAYS` environment variable to selectively overlay
7935 * resources with replacements from the filesystem. It is a %G_SEARCHPATH_SEPARATOR-separated list of substitutions to perform
7936 * during resource lookups. It is ignored when running in a setuid process.
7938 * A substitution has the form
7941 * /org/gtk/libgtk=/home/desrt/gtk-overlay
7944 * The part before the `=` is the resource subpath for which the overlay applies. The part after is a
7945 * filesystem path which contains files and subdirectories as you would like to be loaded as resources with the
7948 * In the example above, if an application tried to load a resource with the resource path
7949 * `/org/gtk/libgtk/ui/gtkdialog.ui` then GResource would check the filesystem path
7950 * `/home/desrt/gtk-overlay/ui/gtkdialog.ui`. If a file was found there, it would be used instead. This is an
7951 * overlay, not an outright replacement, which means that if a file is not found at that path, the built-in
7952 * version will be used instead. Whiteouts are not currently supported.
7954 * Substitutions must start with a slash, and must not contain a trailing slash before the '='. The path after
7955 * the slash should ideally be absolute, but this is not strictly required. It is possible to overlay the
7956 * location of a single resource with an individual file.
7964 * @short_description: Stream seeking interface
7965 * @include: gio/gio.h
7966 * @see_also: #GInputStream, #GOutputStream
7968 * #GSeekable is implemented by streams (implementations of
7969 * #GInputStream or #GOutputStream) that support seeking.
7971 * Seekable streams largely fall into two categories: resizable and
7974 * #GSeekable on fixed-sized streams is approximately the same as POSIX
7975 * lseek() on a block device (for example: attempting to seek past the
7976 * end of the device is an error). Fixed streams typically cannot be
7979 * #GSeekable on resizable streams is approximately the same as POSIX
7980 * lseek() on a normal file. Seeking past the end and writing data will
7981 * usually cause the stream to resize by introducing zero bytes.
7987 * @short_description: High-level API for application settings
7988 * @include: gio/gio.h
7990 * The #GSettings class provides a convenient API for storing and retrieving
7991 * application settings.
7993 * Reads and writes can be considered to be non-blocking. Reading
7994 * settings with #GSettings is typically extremely fast: on
7995 * approximately the same order of magnitude (but slower than) a
7996 * #GHashTable lookup. Writing settings is also extremely fast in terms
7997 * of time to return to your application, but can be extremely expensive
7998 * for other threads and other processes. Many settings backends
7999 * (including dconf) have lazy initialisation which means in the common
8000 * case of the user using their computer without modifying any settings
8001 * a lot of work can be avoided. For dconf, the D-Bus service doesn't
8002 * even need to be started in this case. For this reason, you should
8003 * only ever modify #GSettings keys in response to explicit user action.
8004 * Particular care should be paid to ensure that modifications are not
8005 * made during startup -- for example, when setting the initial value
8006 * of preferences widgets. The built-in g_settings_bind() functionality
8007 * is careful not to write settings in response to notify signals as a
8008 * result of modifications that it makes to widgets.
8010 * When creating a GSettings instance, you have to specify a schema
8011 * that describes the keys in your settings and their types and default
8012 * values, as well as some other information.
8014 * Normally, a schema has a fixed path that determines where the settings
8015 * are stored in the conceptual global tree of settings. However, schemas
8016 * can also be '[relocatable][gsettings-relocatable]', i.e. not equipped with
8017 * a fixed path. This is
8018 * useful e.g. when the schema describes an 'account', and you want to be
8019 * able to store a arbitrary number of accounts.
8021 * Paths must start with and end with a forward slash character ('/')
8022 * and must not contain two sequential slash characters. Paths should
8023 * be chosen based on a domain name associated with the program or
8024 * library to which the settings belong. Examples of paths are
8025 * "/org/gtk/settings/file-chooser/" and "/ca/desrt/dconf-editor/".
8026 * Paths should not start with "/apps/", "/desktop/" or "/system/" as
8027 * they often did in GConf.
8029 * Unlike other configuration systems (like GConf), GSettings does not
8030 * restrict keys to basic types like strings and numbers. GSettings stores
8031 * values as #GVariant, and allows any #GVariantType for keys. Key names
8032 * are restricted to lowercase characters, numbers and '-'. Furthermore,
8033 * the names must begin with a lowercase character, must not end
8034 * with a '-', and must not contain consecutive dashes.
8036 * Similar to GConf, the default values in GSettings schemas can be
8037 * localized, but the localized values are stored in gettext catalogs
8038 * and looked up with the domain that is specified in the
8039 * `gettext-domain` attribute of the <schemalist> or <schema>
8040 * elements and the category that is specified in the `l10n` attribute of
8041 * the <default> element. The string which is translated includes all text in
8042 * the <default> element, including any surrounding quotation marks.
8044 * The `l10n` attribute must be set to `messages` or `time`, and sets the
8045 * [locale category for
8046 * translation](https://www.gnu.org/software/gettext/manual/html_node/Aspects.html#index-locale-categories-1).
8047 * The `messages` category should be used by default; use `time` for
8048 * translatable date or time formats. A translation comment can be added as an
8049 * XML comment immediately above the <default> element — it is recommended to
8050 * add these comments to aid translators understand the meaning and
8051 * implications of the default value. An optional translation `context`
8052 * attribute can be set on the <default> element to disambiguate multiple
8053 * defaults which use the same string.
8057 * <!-- Translators: A list of words which are not allowed to be typed, in
8058 * GVariant serialization syntax.
8059 * See: https://developer.gnome.org/glib/stable/gvariant-text.html -->
8060 * <default l10n='messages' context='Banned words'>['bad', 'words']</default>
8063 * Translations of default values must remain syntactically valid serialized
8064 * #GVariants (e.g. retaining any surrounding quotation marks) or runtime
8065 * errors will occur.
8067 * GSettings uses schemas in a compact binary form that is created
8068 * by the [glib-compile-schemas][glib-compile-schemas]
8069 * utility. The input is a schema description in an XML format.
8071 * A DTD for the gschema XML format can be found here:
8072 * [gschema.dtd](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/gschema.dtd)
8074 * The [glib-compile-schemas][glib-compile-schemas] tool expects schema
8075 * files to have the extension `.gschema.xml`.
8077 * At runtime, schemas are identified by their id (as specified in the
8078 * id attribute of the <schema> element). The convention for schema
8079 * ids is to use a dotted name, similar in style to a D-Bus bus name,
8080 * e.g. "org.gnome.SessionManager". In particular, if the settings are
8081 * for a specific service that owns a D-Bus bus name, the D-Bus bus name
8082 * and schema id should match. For schemas which deal with settings not
8083 * associated with one named application, the id should not use
8084 * StudlyCaps, e.g. "org.gnome.font-rendering".
8086 * In addition to #GVariant types, keys can have types that have
8087 * enumerated types. These can be described by a <choice>,
8088 * <enum> or <flags> element, as seen in the
8089 * [example][schema-enumerated]. The underlying type of such a key
8090 * is string, but you can use g_settings_get_enum(), g_settings_set_enum(),
8091 * g_settings_get_flags(), g_settings_set_flags() access the numeric values
8092 * corresponding to the string value of enum and flags keys.
8094 * An example for default value:
8097 * <schema id="org.gtk.Test" path="/org/gtk/Test/" gettext-domain="test">
8099 * <key name="greeting" type="s">
8100 * <default l10n="messages">"Hello, earthlings"</default>
8101 * <summary>A greeting</summary>
8103 * Greeting of the invading martians
8107 * <key name="box" type="(ii)">
8108 * <default>(20,30)</default>
8111 * <key name="empty-string" type="s">
8112 * <default>""</default>
8113 * <summary>Empty strings have to be provided in GVariant form</summary>
8120 * An example for ranges, choices and enumerated types:
8124 * <enum id="org.gtk.Test.myenum">
8125 * <value nick="first" value="1"/>
8126 * <value nick="second" value="2"/>
8129 * <flags id="org.gtk.Test.myflags">
8130 * <value nick="flag1" value="1"/>
8131 * <value nick="flag2" value="2"/>
8132 * <value nick="flag3" value="4"/>
8135 * <schema id="org.gtk.Test">
8137 * <key name="key-with-range" type="i">
8138 * <range min="1" max="100"/>
8139 * <default>10</default>
8142 * <key name="key-with-choices" type="s">
8144 * <choice value='Elisabeth'/>
8145 * <choice value='Annabeth'/>
8146 * <choice value='Joe'/>
8149 * <alias value='Anna' target='Annabeth'/>
8150 * <alias value='Beth' target='Elisabeth'/>
8152 * <default>'Joe'</default>
8155 * <key name='enumerated-key' enum='org.gtk.Test.myenum'>
8156 * <default>'first'</default>
8159 * <key name='flags-key' flags='org.gtk.Test.myflags'>
8160 * <default>["flag1","flag2"]</default>
8166 * ## Vendor overrides
8168 * Default values are defined in the schemas that get installed by
8169 * an application. Sometimes, it is necessary for a vendor or distributor
8170 * to adjust these defaults. Since patching the XML source for the schema
8171 * is inconvenient and error-prone,
8172 * [glib-compile-schemas][glib-compile-schemas] reads so-called vendor
8173 * override' files. These are keyfiles in the same directory as the XML
8174 * schema sources which can override default values. The schema id serves
8175 * as the group name in the key file, and the values are expected in
8176 * serialized GVariant form, as in the following example:
8183 * glib-compile-schemas expects schema files to have the extension
8184 * `.gschema.override`.
8188 * A very convenient feature of GSettings lets you bind #GObject properties
8189 * directly to settings, using g_settings_bind(). Once a GObject property
8190 * has been bound to a setting, changes on either side are automatically
8191 * propagated to the other side. GSettings handles details like mapping
8192 * between GObject and GVariant types, and preventing infinite cycles.
8194 * This makes it very easy to hook up a preferences dialog to the
8195 * underlying settings. To make this even more convenient, GSettings
8196 * looks for a boolean property with the name "sensitivity" and
8197 * automatically binds it to the writability of the bound setting.
8198 * If this 'magic' gets in the way, it can be suppressed with the
8199 * #G_SETTINGS_BIND_NO_SENSITIVITY flag.
8201 * ## Relocatable schemas # {#gsettings-relocatable}
8203 * A relocatable schema is one with no `path` attribute specified on its
8204 * <schema> element. By using g_settings_new_with_path(), a #GSettings object
8205 * can be instantiated for a relocatable schema, assigning a path to the
8206 * instance. Paths passed to g_settings_new_with_path() will typically be
8207 * constructed dynamically from a constant prefix plus some form of instance
8208 * identifier; but they must still be valid GSettings paths. Paths could also
8209 * be constant and used with a globally installed schema originating from a
8210 * dependency library.
8212 * For example, a relocatable schema could be used to store geometry information
8213 * for different windows in an application. If the schema ID was
8214 * `org.foo.MyApp.Window`, it could be instantiated for paths
8215 * `/org/foo/MyApp/main/`, `/org/foo/MyApp/document-1/`,
8216 * `/org/foo/MyApp/document-2/`, etc. If any of the paths are well-known
8217 * they can be specified as <child> elements in the parent schema, e.g.:
8219 * <schema id="org.foo.MyApp" path="/org/foo/MyApp/">
8220 * <child name="main" schema="org.foo.MyApp.Window"/>
8224 * ## Build system integration # {#gsettings-build-system}
8226 * GSettings comes with autotools integration to simplify compiling and
8227 * installing schemas. To add GSettings support to an application, add the
8228 * following to your `configure.ac`:
8233 * In the appropriate `Makefile.am`, use the following snippet to compile and
8234 * install the named schema:
8236 * gsettings_SCHEMAS = org.foo.MyApp.gschema.xml
8237 * EXTRA_DIST = $(gsettings_SCHEMAS)
8242 * No changes are needed to the build system to mark a schema XML file for
8243 * translation. Assuming it sets the `gettext-domain` attribute, a schema may
8244 * be marked for translation by adding it to `POTFILES.in`, assuming gettext
8245 * 0.19 is in use (the preferred method for translation):
8247 * data/org.foo.MyApp.gschema.xml
8250 * Alternatively, if intltool 0.50.1 is in use:
8252 * [type: gettext/gsettings]data/org.foo.MyApp.gschema.xml
8255 * GSettings will use gettext to look up translations for the <summary> and
8256 * <description> elements, and also any <default> elements which have a `l10n`
8257 * attribute set. Translations must not be included in the `.gschema.xml` file
8258 * by the build system, for example by using intltool XML rules with a
8259 * `.gschema.xml.in` template.
8261 * If an enumerated type defined in a C header file is to be used in a GSettings
8262 * schema, it can either be defined manually using an <enum> element in the
8263 * schema XML, or it can be extracted automatically from the C header. This
8264 * approach is preferred, as it ensures the two representations are always
8265 * synchronised. To do so, add the following to the relevant `Makefile.am`:
8267 * gsettings_ENUM_NAMESPACE = org.foo.MyApp
8268 * gsettings_ENUM_FILES = my-app-enums.h my-app-misc.h
8271 * `gsettings_ENUM_NAMESPACE` specifies the schema namespace for the enum files,
8272 * which are specified in `gsettings_ENUM_FILES`. This will generate a
8273 * `org.foo.MyApp.enums.xml` file containing the extracted enums, which will be
8274 * automatically included in the schema compilation, install and uninstall
8275 * rules. It should not be committed to version control or included in
8281 * SECTION:gsettingsbackend
8282 * @title: GSettingsBackend
8283 * @short_description: Interface for settings backend implementations
8284 * @include: gio/gsettingsbackend.h
8285 * @see_also: #GSettings, #GIOExtensionPoint
8287 * The #GSettingsBackend interface defines a generic interface for
8288 * non-strictly-typed data that is stored in a hierarchy. To implement
8289 * an alternative storage backend for #GSettings, you need to implement
8290 * the #GSettingsBackend interface and then make it implement the
8291 * extension point #G_SETTINGS_BACKEND_EXTENSION_POINT_NAME.
8293 * The interface defines methods for reading and writing values, a
8294 * method for determining if writing of certain values will fail
8295 * (lockdown) and a change notification mechanism.
8297 * The semantics of the interface are very precisely defined and
8298 * implementations must carefully adhere to the expectations of
8299 * callers that are documented on each of the interface methods.
8301 * Some of the #GSettingsBackend functions accept or return a #GTree.
8302 * These trees always have strings as keys and #GVariant as values.
8303 * g_settings_backend_create_tree() is a convenience function to create
8306 * The #GSettingsBackend API is exported to allow third-party
8307 * implementations, but does not carry the same stability guarantees
8308 * as the public GIO API. For this reason, you have to define the
8309 * C preprocessor symbol %G_SETTINGS_ENABLE_BACKEND before including
8310 * `gio/gsettingsbackend.h`.
8315 * SECTION:gsettingsschema
8316 * @short_description: Introspecting and controlling the loading
8317 * of GSettings schemas
8318 * @include: gio/gio.h
8320 * The #GSettingsSchemaSource and #GSettingsSchema APIs provide a
8321 * mechanism for advanced control over the loading of schemas and a
8322 * mechanism for introspecting their content.
8324 * Plugin loading systems that wish to provide plugins a way to access
8325 * settings face the problem of how to make the schemas for these
8326 * settings visible to GSettings. Typically, a plugin will want to ship
8327 * the schema along with itself and it won't be installed into the
8328 * standard system directories for schemas.
8330 * #GSettingsSchemaSource provides a mechanism for dealing with this by
8331 * allowing the creation of a new 'schema source' from which schemas can
8332 * be acquired. This schema source can then become part of the metadata
8333 * associated with the plugin and queried whenever the plugin requires
8334 * access to some settings.
8336 * Consider the following example:
8338 * |[<!-- language="C" -->
8342 * GSettingsSchemaSource *schema_source;
8347 * initialise_plugin (const gchar *dir)
8353 * plugin->schema_source =
8354 * g_settings_schema_source_new_from_directory (dir,
8355 * g_settings_schema_source_get_default (), FALSE, NULL);
8365 * plugin_get_settings (Plugin *plugin,
8366 * const gchar *schema_id)
8368 * GSettingsSchema *schema;
8370 * if (schema_id == NULL)
8371 * schema_id = plugin->identifier;
8373 * schema = g_settings_schema_source_lookup (plugin->schema_source,
8374 * schema_id, FALSE);
8376 * if (schema == NULL)
8378 * ... disable the plugin or abort, etc ...
8381 * return g_settings_new_full (schema, NULL, NULL);
8385 * The code above shows how hooks should be added to the code that
8386 * initialises (or enables) the plugin to create the schema source and
8387 * how an API can be added to the plugin system to provide a convenient
8388 * way for the plugin to access its settings, using the schemas that it
8391 * From the standpoint of the plugin, it would need to ensure that it
8392 * ships a gschemas.compiled file as part of itself, and then simply do
8395 * |[<!-- language="C" -->
8397 * GSettings *settings;
8400 * settings = plugin_get_settings (self, NULL);
8401 * some_value = g_settings_get_int (settings, "some-value");
8406 * It's also possible that the plugin system expects the schema source
8407 * files (ie: .gschema.xml files) instead of a gschemas.compiled file.
8408 * In that case, the plugin loading system must compile the schemas for
8409 * itself before attempting to create the settings source.
8416 * SECTION:gsimpleaction
8417 * @title: GSimpleAction
8418 * @short_description: A simple GAction implementation
8419 * @include: gio/gio.h
8421 * A #GSimpleAction is the obvious simple implementation of the #GAction
8422 * interface. This is the easiest way to create an action for purposes of
8423 * adding it to a #GSimpleActionGroup.
8425 * See also #GtkAction.
8430 * SECTION:gsimpleactiongroup
8431 * @title: GSimpleActionGroup
8432 * @short_description: A simple GActionGroup implementation
8433 * @include: gio/gio.h
8435 * #GSimpleActionGroup is a hash table filled with #GAction objects,
8436 * implementing the #GActionGroup and #GActionMap interfaces.
8441 * SECTION:gsimpleasyncresult
8442 * @short_description: Simple asynchronous results implementation
8443 * @include: gio/gio.h
8444 * @see_also: #GAsyncResult, #GTask
8446 * As of GLib 2.46, #GSimpleAsyncResult is deprecated in favor of
8447 * #GTask, which provides a simpler API.
8449 * #GSimpleAsyncResult implements #GAsyncResult.
8451 * GSimpleAsyncResult handles #GAsyncReadyCallbacks, error
8452 * reporting, operation cancellation and the final state of an operation,
8453 * completely transparent to the application. Results can be returned
8454 * as a pointer e.g. for functions that return data that is collected
8455 * asynchronously, a boolean value for checking the success or failure
8456 * of an operation, or a #gssize for operations which return the number
8457 * of bytes modified by the operation; all of the simple return cases
8460 * Most of the time, an application will not need to know of the details
8461 * of this API; it is handled transparently, and any necessary operations
8462 * are handled by #GAsyncResult's interface. However, if implementing a
8463 * new GIO module, for writing language bindings, or for complex
8464 * applications that need better control of how asynchronous operations
8465 * are completed, it is important to understand this functionality.
8467 * GSimpleAsyncResults are tagged with the calling function to ensure
8468 * that asynchronous functions and their finishing functions are used
8469 * together correctly.
8471 * To create a new #GSimpleAsyncResult, call g_simple_async_result_new().
8472 * If the result needs to be created for a #GError, use
8473 * g_simple_async_result_new_from_error() or
8474 * g_simple_async_result_new_take_error(). If a #GError is not available
8475 * (e.g. the asynchronous operation's doesn't take a #GError argument),
8476 * but the result still needs to be created for an error condition, use
8477 * g_simple_async_result_new_error() (or g_simple_async_result_set_error_va()
8478 * if your application or binding requires passing a variable argument list
8479 * directly), and the error can then be propagated through the use of
8480 * g_simple_async_result_propagate_error().
8482 * An asynchronous operation can be made to ignore a cancellation event by
8483 * calling g_simple_async_result_set_handle_cancellation() with a
8484 * #GSimpleAsyncResult for the operation and %FALSE. This is useful for
8485 * operations that are dangerous to cancel, such as close (which would
8486 * cause a leak if cancelled before being run).
8488 * GSimpleAsyncResult can integrate into GLib's event loop, #GMainLoop,
8489 * or it can use #GThreads.
8490 * g_simple_async_result_complete() will finish an I/O task directly
8491 * from the point where it is called. g_simple_async_result_complete_in_idle()
8492 * will finish it from an idle handler in the
8493 * [thread-default main context][g-main-context-push-thread-default]
8494 * where the #GSimpleAsyncResult was created.
8495 * g_simple_async_result_run_in_thread() will run the job in a
8496 * separate thread and then use
8497 * g_simple_async_result_complete_in_idle() to deliver the result.
8499 * To set the results of an asynchronous function,
8500 * g_simple_async_result_set_op_res_gpointer(),
8501 * g_simple_async_result_set_op_res_gboolean(), and
8502 * g_simple_async_result_set_op_res_gssize()
8503 * are provided, setting the operation's result to a gpointer, gboolean, or
8504 * gssize, respectively.
8506 * Likewise, to get the result of an asynchronous function,
8507 * g_simple_async_result_get_op_res_gpointer(),
8508 * g_simple_async_result_get_op_res_gboolean(), and
8509 * g_simple_async_result_get_op_res_gssize() are
8510 * provided, getting the operation's result as a gpointer, gboolean, and
8511 * gssize, respectively.
8513 * For the details of the requirements implementations must respect, see
8514 * #GAsyncResult. A typical implementation of an asynchronous operation
8515 * using GSimpleAsyncResult looks something like this:
8517 * |[<!-- language="C" -->
8519 * baked_cb (Cake *cake,
8520 * gpointer user_data)
8522 * // In this example, this callback is not given a reference to the cake,
8523 * // so the GSimpleAsyncResult has to take a reference to it.
8524 * GSimpleAsyncResult *result = user_data;
8527 * g_simple_async_result_set_error (result,
8529 * BAKER_ERROR_NO_FLOUR,
8530 * "Go to the supermarket");
8532 * g_simple_async_result_set_op_res_gpointer (result,
8533 * g_object_ref (cake),
8537 * // In this example, we assume that baked_cb is called as a callback from
8538 * // the mainloop, so it's safe to complete the operation synchronously here.
8539 * // If, however, _baker_prepare_cake () might call its callback without
8540 * // first returning to the mainloop — inadvisable, but some APIs do so —
8541 * // we would need to use g_simple_async_result_complete_in_idle().
8542 * g_simple_async_result_complete (result);
8543 * g_object_unref (result);
8547 * baker_bake_cake_async (Baker *self,
8549 * GAsyncReadyCallback callback,
8550 * gpointer user_data)
8552 * GSimpleAsyncResult *simple;
8557 * g_simple_async_report_error_in_idle (G_OBJECT (self),
8561 * BAKER_ERROR_TOO_SMALL,
8562 * "%ucm radius cakes are silly",
8567 * simple = g_simple_async_result_new (G_OBJECT (self),
8570 * baker_bake_cake_async);
8571 * cake = _baker_get_cached_cake (self, radius);
8575 * g_simple_async_result_set_op_res_gpointer (simple,
8576 * g_object_ref (cake),
8578 * g_simple_async_result_complete_in_idle (simple);
8579 * g_object_unref (simple);
8580 * // Drop the reference returned by _baker_get_cached_cake();
8581 * // the GSimpleAsyncResult has taken its own reference.
8582 * g_object_unref (cake);
8586 * _baker_prepare_cake (self, radius, baked_cb, simple);
8590 * baker_bake_cake_finish (Baker *self,
8591 * GAsyncResult *result,
8594 * GSimpleAsyncResult *simple;
8597 * g_return_val_if_fail (g_simple_async_result_is_valid (result,
8599 * baker_bake_cake_async),
8602 * simple = (GSimpleAsyncResult *) result;
8604 * if (g_simple_async_result_propagate_error (simple, error))
8607 * cake = CAKE (g_simple_async_result_get_op_res_gpointer (simple));
8608 * return g_object_ref (cake);
8615 * SECTION:gsimpleiostream
8616 * @short_description: A wrapper around an input and an output stream.
8617 * @include: gio/gio.h
8618 * @see_also: #GIOStream
8620 * GSimpleIOStream creates a #GIOStream from an arbitrary #GInputStream and
8621 * #GOutputStream. This allows any pair of input and output streams to be used
8622 * with #GIOStream methods.
8624 * This is useful when you obtained a #GInputStream and a #GOutputStream
8625 * by other means, for instance creating them with platform specific methods as
8626 * g_unix_input_stream_new() or g_win32_input_stream_new(), and you want
8627 * to take advantage of the methods provided by #GIOStream.
8634 * SECTION:gsimplepermission
8635 * @title: GSimplePermission
8636 * @short_description: A GPermission that doesn't change value
8637 * @include: gio/gio.h
8639 * #GSimplePermission is a trivial implementation of #GPermission that
8640 * represents a permission that is either always or never allowed. The
8641 * value is given at construction and doesn't change.
8643 * Calling request or release will result in errors.
8648 * SECTION:gsimpleproxyresolver
8649 * @short_description: Simple proxy resolver implementation
8650 * @include: gio/gio.h
8651 * @see_also: g_socket_client_set_proxy_resolver()
8653 * #GSimpleProxyResolver is a simple #GProxyResolver implementation
8654 * that handles a single default proxy, multiple URI-scheme-specific
8655 * proxies, and a list of hosts that proxies should not be used for.
8657 * #GSimpleProxyResolver is never the default proxy resolver, but it
8658 * can be used as the base class for another proxy resolver
8659 * implementation, or it can be created and used manually, such as
8660 * with g_socket_client_set_proxy_resolver().
8668 * @short_description: Low-level socket object
8669 * @include: gio/gio.h
8670 * @see_also: #GInitable, [<gnetworking.h>][gio-gnetworking.h]
8672 * A #GSocket is a low-level networking primitive. It is a more or less
8673 * direct mapping of the BSD socket API in a portable GObject based API.
8674 * It supports both the UNIX socket implementations and winsock2 on Windows.
8676 * #GSocket is the platform independent base upon which the higher level
8677 * network primitives are based. Applications are not typically meant to
8678 * use it directly, but rather through classes like #GSocketClient,
8679 * #GSocketService and #GSocketConnection. However there may be cases where
8680 * direct use of #GSocket is useful.
8682 * #GSocket implements the #GInitable interface, so if it is manually constructed
8683 * by e.g. g_object_new() you must call g_initable_init() and check the
8684 * results before using the object. This is done automatically in
8685 * g_socket_new() and g_socket_new_from_fd(), so these functions can return
8688 * Sockets operate in two general modes, blocking or non-blocking. When
8689 * in blocking mode all operations (which don’t take an explicit blocking
8690 * parameter) block until the requested operation
8691 * is finished or there is an error. In non-blocking mode all calls that
8692 * would block return immediately with a %G_IO_ERROR_WOULD_BLOCK error.
8693 * To know when a call would successfully run you can call g_socket_condition_check(),
8694 * or g_socket_condition_wait(). You can also use g_socket_create_source() and
8695 * attach it to a #GMainContext to get callbacks when I/O is possible.
8696 * Note that all sockets are always set to non blocking mode in the system, and
8697 * blocking mode is emulated in GSocket.
8699 * When working in non-blocking mode applications should always be able to
8700 * handle getting a %G_IO_ERROR_WOULD_BLOCK error even when some other
8701 * function said that I/O was possible. This can easily happen in case
8702 * of a race condition in the application, but it can also happen for other
8703 * reasons. For instance, on Windows a socket is always seen as writable
8704 * until a write returns %G_IO_ERROR_WOULD_BLOCK.
8706 * #GSockets can be either connection oriented or datagram based.
8707 * For connection oriented types you must first establish a connection by
8708 * either connecting to an address or accepting a connection from another
8709 * address. For connectionless socket types the target/source address is
8710 * specified or received in each I/O operation.
8712 * All socket file descriptors are set to be close-on-exec.
8714 * Note that creating a #GSocket causes the signal %SIGPIPE to be
8715 * ignored for the remainder of the program. If you are writing a
8716 * command-line utility that uses #GSocket, you may need to take into
8717 * account the fact that your program will not automatically be killed
8718 * if it tries to write to %stdout after it has been closed.
8720 * Like most other APIs in GLib, #GSocket is not inherently thread safe. To use
8721 * a #GSocket concurrently from multiple threads, you must implement your own
8729 * SECTION:gsocketaddress
8730 * @short_description: Abstract base class representing endpoints
8731 * for socket communication
8732 * @include: gio/gio.h
8734 * #GSocketAddress is the equivalent of struct sockaddr in the BSD
8735 * sockets API. This is an abstract class; use #GInetSocketAddress
8736 * for internet sockets, or #GUnixSocketAddress for UNIX domain sockets.
8741 * SECTION:gsocketaddressenumerator
8742 * @short_description: Enumerator for socket addresses
8743 * @include: gio/gio.h
8745 * #GSocketAddressEnumerator is an enumerator type for #GSocketAddress
8746 * instances. It is returned by enumeration functions such as
8747 * g_socket_connectable_enumerate(), which returns a #GSocketAddressEnumerator
8748 * to list each #GSocketAddress which could be used to connect to that
8749 * #GSocketConnectable.
8751 * Enumeration is typically a blocking operation, so the asynchronous methods
8752 * g_socket_address_enumerator_next_async() and
8753 * g_socket_address_enumerator_next_finish() should be used where possible.
8755 * Each #GSocketAddressEnumerator can only be enumerated once. Once
8756 * g_socket_address_enumerator_next() has returned %NULL, further
8757 * enumeration with that #GSocketAddressEnumerator is not possible, and it can
8763 * SECTION:gsocketclient
8764 * @short_description: Helper for connecting to a network service
8765 * @include: gio/gio.h
8766 * @see_also: #GSocketConnection, #GSocketListener
8768 * #GSocketClient is a lightweight high-level utility class for connecting to
8769 * a network host using a connection oriented socket type.
8771 * You create a #GSocketClient object, set any options you want, and then
8772 * call a sync or async connect operation, which returns a #GSocketConnection
8773 * subclass on success.
8775 * The type of the #GSocketConnection object returned depends on the type of
8776 * the underlying socket that is in use. For instance, for a TCP/IP connection
8777 * it will be a #GTcpConnection.
8779 * As #GSocketClient is a lightweight object, you don't need to cache it. You
8780 * can just create a new one any time you need one.
8787 * SECTION:gsocketconnectable
8788 * @short_description: Interface for potential socket endpoints
8789 * @include: gio/gio.h
8791 * Objects that describe one or more potential socket endpoints
8792 * implement #GSocketConnectable. Callers can then use
8793 * g_socket_connectable_enumerate() to get a #GSocketAddressEnumerator
8794 * to try out each socket address in turn until one succeeds, as shown
8795 * in the sample code below.
8797 * |[<!-- language="C" -->
8798 * MyConnectionType *
8799 * connect_to_host (const char *hostname,
8801 * GCancellable *cancellable,
8804 * MyConnection *conn = NULL;
8805 * GSocketConnectable *addr;
8806 * GSocketAddressEnumerator *enumerator;
8807 * GSocketAddress *sockaddr;
8808 * GError *conn_error = NULL;
8810 * addr = g_network_address_new (hostname, port);
8811 * enumerator = g_socket_connectable_enumerate (addr);
8812 * g_object_unref (addr);
8814 * // Try each sockaddr until we succeed. Record the first connection error,
8815 * // but not any further ones (since they'll probably be basically the same
8817 * while (!conn && (sockaddr = g_socket_address_enumerator_next (enumerator, cancellable, error))
8819 * conn = connect_to_sockaddr (sockaddr, conn_error ? NULL : &conn_error);
8820 * g_object_unref (sockaddr);
8822 * g_object_unref (enumerator);
8828 * // We couldn't connect to the first address, but we succeeded
8829 * // in connecting to a later address.
8830 * g_error_free (conn_error);
8836 * /// Either initial lookup failed, or else the caller cancelled us.
8838 * g_error_free (conn_error);
8843 * g_error_propagate (error, conn_error);
8852 * SECTION:gsocketconnection
8853 * @short_description: A socket connection
8854 * @include: gio/gio.h
8855 * @see_also: #GIOStream, #GSocketClient, #GSocketListener
8857 * #GSocketConnection is a #GIOStream for a connected socket. They
8858 * can be created either by #GSocketClient when connecting to a host,
8859 * or by #GSocketListener when accepting a new client.
8861 * The type of the #GSocketConnection object returned from these calls
8862 * depends on the type of the underlying socket that is in use. For
8863 * instance, for a TCP/IP connection it will be a #GTcpConnection.
8865 * Choosing what type of object to construct is done with the socket
8866 * connection factory, and it is possible for 3rd parties to register
8867 * custom socket connection types for specific combination of socket
8868 * family/type/protocol using g_socket_connection_factory_register_type().
8870 * To close a #GSocketConnection, use g_io_stream_close(). Closing both
8871 * substreams of the #GIOStream separately will not close the underlying
8879 * SECTION:gsocketcontrolmessage
8880 * @title: GSocketControlMessage
8881 * @short_description: A GSocket control message
8882 * @include: gio/gio.h
8883 * @see_also: #GSocket.
8885 * A #GSocketControlMessage is a special-purpose utility message that
8886 * can be sent to or received from a #GSocket. These types of
8887 * messages are often called "ancillary data".
8889 * The message can represent some sort of special instruction to or
8890 * information from the socket or can represent a special kind of
8891 * transfer to the peer (for example, sending a file descriptor over
8894 * These messages are sent with g_socket_send_message() and received
8895 * with g_socket_receive_message().
8897 * To extend the set of control message that can be sent, subclass this
8898 * class and override the get_size, get_level, get_type and serialize
8901 * To extend the set of control messages that can be received, subclass
8902 * this class and implement the deserialize method. Also, make sure your
8903 * class is registered with the GType typesystem before calling
8904 * g_socket_receive_message() to read such a message.
8911 * SECTION:gsocketlistener
8912 * @title: GSocketListener
8913 * @short_description: Helper for accepting network client connections
8914 * @include: gio/gio.h
8915 * @see_also: #GThreadedSocketService, #GSocketService.
8917 * A #GSocketListener is an object that keeps track of a set
8918 * of server sockets and helps you accept sockets from any of the
8919 * socket, either sync or async.
8921 * Add addresses and ports to listen on using g_socket_listener_add_address()
8922 * and g_socket_listener_add_inet_port(). These will be listened on until
8923 * g_socket_listener_close() is called. Dropping your final reference to the
8924 * #GSocketListener will not cause g_socket_listener_close() to be called
8925 * implicitly, as some references to the #GSocketListener may be held
8928 * If you want to implement a network server, also look at #GSocketService
8929 * and #GThreadedSocketService which are subclasses of #GSocketListener
8930 * that make this even easier.
8937 * SECTION:gsocketservice
8938 * @title: GSocketService
8939 * @short_description: Make it easy to implement a network service
8940 * @include: gio/gio.h
8941 * @see_also: #GThreadedSocketService, #GSocketListener.
8943 * A #GSocketService is an object that represents a service that
8944 * is provided to the network or over local sockets. When a new
8945 * connection is made to the service the #GSocketService::incoming
8946 * signal is emitted.
8948 * A #GSocketService is a subclass of #GSocketListener and you need
8949 * to add the addresses you want to accept connections on with the
8950 * #GSocketListener APIs.
8952 * There are two options for implementing a network service based on
8953 * #GSocketService. The first is to create the service using
8954 * g_socket_service_new() and to connect to the #GSocketService::incoming
8955 * signal. The second is to subclass #GSocketService and override the
8956 * default signal handler implementation.
8958 * In either case, the handler must immediately return, or else it
8959 * will block additional incoming connections from being serviced.
8960 * If you are interested in writing connection handlers that contain
8961 * blocking code then see #GThreadedSocketService.
8963 * The socket service runs on the main loop of the
8964 * [thread-default context][g-main-context-push-thread-default-context]
8965 * of the thread it is created in, and is not
8966 * threadsafe in general. However, the calls to start and stop the
8967 * service are thread-safe so these can be used from threads that
8968 * handle incoming clients.
8975 * SECTION:gsrvtarget
8976 * @short_description: DNS SRV record target
8977 * @include: gio/gio.h
8979 * SRV (service) records are used by some network protocols to provide
8980 * service-specific aliasing and load-balancing. For example, XMPP
8981 * (Jabber) uses SRV records to locate the XMPP server for a domain;
8982 * rather than connecting directly to "example.com" or assuming a
8983 * specific server hostname like "xmpp.example.com", an XMPP client
8984 * would look up the "xmpp-client" SRV record for "example.com", and
8985 * then connect to whatever host was pointed to by that record.
8987 * You can use g_resolver_lookup_service() or
8988 * g_resolver_lookup_service_async() to find the #GSrvTargets
8989 * for a given service. However, if you are simply planning to connect
8990 * to the remote service, you can use #GNetworkService's
8991 * #GSocketConnectable interface and not need to worry about
8992 * #GSrvTarget at all.
8997 * SECTION:gsubprocess
8998 * @title: GSubprocess
8999 * @short_description: Child processes
9000 * @include: gio/gio.h
9001 * @see_also: #GSubprocessLauncher
9003 * #GSubprocess allows the creation of and interaction with child
9006 * Processes can be communicated with using standard GIO-style APIs (ie:
9007 * #GInputStream, #GOutputStream). There are GIO-style APIs to wait for
9008 * process termination (ie: cancellable and with an asynchronous
9011 * There is an API to force a process to terminate, as well as a
9012 * race-free API for sending UNIX signals to a subprocess.
9014 * One major advantage that GIO brings over the core GLib library is
9015 * comprehensive API for asynchronous I/O, such
9016 * g_output_stream_splice_async(). This makes GSubprocess
9017 * significantly more powerful and flexible than equivalent APIs in
9018 * some other languages such as the `subprocess.py`
9019 * included with Python. For example, using #GSubprocess one could
9020 * create two child processes, reading standard output from the first,
9021 * processing it, and writing to the input stream of the second, all
9022 * without blocking the main loop.
9024 * A powerful g_subprocess_communicate() API is provided similar to the
9025 * `communicate()` method of `subprocess.py`. This enables very easy
9026 * interaction with a subprocess that has been opened with pipes.
9028 * #GSubprocess defaults to tight control over the file descriptors open
9029 * in the child process, avoiding dangling-fd issues that are caused by
9030 * a simple fork()/exec(). The only open file descriptors in the
9031 * spawned process are ones that were explicitly specified by the
9032 * #GSubprocess API (unless %G_SUBPROCESS_FLAGS_INHERIT_FDS was
9035 * #GSubprocess will quickly reap all child processes as they exit,
9036 * avoiding "zombie processes" remaining around for long periods of
9037 * time. g_subprocess_wait() can be used to wait for this to happen,
9038 * but it will happen even without the call being explicitly made.
9040 * As a matter of principle, #GSubprocess has no API that accepts
9041 * shell-style space-separated strings. It will, however, match the
9042 * typical shell behaviour of searching the PATH for executables that do
9043 * not contain a directory separator in their name.
9045 * #GSubprocess attempts to have a very simple API for most uses (ie:
9046 * spawning a subprocess with arguments and support for most typical
9047 * kinds of input and output redirection). See g_subprocess_new(). The
9048 * #GSubprocessLauncher API is provided for more complicated cases
9049 * (advanced types of redirection, environment variable manipulation,
9050 * change of working directory, child setup functions, etc).
9052 * A typical use of #GSubprocess will involve calling
9053 * g_subprocess_new(), followed by g_subprocess_wait_async() or
9054 * g_subprocess_wait(). After the process exits, the status can be
9055 * checked using functions such as g_subprocess_get_if_exited() (which
9056 * are similar to the familiar WIFEXITED-style POSIX macros).
9063 * SECTION:gsubprocesslauncher
9064 * @title: GSubprocess Launcher
9065 * @short_description: Environment options for launching a child process
9066 * @include: gio/gio.h
9068 * This class contains a set of options for launching child processes,
9069 * such as where its standard input and output will be directed, the
9070 * argument list, the environment, and more.
9072 * While the #GSubprocess class has high level functions covering
9073 * popular cases, use of this class allows access to more advanced
9074 * options. It can also be used to launch multiple subprocesses with
9075 * a similar configuration.
9083 * @short_description: Cancellable synchronous or asynchronous task
9085 * @include: gio/gio.h
9086 * @see_also: #GAsyncResult
9088 * A #GTask represents and manages a cancellable "task".
9090 * ## Asynchronous operations
9092 * The most common usage of #GTask is as a #GAsyncResult, to
9093 * manage data during an asynchronous operation. You call
9094 * g_task_new() in the "start" method, followed by
9095 * g_task_set_task_data() and the like if you need to keep some
9096 * additional data associated with the task, and then pass the
9097 * task object around through your asynchronous operation.
9098 * Eventually, you will call a method such as
9099 * g_task_return_pointer() or g_task_return_error(), which will
9100 * save the value you give it and then invoke the task's callback
9102 * [thread-default main context][g-main-context-push-thread-default]
9103 * where it was created (waiting until the next iteration of the main
9104 * loop first, if necessary). The caller will pass the #GTask back to
9105 * the operation's finish function (as a #GAsyncResult), and you can
9106 * use g_task_propagate_pointer() or the like to extract the
9109 * Here is an example for using GTask as a GAsyncResult:
9110 * |[<!-- language="C" -->
9112 * CakeFrostingType frosting;
9117 * decoration_data_free (DecorationData *decoration)
9119 * g_free (decoration->message);
9120 * g_slice_free (DecorationData, decoration);
9124 * baked_cb (Cake *cake,
9125 * gpointer user_data)
9127 * GTask *task = user_data;
9128 * DecorationData *decoration = g_task_get_task_data (task);
9129 * GError *error = NULL;
9133 * g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_NO_FLOUR,
9134 * "Go to the supermarket");
9135 * g_object_unref (task);
9139 * if (!cake_decorate (cake, decoration->frosting, decoration->message, &error))
9141 * g_object_unref (cake);
9142 * // g_task_return_error() takes ownership of error
9143 * g_task_return_error (task, error);
9144 * g_object_unref (task);
9148 * g_task_return_pointer (task, cake, g_object_unref);
9149 * g_object_unref (task);
9153 * baker_bake_cake_async (Baker *self,
9155 * CakeFlavor flavor,
9156 * CakeFrostingType frosting,
9157 * const char *message,
9158 * GCancellable *cancellable,
9159 * GAsyncReadyCallback callback,
9160 * gpointer user_data)
9163 * DecorationData *decoration;
9166 * task = g_task_new (self, cancellable, callback, user_data);
9169 * g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_TOO_SMALL,
9170 * "%ucm radius cakes are silly",
9172 * g_object_unref (task);
9176 * cake = _baker_get_cached_cake (self, radius, flavor, frosting, message);
9179 * // _baker_get_cached_cake() returns a reffed cake
9180 * g_task_return_pointer (task, cake, g_object_unref);
9181 * g_object_unref (task);
9185 * decoration = g_slice_new (DecorationData);
9186 * decoration->frosting = frosting;
9187 * decoration->message = g_strdup (message);
9188 * g_task_set_task_data (task, decoration, (GDestroyNotify) decoration_data_free);
9190 * _baker_begin_cake (self, radius, flavor, cancellable, baked_cb, task);
9194 * baker_bake_cake_finish (Baker *self,
9195 * GAsyncResult *result,
9198 * g_return_val_if_fail (g_task_is_valid (result, self), NULL);
9200 * return g_task_propagate_pointer (G_TASK (result), error);
9204 * ## Chained asynchronous operations
9206 * #GTask also tries to simplify asynchronous operations that
9207 * internally chain together several smaller asynchronous
9208 * operations. g_task_get_cancellable(), g_task_get_context(),
9209 * and g_task_get_priority() allow you to get back the task's
9210 * #GCancellable, #GMainContext, and [I/O priority][io-priority]
9211 * when starting a new subtask, so you don't have to keep track
9212 * of them yourself. g_task_attach_source() simplifies the case
9213 * of waiting for a source to fire (automatically using the correct
9214 * #GMainContext and priority).
9216 * Here is an example for chained asynchronous operations:
9217 * |[<!-- language="C" -->
9220 * CakeFrostingType frosting;
9225 * decoration_data_free (BakingData *bd)
9228 * g_object_unref (bd->cake);
9229 * g_free (bd->message);
9230 * g_slice_free (BakingData, bd);
9234 * decorated_cb (Cake *cake,
9235 * GAsyncResult *result,
9236 * gpointer user_data)
9238 * GTask *task = user_data;
9239 * GError *error = NULL;
9241 * if (!cake_decorate_finish (cake, result, &error))
9243 * g_object_unref (cake);
9244 * g_task_return_error (task, error);
9245 * g_object_unref (task);
9249 * // baking_data_free() will drop its ref on the cake, so we have to
9250 * // take another here to give to the caller.
9251 * g_task_return_pointer (task, g_object_ref (cake), g_object_unref);
9252 * g_object_unref (task);
9256 * decorator_ready (gpointer user_data)
9258 * GTask *task = user_data;
9259 * BakingData *bd = g_task_get_task_data (task);
9261 * cake_decorate_async (bd->cake, bd->frosting, bd->message,
9262 * g_task_get_cancellable (task),
9263 * decorated_cb, task);
9265 * return G_SOURCE_REMOVE;
9269 * baked_cb (Cake *cake,
9270 * gpointer user_data)
9272 * GTask *task = user_data;
9273 * BakingData *bd = g_task_get_task_data (task);
9274 * GError *error = NULL;
9278 * g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_NO_FLOUR,
9279 * "Go to the supermarket");
9280 * g_object_unref (task);
9286 * // Bail out now if the user has already cancelled
9287 * if (g_task_return_error_if_cancelled (task))
9289 * g_object_unref (task);
9293 * if (cake_decorator_available (cake))
9294 * decorator_ready (task);
9299 * source = cake_decorator_wait_source_new (cake);
9300 * // Attach @source to @task's GMainContext and have it call
9301 * // decorator_ready() when it is ready.
9302 * g_task_attach_source (task, source, decorator_ready);
9303 * g_source_unref (source);
9308 * baker_bake_cake_async (Baker *self,
9310 * CakeFlavor flavor,
9311 * CakeFrostingType frosting,
9312 * const char *message,
9314 * GCancellable *cancellable,
9315 * GAsyncReadyCallback callback,
9316 * gpointer user_data)
9321 * task = g_task_new (self, cancellable, callback, user_data);
9322 * g_task_set_priority (task, priority);
9324 * bd = g_slice_new0 (BakingData);
9325 * bd->frosting = frosting;
9326 * bd->message = g_strdup (message);
9327 * g_task_set_task_data (task, bd, (GDestroyNotify) baking_data_free);
9329 * _baker_begin_cake (self, radius, flavor, cancellable, baked_cb, task);
9333 * baker_bake_cake_finish (Baker *self,
9334 * GAsyncResult *result,
9337 * g_return_val_if_fail (g_task_is_valid (result, self), NULL);
9339 * return g_task_propagate_pointer (G_TASK (result), error);
9343 * ## Asynchronous operations from synchronous ones
9345 * You can use g_task_run_in_thread() to turn a synchronous
9346 * operation into an asynchronous one, by running it in a thread.
9347 * When it completes, the result will be dispatched to the
9348 * [thread-default main context][g-main-context-push-thread-default]
9349 * where the #GTask was created.
9351 * Running a task in a thread:
9352 * |[<!-- language="C" -->
9355 * CakeFlavor flavor;
9356 * CakeFrostingType frosting;
9361 * cake_data_free (CakeData *cake_data)
9363 * g_free (cake_data->message);
9364 * g_slice_free (CakeData, cake_data);
9368 * bake_cake_thread (GTask *task,
9369 * gpointer source_object,
9370 * gpointer task_data,
9371 * GCancellable *cancellable)
9373 * Baker *self = source_object;
9374 * CakeData *cake_data = task_data;
9376 * GError *error = NULL;
9378 * cake = bake_cake (baker, cake_data->radius, cake_data->flavor,
9379 * cake_data->frosting, cake_data->message,
9380 * cancellable, &error);
9382 * g_task_return_pointer (task, cake, g_object_unref);
9384 * g_task_return_error (task, error);
9388 * baker_bake_cake_async (Baker *self,
9390 * CakeFlavor flavor,
9391 * CakeFrostingType frosting,
9392 * const char *message,
9393 * GCancellable *cancellable,
9394 * GAsyncReadyCallback callback,
9395 * gpointer user_data)
9397 * CakeData *cake_data;
9400 * cake_data = g_slice_new (CakeData);
9401 * cake_data->radius = radius;
9402 * cake_data->flavor = flavor;
9403 * cake_data->frosting = frosting;
9404 * cake_data->message = g_strdup (message);
9405 * task = g_task_new (self, cancellable, callback, user_data);
9406 * g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free);
9407 * g_task_run_in_thread (task, bake_cake_thread);
9408 * g_object_unref (task);
9412 * baker_bake_cake_finish (Baker *self,
9413 * GAsyncResult *result,
9416 * g_return_val_if_fail (g_task_is_valid (result, self), NULL);
9418 * return g_task_propagate_pointer (G_TASK (result), error);
9422 * ## Adding cancellability to uncancellable tasks
9424 * Finally, g_task_run_in_thread() and g_task_run_in_thread_sync()
9425 * can be used to turn an uncancellable operation into a
9426 * cancellable one. If you call g_task_set_return_on_cancel(),
9427 * passing %TRUE, then if the task's #GCancellable is cancelled,
9428 * it will return control back to the caller immediately, while
9429 * allowing the task thread to continue running in the background
9430 * (and simply discarding its result when it finally does finish).
9431 * Provided that the task thread is careful about how it uses
9432 * locks and other externally-visible resources, this allows you
9433 * to make "GLib-friendly" asynchronous and cancellable
9434 * synchronous variants of blocking APIs.
9436 * Cancelling a task:
9437 * |[<!-- language="C" -->
9439 * bake_cake_thread (GTask *task,
9440 * gpointer source_object,
9441 * gpointer task_data,
9442 * GCancellable *cancellable)
9444 * Baker *self = source_object;
9445 * CakeData *cake_data = task_data;
9447 * GError *error = NULL;
9449 * cake = bake_cake (baker, cake_data->radius, cake_data->flavor,
9450 * cake_data->frosting, cake_data->message,
9454 * g_task_return_error (task, error);
9458 * // If the task has already been cancelled, then we don't want to add
9459 * // the cake to the cake cache. Likewise, we don't want to have the
9460 * // task get cancelled in the middle of updating the cache.
9461 * // g_task_set_return_on_cancel() will return %TRUE here if it managed
9462 * // to disable return-on-cancel, or %FALSE if the task was cancelled
9463 * // before it could.
9464 * if (g_task_set_return_on_cancel (task, FALSE))
9466 * // If the caller cancels at this point, their
9467 * // GAsyncReadyCallback won't be invoked until we return,
9468 * // so we don't have to worry that this code will run at
9469 * // the same time as that code does. But if there were
9470 * // other functions that might look at the cake cache,
9471 * // then we'd probably need a GMutex here as well.
9472 * baker_add_cake_to_cache (baker, cake);
9473 * g_task_return_pointer (task, cake, g_object_unref);
9478 * baker_bake_cake_async (Baker *self,
9480 * CakeFlavor flavor,
9481 * CakeFrostingType frosting,
9482 * const char *message,
9483 * GCancellable *cancellable,
9484 * GAsyncReadyCallback callback,
9485 * gpointer user_data)
9487 * CakeData *cake_data;
9490 * cake_data = g_slice_new (CakeData);
9494 * task = g_task_new (self, cancellable, callback, user_data);
9495 * g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free);
9496 * g_task_set_return_on_cancel (task, TRUE);
9497 * g_task_run_in_thread (task, bake_cake_thread);
9501 * baker_bake_cake_sync (Baker *self,
9503 * CakeFlavor flavor,
9504 * CakeFrostingType frosting,
9505 * const char *message,
9506 * GCancellable *cancellable,
9509 * CakeData *cake_data;
9513 * cake_data = g_slice_new (CakeData);
9517 * task = g_task_new (self, cancellable, NULL, NULL);
9518 * g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free);
9519 * g_task_set_return_on_cancel (task, TRUE);
9520 * g_task_run_in_thread_sync (task, bake_cake_thread);
9522 * cake = g_task_propagate_pointer (task, error);
9523 * g_object_unref (task);
9528 * ## Porting from GSimpleAsyncResult
9530 * #GTask's API attempts to be simpler than #GSimpleAsyncResult's
9532 * - You can save task-specific data with g_task_set_task_data(), and
9533 * retrieve it later with g_task_get_task_data(). This replaces the
9534 * abuse of g_simple_async_result_set_op_res_gpointer() for the same
9535 * purpose with #GSimpleAsyncResult.
9536 * - In addition to the task data, #GTask also keeps track of the
9537 * [priority][io-priority], #GCancellable, and
9538 * #GMainContext associated with the task, so tasks that consist of
9539 * a chain of simpler asynchronous operations will have easy access
9540 * to those values when starting each sub-task.
9541 * - g_task_return_error_if_cancelled() provides simplified
9542 * handling for cancellation. In addition, cancellation
9543 * overrides any other #GTask return value by default, like
9544 * #GSimpleAsyncResult does when
9545 * g_simple_async_result_set_check_cancellable() is called.
9546 * (You can use g_task_set_check_cancellable() to turn off that
9547 * behavior.) On the other hand, g_task_run_in_thread()
9548 * guarantees that it will always run your
9549 * `task_func`, even if the task's #GCancellable
9550 * is already cancelled before the task gets a chance to run;
9551 * you can start your `task_func` with a
9552 * g_task_return_error_if_cancelled() check if you need the
9554 * - The "return" methods (eg, g_task_return_pointer())
9555 * automatically cause the task to be "completed" as well, and
9556 * there is no need to worry about the "complete" vs "complete
9557 * in idle" distinction. (#GTask automatically figures out
9558 * whether the task's callback can be invoked directly, or
9559 * if it needs to be sent to another #GMainContext, or delayed
9560 * until the next iteration of the current #GMainContext.)
9561 * - The "finish" functions for #GTask based operations are generally
9562 * much simpler than #GSimpleAsyncResult ones, normally consisting
9563 * of only a single call to g_task_propagate_pointer() or the like.
9564 * Since g_task_propagate_pointer() "steals" the return value from
9565 * the #GTask, it is not necessary to juggle pointers around to
9566 * prevent it from being freed twice.
9567 * - With #GSimpleAsyncResult, it was common to call
9568 * g_simple_async_result_propagate_error() from the
9569 * `_finish()` wrapper function, and have
9570 * virtual method implementations only deal with successful
9571 * returns. This behavior is deprecated, because it makes it
9572 * difficult for a subclass to chain to a parent class's async
9573 * methods. Instead, the wrapper function should just be a
9574 * simple wrapper, and the virtual method should call an
9575 * appropriate `g_task_propagate_` function.
9576 * Note that wrapper methods can now use
9577 * g_async_result_legacy_propagate_error() to do old-style
9578 * #GSimpleAsyncResult error-returning behavior, and
9579 * g_async_result_is_tagged() to check if a result is tagged as
9580 * having come from the `_async()` wrapper
9581 * function (for "short-circuit" results, such as when passing
9582 * 0 to g_input_stream_read_async()).
9587 * SECTION:gtcpconnection
9588 * @title: GTcpConnection
9589 * @short_description: A TCP GSocketConnection
9590 * @include: gio/gio.h
9591 * @see_also: #GSocketConnection.
9593 * This is the subclass of #GSocketConnection that is created
9594 * for TCP/IP sockets.
9601 * SECTION:gtcpwrapperconnection
9602 * @title: GTcpWrapperConnection
9603 * @short_description: Wrapper for non-GSocketConnection-based,
9604 * GSocket-based GIOStreams
9605 * @include: gio/gio.h
9606 * @see_also: #GSocketConnection.
9608 * A #GTcpWrapperConnection can be used to wrap a #GIOStream that is
9609 * based on a #GSocket, but which is not actually a
9610 * #GSocketConnection. This is used by #GSocketClient so that it can
9611 * always return a #GSocketConnection, even when the connection it has
9612 * actually created is not directly a #GSocketConnection.
9620 * @short_description: D-Bus testing helper
9621 * @include: gio/gio.h
9623 * A helper class for testing code which uses D-Bus without touching the user's
9626 * Note that #GTestDBus modifies the user’s environment, calling setenv().
9627 * This is not thread-safe, so all #GTestDBus calls should be completed before
9628 * threads are spawned, or should have appropriate locking to ensure no access
9629 * conflicts to environment variables shared between #GTestDBus and other
9632 * ## Creating unit tests using GTestDBus
9634 * Testing of D-Bus services can be tricky because normally we only ever run
9635 * D-Bus services over an existing instance of the D-Bus daemon thus we
9636 * usually don't activate D-Bus services that are not yet installed into the
9637 * target system. The #GTestDBus object makes this easier for us by taking care
9638 * of the lower level tasks such as running a private D-Bus daemon and looking
9639 * up uninstalled services in customizable locations, typically in your source
9642 * The first thing you will need is a separate service description file for the
9643 * D-Bus daemon. Typically a `services` subdirectory of your `tests` directory
9644 * is a good place to put this file.
9646 * The service file should list your service along with an absolute path to the
9647 * uninstalled service executable in your source tree. Using autotools we would
9648 * achieve this by adding a file such as `my-server.service.in` in the services
9649 * directory and have it processed by configure.
9652 * Name=org.gtk.GDBus.Examples.ObjectManager
9653 * Exec=@abs_top_builddir@/gio/tests/gdbus-example-objectmanager-server
9655 * You will also need to indicate this service directory in your test
9656 * fixtures, so you will need to pass the path while compiling your
9657 * test cases. Typically this is done with autotools with an added
9658 * preprocessor flag specified to compile your tests such as:
9660 * -DTEST_SERVICES=\""$(abs_top_builddir)/tests/services"\"
9662 * Once you have a service definition file which is local to your source tree,
9663 * you can proceed to set up a GTest fixture using the #GTestDBus scaffolding.
9665 * An example of a test fixture for D-Bus services can be found
9667 * [gdbus-test-fixture.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-test-fixture.c)
9669 * Note that these examples only deal with isolating the D-Bus aspect of your
9670 * service. To successfully run isolated unit tests on your service you may need
9671 * some additional modifications to your test case fixture. For example; if your
9672 * service uses GSettings and installs a schema then it is important that your test service
9673 * not load the schema in the ordinary installed location (chances are that your service
9674 * and schema files are not yet installed, or worse; there is an older version of the
9675 * schema file sitting in the install location).
9677 * Most of the time we can work around these obstacles using the
9678 * environment. Since the environment is inherited by the D-Bus daemon
9679 * created by #GTestDBus and then in turn inherited by any services the
9680 * D-Bus daemon activates, using the setup routine for your fixture is
9681 * a practical place to help sandbox your runtime environment. For the
9682 * rather typical GSettings case we can work around this by setting
9683 * `GSETTINGS_SCHEMA_DIR` to the in tree directory holding your schemas
9684 * in the above fixture_setup() routine.
9686 * The GSettings schemas need to be locally pre-compiled for this to work. This can be achieved
9687 * by compiling the schemas locally as a step before running test cases, an autotools setup might
9688 * do the following in the directory holding schemas:
9691 * $(GLIB_COMPILE_SCHEMAS) .
9693 * CLEANFILES += gschemas.compiled
9699 * SECTION:gthemedicon
9700 * @short_description: Icon theming support
9701 * @include: gio/gio.h
9702 * @see_also: #GIcon, #GLoadableIcon
9704 * #GThemedIcon is an implementation of #GIcon that supports icon themes.
9705 * #GThemedIcon contains a list of all of the icons present in an icon
9706 * theme, so that icons can be looked up quickly. #GThemedIcon does
9707 * not provide actual pixmaps for icons, just the icon names.
9708 * Ideally something like gtk_icon_theme_choose_icon() should be used to
9709 * resolve the list of names so that fallback icons work nicely with
9710 * themes that inherit other themes.
9715 * SECTION:gthreadedsocketservice
9716 * @title: GThreadedSocketService
9717 * @short_description: A threaded GSocketService
9718 * @include: gio/gio.h
9719 * @see_also: #GSocketService.
9721 * A #GThreadedSocketService is a simple subclass of #GSocketService
9722 * that handles incoming connections by creating a worker thread and
9723 * dispatching the connection to it by emitting the
9724 * #GThreadedSocketService::run signal in the new thread.
9726 * The signal handler may perform blocking IO and need not return
9727 * until the connection is closed.
9729 * The service is implemented using a thread pool, so there is a
9730 * limited amount of threads available to serve incoming requests.
9731 * The service automatically stops the #GSocketService from accepting
9732 * new connections when all threads are busy.
9734 * As with #GSocketService, you may connect to #GThreadedSocketService::run,
9735 * or subclass and override the default handler.
9741 * @title: TLS Overview
9742 * @short_description: TLS (aka SSL) support for GSocketConnection
9743 * @include: gio/gio.h
9745 * #GTlsConnection and related classes provide TLS (Transport Layer
9746 * Security, previously known as SSL, Secure Sockets Layer) support for
9747 * gio-based network streams.
9749 * #GDtlsConnection and related classes provide DTLS (Datagram TLS) support for
9750 * GIO-based network sockets, using the #GDatagramBased interface. The TLS and
9751 * DTLS APIs are almost identical, except TLS is stream-based and DTLS is
9752 * datagram-based. They share certificate and backend infrastructure.
9754 * In the simplest case, for a client TLS connection, you can just set the
9755 * #GSocketClient:tls flag on a #GSocketClient, and then any
9756 * connections created by that client will have TLS negotiated
9757 * automatically, using appropriate default settings, and rejecting
9758 * any invalid or self-signed certificates (unless you change that
9759 * default by setting the #GSocketClient:tls-validation-flags
9760 * property). The returned object will be a #GTcpWrapperConnection,
9761 * which wraps the underlying #GTlsClientConnection.
9763 * For greater control, you can create your own #GTlsClientConnection,
9764 * wrapping a #GSocketConnection (or an arbitrary #GIOStream with
9765 * pollable input and output streams) and then connect to its signals,
9766 * such as #GTlsConnection::accept-certificate, before starting the
9769 * Server-side TLS is similar, using #GTlsServerConnection. At the
9770 * moment, there is no support for automatically wrapping server-side
9771 * connections in the way #GSocketClient does for client-side
9777 * SECTION:gtlsbackend
9778 * @title: GTlsBackend
9779 * @short_description: TLS backend implementation
9780 * @include: gio/gio.h
9782 * TLS (Transport Layer Security, aka SSL) and DTLS backend.
9789 * SECTION:gtlscertificate
9790 * @title: GTlsCertificate
9791 * @short_description: TLS certificate
9792 * @include: gio/gio.h
9793 * @see_also: #GTlsConnection
9795 * A certificate used for TLS authentication and encryption.
9796 * This can represent either a certificate only (eg, the certificate
9797 * received by a client from a server), or the combination of
9798 * a certificate and a private key (which is needed when acting as a
9799 * #GTlsServerConnection).
9806 * SECTION:gtlsclientconnection
9807 * @short_description: TLS client-side connection
9808 * @include: gio/gio.h
9810 * #GTlsClientConnection is the client-side subclass of
9811 * #GTlsConnection, representing a client-side TLS connection.
9816 * SECTION:gtlsconnection
9817 * @short_description: TLS connection type
9818 * @include: gio/gio.h
9820 * #GTlsConnection is the base TLS connection class type, which wraps
9821 * a #GIOStream and provides TLS encryption on top of it. Its
9822 * subclasses, #GTlsClientConnection and #GTlsServerConnection,
9823 * implement client-side and server-side TLS, respectively.
9825 * For DTLS (Datagram TLS) support, see #GDtlsConnection.
9832 * SECTION:gtlsdatabase
9833 * @short_description: TLS database type
9834 * @include: gio/gio.h
9836 * #GTlsDatabase is used to look up certificates and other information
9837 * from a certificate or key store. It is an abstract base class which
9838 * TLS library specific subtypes override.
9840 * A #GTlsDatabase may be accessed from multiple threads by the TLS backend.
9841 * All implementations are required to be fully thread-safe.
9843 * Most common client applications will not directly interact with
9844 * #GTlsDatabase. It is used internally by #GTlsConnection.
9851 * SECTION:gtlsfiledatabase
9852 * @short_description: TLS file based database type
9853 * @include: gio/gio.h
9855 * #GTlsFileDatabase is implemented by #GTlsDatabase objects which load
9856 * their certificate information from a file. It is an interface which
9857 * TLS library specific subtypes implement.
9864 * SECTION:gtlsinteraction
9865 * @short_description: Interaction with the user during TLS operations.
9866 * @include: gio/gio.h
9868 * #GTlsInteraction provides a mechanism for the TLS connection and database
9869 * code to interact with the user. It can be used to ask the user for passwords.
9871 * To use a #GTlsInteraction with a TLS connection use
9872 * g_tls_connection_set_interaction().
9874 * Callers should instantiate a derived class that implements the various
9875 * interaction methods to show the required dialogs.
9877 * Callers should use the 'invoke' functions like
9878 * g_tls_interaction_invoke_ask_password() to run interaction methods. These
9879 * functions make sure that the interaction is invoked in the main loop
9880 * and not in the current thread, if the current thread is not running the
9883 * Derived classes can choose to implement whichever interactions methods they'd
9884 * like to support by overriding those virtual methods in their class
9885 * initialization function. Any interactions not implemented will return
9886 * %G_TLS_INTERACTION_UNHANDLED. If a derived class implements an async method,
9887 * it must also implement the corresponding finish method.
9892 * SECTION:gtlspassword
9893 * @title: GTlsPassword
9894 * @short_description: TLS Passwords for prompting
9895 * @include: gio/gio.h
9897 * Holds a password used in TLS.
9902 * SECTION:gtlsserverconnection
9903 * @short_description: TLS server-side connection
9904 * @include: gio/gio.h
9906 * #GTlsServerConnection is the server-side subclass of #GTlsConnection,
9907 * representing a server-side TLS connection.
9914 * SECTION:gunixconnection
9915 * @title: GUnixConnection
9916 * @short_description: A UNIX domain GSocketConnection
9917 * @include: gio/gunixconnection.h
9918 * @see_also: #GSocketConnection.
9920 * This is the subclass of #GSocketConnection that is created
9921 * for UNIX domain sockets.
9923 * It contains functions to do some of the UNIX socket specific
9924 * functionality like passing file descriptors.
9926 * Note that `<gio/gunixconnection.h>` belongs to the UNIX-specific
9927 * GIO interfaces, thus you have to use the `gio-unix-2.0.pc`
9928 * pkg-config file when using it.
9935 * SECTION:gunixcredentialsmessage
9936 * @title: GUnixCredentialsMessage
9937 * @short_description: A GSocketControlMessage containing credentials
9938 * @include: gio/gunixcredentialsmessage.h
9939 * @see_also: #GUnixConnection, #GSocketControlMessage
9941 * This #GSocketControlMessage contains a #GCredentials instance. It
9942 * may be sent using g_socket_send_message() and received using
9943 * g_socket_receive_message() over UNIX sockets (ie: sockets in the
9944 * %G_SOCKET_FAMILY_UNIX family).
9946 * For an easier way to send and receive credentials over
9947 * stream-oriented UNIX sockets, see
9948 * g_unix_connection_send_credentials() and
9949 * g_unix_connection_receive_credentials(). To receive credentials of
9950 * a foreign process connected to a socket, use
9951 * g_socket_get_credentials().
9956 * SECTION:gunixfdlist
9957 * @title: GUnixFDList
9958 * @short_description: An object containing a set of UNIX file descriptors
9959 * @include: gio/gunixfdlist.h
9960 * @see_also: #GUnixFDMessage
9962 * A #GUnixFDList contains a list of file descriptors. It owns the file
9963 * descriptors that it contains, closing them when finalized.
9965 * It may be wrapped in a #GUnixFDMessage and sent over a #GSocket in
9966 * the %G_SOCKET_FAMILY_UNIX family by using g_socket_send_message()
9967 * and received using g_socket_receive_message().
9969 * Note that `<gio/gunixfdlist.h>` belongs to the UNIX-specific GIO
9970 * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config
9971 * file when using it.
9976 * SECTION:gunixfdmessage
9977 * @title: GUnixFDMessage
9978 * @short_description: A GSocketControlMessage containing a GUnixFDList
9979 * @include: gio/gunixfdmessage.h
9980 * @see_also: #GUnixConnection, #GUnixFDList, #GSocketControlMessage
9982 * This #GSocketControlMessage contains a #GUnixFDList.
9983 * It may be sent using g_socket_send_message() and received using
9984 * g_socket_receive_message() over UNIX sockets (ie: sockets in the
9985 * %G_SOCKET_FAMILY_UNIX family). The file descriptors are copied
9986 * between processes by the kernel.
9988 * For an easier way to send and receive file descriptors over
9989 * stream-oriented UNIX sockets, see g_unix_connection_send_fd() and
9990 * g_unix_connection_receive_fd().
9992 * Note that `<gio/gunixfdmessage.h>` belongs to the UNIX-specific GIO
9993 * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config
9994 * file when using it.
9999 * SECTION:gunixinputstream
10000 * @short_description: Streaming input operations for UNIX file descriptors
10001 * @include: gio/gunixinputstream.h
10002 * @see_also: #GInputStream
10004 * #GUnixInputStream implements #GInputStream for reading from a UNIX
10005 * file descriptor, including asynchronous operations. (If the file
10006 * descriptor refers to a socket or pipe, this will use poll() to do
10007 * asynchronous I/O. If it refers to a regular file, it will fall back
10008 * to doing asynchronous I/O in another thread.)
10010 * Note that `<gio/gunixinputstream.h>` belongs to the UNIX-specific GIO
10011 * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config
10012 * file when using it.
10017 * SECTION:gunixmounts
10018 * @include: gio/gunixmounts.h
10019 * @short_description: UNIX mounts
10021 * Routines for managing mounted UNIX mount points and paths.
10023 * Note that `<gio/gunixmounts.h>` belongs to the UNIX-specific GIO
10024 * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config
10025 * file when using it.
10030 * SECTION:gunixoutputstream
10031 * @short_description: Streaming output operations for UNIX file descriptors
10032 * @include: gio/gunixoutputstream.h
10033 * @see_also: #GOutputStream
10035 * #GUnixOutputStream implements #GOutputStream for writing to a UNIX
10036 * file descriptor, including asynchronous operations. (If the file
10037 * descriptor refers to a socket or pipe, this will use poll() to do
10038 * asynchronous I/O. If it refers to a regular file, it will fall back
10039 * to doing asynchronous I/O in another thread.)
10041 * Note that `<gio/gunixoutputstream.h>` belongs to the UNIX-specific GIO
10042 * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config file
10048 * SECTION:gunixsocketaddress
10049 * @short_description: UNIX GSocketAddress
10050 * @include: gio/gunixsocketaddress.h
10052 * Support for UNIX-domain (also known as local) sockets.
10054 * UNIX domain sockets are generally visible in the filesystem.
10055 * However, some systems support abstract socket names which are not
10056 * visible in the filesystem and not affected by the filesystem
10057 * permissions, visibility, etc. Currently this is only supported
10058 * under Linux. If you attempt to use abstract sockets on other
10059 * systems, function calls may return %G_IO_ERROR_NOT_SUPPORTED
10060 * errors. You can use g_unix_socket_address_abstract_names_supported()
10061 * to see if abstract names are supported.
10063 * Note that `<gio/gunixsocketaddress.h>` belongs to the UNIX-specific GIO
10064 * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config file
10071 * @short_description: Virtual File System
10072 * @include: gio/gio.h
10074 * Entry point for using GIO functionality.
10080 * @short_description: Volume management
10081 * @include: gio/gio.h
10083 * The #GVolume interface represents user-visible objects that can be
10084 * mounted. Note, when porting from GnomeVFS, #GVolume is the moral
10085 * equivalent of #GnomeVFSDrive.
10087 * Mounting a #GVolume instance is an asynchronous operation. For more
10088 * information about asynchronous operations, see #GAsyncResult and
10089 * #GTask. To mount a #GVolume, first call g_volume_mount() with (at
10090 * least) the #GVolume instance, optionally a #GMountOperation object
10091 * and a #GAsyncReadyCallback.
10093 * Typically, one will only want to pass %NULL for the
10094 * #GMountOperation if automounting all volumes when a desktop session
10095 * starts since it's not desirable to put up a lot of dialogs asking
10098 * The callback will be fired when the operation has resolved (either
10099 * with success or failure), and a #GAsyncResult instance will be
10100 * passed to the callback. That callback should then call
10101 * g_volume_mount_finish() with the #GVolume instance and the
10102 * #GAsyncResult data to see if the operation was completed
10103 * successfully. If an @error is present when g_volume_mount_finish()
10104 * is called, then it will be filled with any error information.
10106 * ## Volume Identifiers # {#volume-identifier}
10108 * It is sometimes necessary to directly access the underlying
10109 * operating system object behind a volume (e.g. for passing a volume
10110 * to an application via the commandline). For this purpose, GIO
10111 * allows to obtain an 'identifier' for the volume. There can be
10112 * different kinds of identifiers, such as Hal UDIs, filesystem labels,
10113 * traditional Unix devices (e.g. `/dev/sda2`), UUIDs. GIO uses predefined
10114 * strings as names for the different kinds of identifiers:
10115 * #G_VOLUME_IDENTIFIER_KIND_UUID, #G_VOLUME_IDENTIFIER_KIND_LABEL, etc.
10116 * Use g_volume_get_identifier() to obtain an identifier for a volume.
10119 * Note that #G_VOLUME_IDENTIFIER_KIND_HAL_UDI will only be available
10120 * when the gvfs hal volume monitor is in use. Other volume monitors
10121 * will generally be able to provide the #G_VOLUME_IDENTIFIER_KIND_UNIX_DEVICE
10122 * identifier, which can be used to obtain a hal device by means of
10123 * libhal_manager_find_device_string_match().
10128 * SECTION:gvolumemonitor
10129 * @short_description: Volume Monitor
10130 * @include: gio/gio.h
10131 * @see_also: #GFileMonitor
10133 * #GVolumeMonitor is for listing the user interesting devices and volumes
10134 * on the computer. In other words, what a file selector or file manager
10135 * would show in a sidebar.
10137 * #GVolumeMonitor is not
10138 * [thread-default-context aware][g-main-context-push-thread-default],
10139 * and so should not be used other than from the main thread, with no
10140 * thread-default-context active.
10142 * In order to receive updates about volumes and mounts monitored through GVFS,
10143 * a main loop must be running.
10148 * SECTION:gwin32inputstream
10149 * @short_description: Streaming input operations for Windows file handles
10150 * @include: gio/gwin32inputstream.h
10151 * @see_also: #GInputStream
10153 * #GWin32InputStream implements #GInputStream for reading from a
10154 * Windows file handle.
10156 * Note that `<gio/gwin32inputstream.h>` belongs to the Windows-specific GIO
10157 * interfaces, thus you have to use the `gio-windows-2.0.pc` pkg-config file
10163 * SECTION:gwin32outputstream
10164 * @short_description: Streaming output operations for Windows file handles
10165 * @include: gio/gwin32outputstream.h
10166 * @see_also: #GOutputStream
10168 * #GWin32OutputStream implements #GOutputStream for writing to a
10169 * Windows file handle.
10171 * Note that `<gio/gwin32outputstream.h>` belongs to the Windows-specific GIO
10172 * interfaces, thus you have to use the `gio-windows-2.0.pc` pkg-config file
10178 * SECTION:gwin32registrykey
10179 * @title: GWin32RegistryKey
10180 * @short_description: W32 registry access helper
10181 * @include: gio/win32/gwin32registrykey.h
10183 * #GWin32RegistryKey represents a single Windows Registry key.
10185 * #GWin32RegistryKey is used by a number of helper functions that read
10186 * Windows Registry. All keys are opened with read-only access, and at
10187 * the moment there is no API for writing into registry keys or creating
10190 * #GWin32RegistryKey implements the #GInitable interface, so if it is manually
10191 * constructed by e.g. g_object_new() you must call g_initable_init() and check
10192 * the results before using the object. This is done automatically
10193 * in g_win32_registry_key_new() and g_win32_registry_key_get_child(), so these
10194 * functions can return %NULL.
10196 * To increase efficiency, a UTF-16 variant is available for all functions
10197 * that deal with key or value names in the registry. Use these to perform
10198 * deep registry queries or other operations that require querying a name
10199 * of a key or a value and then opening it (or querying its data). The use
10200 * of UTF-16 functions avoids the overhead of converting names to UTF-8 and
10203 * All functions operate in current user's context (it is not possible to
10204 * access registry tree of a different user).
10206 * Key paths must use '\\' as a separator, '/' is not supported. Key names
10207 * must not include '\\', because it's used as a separator. Value names
10208 * can include '\\'.
10210 * Key and value names are not case sensitive.
10212 * Full key name (excluding the pre-defined ancestor's name) can't exceed
10213 * 255 UTF-16 characters, give or take. Value name can't exceed 16383 UTF-16
10214 * characters. Tree depth is limited to 512 levels.
10219 * SECTION:gzlibcompressor
10220 * @short_description: Zlib compressor
10221 * @include: gio/gio.h
10223 * #GZlibCompressor is an implementation of #GConverter that
10224 * compresses data using zlib.
10229 * SECTION:gzlibdecompressor
10230 * @short_description: Zlib decompressor
10231 * @include: gio/gio.h
10233 * #GZlibDecompressor is an implementation of #GConverter that
10234 * decompresses data compressed with zlib.
10239 * _g_dbus_initialize:
10241 * Does various one-time init things such as
10243 * - registering the G_DBUS_ERROR error domain
10244 * - parses the G_DBUS_DEBUG environment variable
10249 * _g_file_attribute_value_as_string:
10250 * @attr: a #GFileAttributeValue.
10252 * Converts a #GFileAttributeValue to a string for display.
10253 * The returned string should be freed when no longer needed.
10255 * Returns: a string from the @attr, %NULL on error, or "<invalid>"
10256 * if @attr is of type %G_FILE_ATTRIBUTE_TYPE_INVALID.
10261 * _g_file_attribute_value_clear:
10262 * @attr: a #GFileAttributeValue.
10264 * Clears the value of @attr and sets its type to
10265 * %G_FILE_ATTRIBUTE_TYPE_INVALID.
10270 * _g_file_attribute_value_free:
10271 * @attr: a #GFileAttributeValue.
10273 * Frees the memory used by @attr.
10278 * _g_file_attribute_value_get_boolean:
10279 * @attr: a #GFileAttributeValue.
10281 * Gets the boolean value from a file attribute value. If the value is not the
10282 * right type then %FALSE will be returned.
10284 * Returns: the boolean value contained within the attribute, or %FALSE.
10289 * _g_file_attribute_value_get_byte_string:
10290 * @attr: a #GFileAttributeValue.
10292 * Gets the byte string from a file attribute value. If the value is not the
10293 * right type then %NULL will be returned.
10295 * Returns: the byte string contained within the attribute or %NULL.
10300 * _g_file_attribute_value_get_int32:
10301 * @attr: a #GFileAttributeValue.
10303 * Gets the signed 32-bit integer from a file attribute value. If the value
10304 * is not the right type then 0 will be returned.
10306 * Returns: the signed 32-bit integer from the attribute, or 0.
10311 * _g_file_attribute_value_get_int64:
10312 * @attr: a #GFileAttributeValue.
10314 * Gets the signed 64-bit integer from a file attribute value. If the value
10315 * is not the right type then 0 will be returned.
10317 * Returns: the signed 64-bit integer from the attribute, or 0.
10322 * _g_file_attribute_value_get_object:
10323 * @attr: a #GFileAttributeValue.
10325 * Gets the GObject from a file attribute value. If the value
10326 * is not the right type then %NULL will be returned.
10328 * Returns: the GObject from the attribute, or %NULL.
10333 * _g_file_attribute_value_get_string:
10334 * @attr: a #GFileAttributeValue.
10336 * Gets the string from a file attribute value. If the value is not the
10337 * right type then %NULL will be returned.
10339 * Returns: the UTF-8 string value contained within the attribute, or %NULL.
10344 * _g_file_attribute_value_get_uint32:
10345 * @attr: a #GFileAttributeValue.
10347 * Gets the unsigned 32-bit integer from a file attribute value. If the value
10348 * is not the right type then 0 will be returned.
10350 * Returns: the unsigned 32-bit integer from the attribute, or 0.
10355 * _g_file_attribute_value_get_uint64:
10356 * @attr: a #GFileAttributeValue.
10358 * Gets the unsigned 64-bit integer from a file attribute value. If the value
10359 * is not the right type then 0 will be returned.
10361 * Returns: the unsigned 64-bit integer from the attribute, or 0.
10366 * _g_file_attribute_value_new:
10368 * Creates a new file attribute.
10370 * Returns: a #GFileAttributeValue.
10375 * _g_file_attribute_value_set_boolean:
10376 * @attr: a #GFileAttributeValue.
10377 * @value: a #gboolean to set within the type.
10379 * Sets the attribute value to the given boolean value.
10384 * _g_file_attribute_value_set_byte_string:
10385 * @attr: a #GFileAttributeValue.
10386 * @string: a byte string to set within the type.
10388 * Sets the attribute value to a given byte string.
10393 * _g_file_attribute_value_set_int32:
10394 * @attr: a #GFileAttributeValue.
10395 * @value: a #gint32 to set within the type.
10397 * Sets the attribute value to the given signed 32-bit integer.
10402 * _g_file_attribute_value_set_int64:
10403 * @attr: a #GFileAttributeValue.
10404 * @value: a #gint64 to set within the type.
10406 * Sets the attribute value to a given signed 64-bit integer.
10411 * _g_file_attribute_value_set_object:
10412 * @attr: a #GFileAttributeValue.
10413 * @obj: a #GObject.
10415 * Sets the attribute to contain the value @obj.
10416 * The @attr references the GObject internally.
10421 * _g_file_attribute_value_set_string:
10422 * @attr: a #GFileAttributeValue.
10423 * @string: a UTF-8 string to set within the type.
10425 * Sets the attribute value to a given UTF-8 string.
10430 * _g_file_attribute_value_set_uint32:
10431 * @attr: a #GFileAttributeValue.
10432 * @value: a #guint32 to set within the type.
10434 * Sets the attribute value to the given unsigned 32-bit integer.
10439 * _g_file_attribute_value_set_uint64:
10440 * @attr: a #GFileAttributeValue.
10441 * @value: a #guint64 to set within the type.
10443 * Sets the attribute value to a given unsigned 64-bit integer.
10448 * _g_io_module_extract_name:
10449 * @filename: filename of a GIOModule
10451 * Extract the plugin name from its filename. It removes optional "lib" or
10452 * "libgio" prefix, and removes everything after the first dot. For example:
10453 * "libgiognutls.so" -> "gnutls".
10455 * Returns: (transfer full): the module's name
10460 * _g_io_module_get_default:
10461 * @extension_point: the name of an extension point
10462 * @envvar: (nullable): the name of an environment variable to
10463 * override the default implementation.
10464 * @verify_func: (nullable): a function to call to verify that
10465 * a given implementation is usable in the current environment.
10467 * Retrieves the default object implementing @extension_point.
10469 * If @envvar is not %NULL, and the environment variable with that
10470 * name is set, then the implementation it specifies will be tried
10471 * first. After that, or if @envvar is not set, all other
10472 * implementations will be tried in order of decreasing priority.
10474 * If an extension point implementation implements #GInitable, then
10475 * that implementation will only be used if it initializes
10476 * successfully. Otherwise, if @verify_func is not %NULL, then it will
10477 * be called on each candidate implementation after construction, to
10478 * check if it is actually usable or not.
10480 * The result is cached after it is generated the first time (but the cache does
10481 * not keep a strong reference to the object), and
10482 * the function is thread-safe.
10484 * Returns: (transfer full) (nullable): an object implementing
10485 * @extension_point, or %NULL if there are no usable
10491 * _g_io_module_get_default_type:
10492 * @extension_point: the name of an extension point
10493 * @envvar: (nullable): the name of an environment variable to
10494 * override the default implementation.
10495 * @is_supported_offset: a vtable offset, or zero
10497 * Retrieves the default class implementing @extension_point.
10499 * If @envvar is not %NULL, and the environment variable with that
10500 * name is set, then the implementation it specifies will be tried
10501 * first. After that, or if @envvar is not set, all other
10502 * implementations will be tried in order of decreasing priority.
10504 * If @is_supported_offset is non-zero, then it is the offset into the
10505 * class vtable at which there is a function that takes no arguments and
10506 * returns a boolean. This function will be called on each candidate
10507 * implementation to check if it is actually usable or not.
10509 * The result is cached after it is generated the first time, and
10510 * the function is thread-safe.
10512 * Returns: (transfer none): the type to instantiate to implement
10513 * @extension_point, or %G_TYPE_INVALID if there are no usable
10519 * _g_poll_file_monitor_new:
10522 * Polls @file for changes.
10524 * Returns: a new #GFileMonitor for the given #GFile.
10529 * g_action_activate:
10530 * @action: a #GAction
10531 * @parameter: (nullable): the parameter to the activation
10533 * Activates the action.
10535 * @parameter must be the correct type of parameter for the action (ie:
10536 * the parameter type given at construction time). If the parameter
10537 * type was %NULL then @parameter must also be %NULL.
10539 * If the @parameter GVariant is floating, it is consumed.
10546 * g_action_change_state:
10547 * @action: a #GAction
10548 * @value: the new state
10550 * Request for the state of @action to be changed to @value.
10552 * The action must be stateful and @value must be of the correct type.
10553 * See g_action_get_state_type().
10555 * This call merely requests a change. The action may refuse to change
10556 * its state or may change its state to something other than @value.
10557 * See g_action_get_state_hint().
10559 * If the @value GVariant is floating, it is consumed.
10566 * g_action_get_enabled:
10567 * @action: a #GAction
10569 * Checks if @action is currently enabled.
10571 * An action must be enabled in order to be activated or in order to
10572 * have its state changed from outside callers.
10574 * Returns: whether the action is enabled
10580 * g_action_get_name:
10581 * @action: a #GAction
10583 * Queries the name of @action.
10585 * Returns: the name of the action
10591 * g_action_get_parameter_type:
10592 * @action: a #GAction
10594 * Queries the type of the parameter that must be given when activating
10597 * When activating the action using g_action_activate(), the #GVariant
10598 * given to that function must be of the type returned by this function.
10600 * In the case that this function returns %NULL, you must not give any
10601 * #GVariant, but %NULL instead.
10603 * Returns: (nullable): the parameter type
10609 * g_action_get_state:
10610 * @action: a #GAction
10612 * Queries the current state of @action.
10614 * If the action is not stateful then %NULL will be returned. If the
10615 * action is stateful then the type of the return value is the type
10616 * given by g_action_get_state_type().
10618 * The return value (if non-%NULL) should be freed with
10619 * g_variant_unref() when it is no longer required.
10621 * Returns: (nullable) (transfer full): the current state of the action
10627 * g_action_get_state_hint:
10628 * @action: a #GAction
10630 * Requests a hint about the valid range of values for the state of
10633 * If %NULL is returned it either means that the action is not stateful
10634 * or that there is no hint about the valid range of values for the
10635 * state of the action.
10637 * If a #GVariant array is returned then each item in the array is a
10638 * possible value for the state. If a #GVariant pair (ie: two-tuple) is
10639 * returned then the tuple specifies the inclusive lower and upper bound
10640 * of valid values for the state.
10642 * In any case, the information is merely a hint. It may be possible to
10643 * have a state value outside of the hinted range and setting a value
10644 * within the range may fail.
10646 * The return value (if non-%NULL) should be freed with
10647 * g_variant_unref() when it is no longer required.
10649 * Returns: (nullable) (transfer full): the state range hint
10655 * g_action_get_state_type:
10656 * @action: a #GAction
10658 * Queries the type of the state of @action.
10660 * If the action is stateful (e.g. created with
10661 * g_simple_action_new_stateful()) then this function returns the
10662 * #GVariantType of the state. This is the type of the initial value
10663 * given as the state. All calls to g_action_change_state() must give a
10664 * #GVariant of this type and g_action_get_state() will return a
10665 * #GVariant of the same type.
10667 * If the action is not stateful (e.g. created with g_simple_action_new())
10668 * then this function will return %NULL. In that case, g_action_get_state()
10669 * will return %NULL and you must not call g_action_change_state().
10671 * Returns: (nullable): the state type, if the action is stateful
10677 * g_action_group_action_added:
10678 * @action_group: a #GActionGroup
10679 * @action_name: the name of an action in the group
10681 * Emits the #GActionGroup::action-added signal on @action_group.
10683 * This function should only be called by #GActionGroup implementations.
10690 * g_action_group_action_enabled_changed:
10691 * @action_group: a #GActionGroup
10692 * @action_name: the name of an action in the group
10693 * @enabled: whether or not the action is now enabled
10695 * Emits the #GActionGroup::action-enabled-changed signal on @action_group.
10697 * This function should only be called by #GActionGroup implementations.
10704 * g_action_group_action_removed:
10705 * @action_group: a #GActionGroup
10706 * @action_name: the name of an action in the group
10708 * Emits the #GActionGroup::action-removed signal on @action_group.
10710 * This function should only be called by #GActionGroup implementations.
10717 * g_action_group_action_state_changed:
10718 * @action_group: a #GActionGroup
10719 * @action_name: the name of an action in the group
10720 * @state: the new state of the named action
10722 * Emits the #GActionGroup::action-state-changed signal on @action_group.
10724 * This function should only be called by #GActionGroup implementations.
10731 * g_action_group_activate_action:
10732 * @action_group: a #GActionGroup
10733 * @action_name: the name of the action to activate
10734 * @parameter: (nullable): parameters to the activation
10736 * Activate the named action within @action_group.
10738 * If the action is expecting a parameter, then the correct type of
10739 * parameter must be given as @parameter. If the action is expecting no
10740 * parameters then @parameter must be %NULL. See
10741 * g_action_group_get_action_parameter_type().
10743 * If the #GActionGroup implementation supports asynchronous remote
10744 * activation over D-Bus, this call may return before the relevant
10745 * D-Bus traffic has been sent, or any replies have been received. In
10746 * order to block on such asynchronous activation calls,
10747 * g_dbus_connection_flush() should be called prior to the code, which
10748 * depends on the result of the action activation. Without flushing
10749 * the D-Bus connection, there is no guarantee that the action would
10750 * have been activated.
10752 * The following code which runs in a remote app instance, shows an
10753 * example of a "quit" action being activated on the primary app
10754 * instance over D-Bus. Here g_dbus_connection_flush() is called
10755 * before `exit()`. Without g_dbus_connection_flush(), the "quit" action
10756 * may fail to be activated on the primary instance.
10758 * |[<!-- language="C" -->
10759 * // call "quit" action on primary instance
10760 * g_action_group_activate_action (G_ACTION_GROUP (app), "quit", NULL);
10762 * // make sure the action is activated now
10763 * g_dbus_connection_flush (...);
10765 * g_debug ("application has been terminated. exiting.");
10775 * g_action_group_change_action_state:
10776 * @action_group: a #GActionGroup
10777 * @action_name: the name of the action to request the change on
10778 * @value: the new state
10780 * Request for the state of the named action within @action_group to be
10781 * changed to @value.
10783 * The action must be stateful and @value must be of the correct type.
10784 * See g_action_group_get_action_state_type().
10786 * This call merely requests a change. The action may refuse to change
10787 * its state or may change its state to something other than @value.
10788 * See g_action_group_get_action_state_hint().
10790 * If the @value GVariant is floating, it is consumed.
10797 * g_action_group_get_action_enabled:
10798 * @action_group: a #GActionGroup
10799 * @action_name: the name of the action to query
10801 * Checks if the named action within @action_group is currently enabled.
10803 * An action must be enabled in order to be activated or in order to
10804 * have its state changed from outside callers.
10806 * Returns: whether or not the action is currently enabled
10812 * g_action_group_get_action_parameter_type:
10813 * @action_group: a #GActionGroup
10814 * @action_name: the name of the action to query
10816 * Queries the type of the parameter that must be given when activating
10817 * the named action within @action_group.
10819 * When activating the action using g_action_group_activate_action(),
10820 * the #GVariant given to that function must be of the type returned
10821 * by this function.
10823 * In the case that this function returns %NULL, you must not give any
10824 * #GVariant, but %NULL instead.
10826 * The parameter type of a particular action will never change but it is
10827 * possible for an action to be removed and for a new action to be added
10828 * with the same name but a different parameter type.
10830 * Returns: (nullable): the parameter type
10836 * g_action_group_get_action_state:
10837 * @action_group: a #GActionGroup
10838 * @action_name: the name of the action to query
10840 * Queries the current state of the named action within @action_group.
10842 * If the action is not stateful then %NULL will be returned. If the
10843 * action is stateful then the type of the return value is the type
10844 * given by g_action_group_get_action_state_type().
10846 * The return value (if non-%NULL) should be freed with
10847 * g_variant_unref() when it is no longer required.
10849 * Returns: (nullable) (transfer full): the current state of the action
10855 * g_action_group_get_action_state_hint:
10856 * @action_group: a #GActionGroup
10857 * @action_name: the name of the action to query
10859 * Requests a hint about the valid range of values for the state of the
10860 * named action within @action_group.
10862 * If %NULL is returned it either means that the action is not stateful
10863 * or that there is no hint about the valid range of values for the
10864 * state of the action.
10866 * If a #GVariant array is returned then each item in the array is a
10867 * possible value for the state. If a #GVariant pair (ie: two-tuple) is
10868 * returned then the tuple specifies the inclusive lower and upper bound
10869 * of valid values for the state.
10871 * In any case, the information is merely a hint. It may be possible to
10872 * have a state value outside of the hinted range and setting a value
10873 * within the range may fail.
10875 * The return value (if non-%NULL) should be freed with
10876 * g_variant_unref() when it is no longer required.
10878 * Returns: (nullable) (transfer full): the state range hint
10884 * g_action_group_get_action_state_type:
10885 * @action_group: a #GActionGroup
10886 * @action_name: the name of the action to query
10888 * Queries the type of the state of the named action within
10891 * If the action is stateful then this function returns the
10892 * #GVariantType of the state. All calls to
10893 * g_action_group_change_action_state() must give a #GVariant of this
10894 * type and g_action_group_get_action_state() will return a #GVariant
10895 * of the same type.
10897 * If the action is not stateful then this function will return %NULL.
10898 * In that case, g_action_group_get_action_state() will return %NULL
10899 * and you must not call g_action_group_change_action_state().
10901 * The state type of a particular action will never change but it is
10902 * possible for an action to be removed and for a new action to be added
10903 * with the same name but a different state type.
10905 * Returns: (nullable): the state type, if the action is stateful
10911 * g_action_group_has_action:
10912 * @action_group: a #GActionGroup
10913 * @action_name: the name of the action to check for
10915 * Checks if the named action exists within @action_group.
10917 * Returns: whether the named action exists
10923 * g_action_group_list_actions:
10924 * @action_group: a #GActionGroup
10926 * Lists the actions contained within @action_group.
10928 * The caller is responsible for freeing the list with g_strfreev() when
10929 * it is no longer required.
10931 * Returns: (transfer full): a %NULL-terminated array of the names of the
10932 * actions in the group
10938 * g_action_group_query_action:
10939 * @action_group: a #GActionGroup
10940 * @action_name: the name of an action in the group
10941 * @enabled: (out): if the action is presently enabled
10942 * @parameter_type: (out) (optional): the parameter type, or %NULL if none needed
10943 * @state_type: (out) (optional): the state type, or %NULL if stateless
10944 * @state_hint: (out) (optional): the state hint, or %NULL if none
10945 * @state: (out) (optional): the current state, or %NULL if stateless
10947 * Queries all aspects of the named action within an @action_group.
10949 * This function acquires the information available from
10950 * g_action_group_has_action(), g_action_group_get_action_enabled(),
10951 * g_action_group_get_action_parameter_type(),
10952 * g_action_group_get_action_state_type(),
10953 * g_action_group_get_action_state_hint() and
10954 * g_action_group_get_action_state() with a single function call.
10956 * This provides two main benefits.
10958 * The first is the improvement in efficiency that comes with not having
10959 * to perform repeated lookups of the action in order to discover
10960 * different things about it. The second is that implementing
10961 * #GActionGroup can now be done by only overriding this one virtual
10964 * The interface provides a default implementation of this function that
10965 * calls the individual functions, as required, to fetch the
10966 * information. The interface also provides default implementations of
10967 * those functions that call this function. All implementations,
10968 * therefore, must override either this function or all of the others.
10970 * If the action exists, %TRUE is returned and any of the requested
10971 * fields (as indicated by having a non-%NULL reference passed in) are
10972 * filled. If the action doesn't exist, %FALSE is returned and the
10973 * fields may or may not have been modified.
10975 * Returns: %TRUE if the action exists, else %FALSE
10981 * g_action_map_add_action:
10982 * @action_map: a #GActionMap
10983 * @action: a #GAction
10985 * Adds an action to the @action_map.
10987 * If the action map already contains an action with the same name
10988 * as @action then the old action is dropped from the action map.
10990 * The action map takes its own reference on @action.
10997 * g_action_map_add_action_entries:
10998 * @action_map: a #GActionMap
10999 * @entries: (array length=n_entries) (element-type GActionEntry): a pointer to
11000 * the first item in an array of #GActionEntry structs
11001 * @n_entries: the length of @entries, or -1 if @entries is %NULL-terminated
11002 * @user_data: the user data for signal connections
11004 * A convenience function for creating multiple #GSimpleAction instances
11005 * and adding them to a #GActionMap.
11007 * Each action is constructed as per one #GActionEntry.
11009 * |[<!-- language="C" -->
11011 * activate_quit (GSimpleAction *simple,
11012 * GVariant *parameter,
11013 * gpointer user_data)
11019 * activate_print_string (GSimpleAction *simple,
11020 * GVariant *parameter,
11021 * gpointer user_data)
11023 * g_print ("%s\n", g_variant_get_string (parameter, NULL));
11026 * static GActionGroup *
11027 * create_action_group (void)
11029 * const GActionEntry entries[] = {
11030 * { "quit", activate_quit },
11031 * { "print-string", activate_print_string, "s" }
11033 * GSimpleActionGroup *group;
11035 * group = g_simple_action_group_new ();
11036 * g_action_map_add_action_entries (G_ACTION_MAP (group), entries, G_N_ELEMENTS (entries), NULL);
11038 * return G_ACTION_GROUP (group);
11047 * g_action_map_lookup_action:
11048 * @action_map: a #GActionMap
11049 * @action_name: the name of an action
11051 * Looks up the action with the name @action_name in @action_map.
11053 * If no such action exists, returns %NULL.
11055 * Returns: (nullable) (transfer none): a #GAction, or %NULL
11061 * g_action_map_remove_action:
11062 * @action_map: a #GActionMap
11063 * @action_name: the name of the action
11065 * Removes the named action from the action map.
11067 * If no action of this name is in the map then nothing happens.
11074 * g_action_name_is_valid:
11075 * @action_name: a potential action name
11077 * Checks if @action_name is valid.
11079 * @action_name is valid if it consists only of alphanumeric characters,
11080 * plus '-' and '.'. The empty string is not a valid action name.
11082 * It is an error to call this function with a non-utf8 @action_name.
11083 * @action_name must not be %NULL.
11085 * Returns: %TRUE if @action_name is valid
11091 * g_action_parse_detailed_name:
11092 * @detailed_name: a detailed action name
11093 * @action_name: (out): the action name
11094 * @target_value: (out): the target value, or %NULL for no target
11095 * @error: a pointer to a %NULL #GError, or %NULL
11097 * Parses a detailed action name into its separate name and target
11100 * Detailed action names can have three formats.
11102 * The first format is used to represent an action name with no target
11103 * value and consists of just an action name containing no whitespace
11104 * nor the characters ':', '(' or ')'. For example: "app.action".
11106 * The second format is used to represent an action with a target value
11107 * that is a non-empty string consisting only of alphanumerics, plus '-'
11108 * and '.'. In that case, the action name and target value are
11109 * separated by a double colon ("::"). For example:
11110 * "app.action::target".
11112 * The third format is used to represent an action with any type of
11113 * target value, including strings. The target value follows the action
11114 * name, surrounded in parens. For example: "app.action(42)". The
11115 * target value is parsed using g_variant_parse(). If a tuple-typed
11116 * value is desired, it must be specified in the same way, resulting in
11117 * two sets of parens, for example: "app.action((1,2,3))". A string
11118 * target can be specified this way as well: "app.action('target')".
11119 * For strings, this third format must be used if * target value is
11120 * empty or contains characters other than alphanumerics, '-' and '.'.
11122 * Returns: %TRUE if successful, else %FALSE with @error set
11128 * g_action_print_detailed_name:
11129 * @action_name: a valid action name
11130 * @target_value: (nullable): a #GVariant target value, or %NULL
11132 * Formats a detailed action name from @action_name and @target_value.
11134 * It is an error to call this function with an invalid action name.
11136 * This function is the opposite of g_action_parse_detailed_name().
11137 * It will produce a string that can be parsed back to the @action_name
11138 * and @target_value by that function.
11140 * See that function for the types of strings that will be printed by
11143 * Returns: a detailed format string
11149 * g_app_info_add_supports_type:
11150 * @appinfo: a #GAppInfo.
11151 * @content_type: a string.
11152 * @error: a #GError.
11154 * Adds a content type to the application information to indicate the
11155 * application is capable of opening files with the given content type.
11157 * Returns: %TRUE on success, %FALSE on error.
11162 * g_app_info_can_delete:
11163 * @appinfo: a #GAppInfo
11165 * Obtains the information whether the #GAppInfo can be deleted.
11166 * See g_app_info_delete().
11168 * Returns: %TRUE if @appinfo can be deleted
11174 * g_app_info_can_remove_supports_type:
11175 * @appinfo: a #GAppInfo.
11177 * Checks if a supported content type can be removed from an application.
11179 * Returns: %TRUE if it is possible to remove supported
11180 * content types from a given @appinfo, %FALSE if not.
11185 * g_app_info_create_from_commandline:
11186 * @commandline: (type filename): the commandline to use
11187 * @application_name: (nullable): the application name, or %NULL to use @commandline
11188 * @flags: flags that can specify details of the created #GAppInfo
11189 * @error: a #GError location to store the error occurring, %NULL to ignore.
11191 * Creates a new #GAppInfo from the given information.
11193 * Note that for @commandline, the quoting rules of the Exec key of the
11194 * [freedesktop.org Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec)
11195 * are applied. For example, if the @commandline contains
11196 * percent-encoded URIs, the percent-character must be doubled in order to prevent it from
11197 * being swallowed by Exec key unquoting. See the specification for exact quoting rules.
11199 * Returns: (transfer full): new #GAppInfo for given command.
11204 * g_app_info_delete: (virtual do_delete)
11205 * @appinfo: a #GAppInfo
11207 * Tries to delete a #GAppInfo.
11209 * On some platforms, there may be a difference between user-defined
11210 * #GAppInfos which can be deleted, and system-wide ones which cannot.
11211 * See g_app_info_can_delete().
11213 * Returns: %TRUE if @appinfo has been deleted
11220 * @appinfo: a #GAppInfo.
11222 * Creates a duplicate of a #GAppInfo.
11224 * Returns: (transfer full): a duplicate of @appinfo.
11229 * g_app_info_equal:
11230 * @appinfo1: the first #GAppInfo.
11231 * @appinfo2: the second #GAppInfo.
11233 * Checks if two #GAppInfos are equal.
11235 * Note that the check *may not* compare each individual
11236 * field, and only does an identity check. In case detecting changes in the
11237 * contents is needed, program code must additionally compare relevant fields.
11239 * Returns: %TRUE if @appinfo1 is equal to @appinfo2. %FALSE otherwise.
11244 * g_app_info_get_all:
11246 * Gets a list of all of the applications currently registered
11249 * For desktop files, this includes applications that have
11250 * `NoDisplay=true` set or are excluded from display by means
11251 * of `OnlyShowIn` or `NotShowIn`. See g_app_info_should_show().
11252 * The returned list does not include applications which have
11253 * the `Hidden` key set.
11255 * Returns: (element-type GAppInfo) (transfer full): a newly allocated #GList of references to #GAppInfos.
11260 * g_app_info_get_all_for_type:
11261 * @content_type: the content type to find a #GAppInfo for
11263 * Gets a list of all #GAppInfos for a given content type,
11264 * including the recommended and fallback #GAppInfos. See
11265 * g_app_info_get_recommended_for_type() and
11266 * g_app_info_get_fallback_for_type().
11268 * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos
11269 * for given @content_type or %NULL on error.
11274 * g_app_info_get_commandline: (virtual get_commandline)
11275 * @appinfo: a #GAppInfo
11277 * Gets the commandline with which the application will be
11280 * Returns: (nullable) (type filename): a string containing the @appinfo's commandline,
11281 * or %NULL if this information is not available
11287 * g_app_info_get_default_for_type:
11288 * @content_type: the content type to find a #GAppInfo for
11289 * @must_support_uris: if %TRUE, the #GAppInfo is expected to
11292 * Gets the default #GAppInfo for a given content type.
11294 * Returns: (transfer full) (nullable): #GAppInfo for given @content_type or
11300 * g_app_info_get_default_for_uri_scheme:
11301 * @uri_scheme: a string containing a URI scheme.
11303 * Gets the default application for handling URIs with
11304 * the given URI scheme. A URI scheme is the initial part
11305 * of the URI, up to but not including the ':', e.g. "http",
11308 * Returns: (transfer full) (nullable): #GAppInfo for given @uri_scheme or
11314 * g_app_info_get_description:
11315 * @appinfo: a #GAppInfo.
11317 * Gets a human-readable description of an installed application.
11319 * Returns: (nullable): a string containing a description of the
11320 * application @appinfo, or %NULL if none.
11325 * g_app_info_get_display_name:
11326 * @appinfo: a #GAppInfo.
11328 * Gets the display name of the application. The display name is often more
11329 * descriptive to the user than the name itself.
11331 * Returns: the display name of the application for @appinfo, or the name if
11332 * no display name is available.
11338 * g_app_info_get_executable: (virtual get_executable)
11339 * @appinfo: a #GAppInfo
11341 * Gets the executable's name for the installed application.
11343 * Returns: (type filename): a string containing the @appinfo's application
11349 * g_app_info_get_fallback_for_type:
11350 * @content_type: the content type to find a #GAppInfo for
11352 * Gets a list of fallback #GAppInfos for a given content type, i.e.
11353 * those applications which claim to support the given content type
11354 * by MIME type subclassing and not directly.
11356 * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos
11357 * for given @content_type or %NULL on error.
11363 * g_app_info_get_icon:
11364 * @appinfo: a #GAppInfo.
11366 * Gets the icon for the application.
11368 * Returns: (nullable) (transfer none): the default #GIcon for @appinfo or %NULL
11369 * if there is no default icon.
11374 * g_app_info_get_id:
11375 * @appinfo: a #GAppInfo.
11377 * Gets the ID of an application. An id is a string that
11378 * identifies the application. The exact format of the id is
11379 * platform dependent. For instance, on Unix this is the
11380 * desktop file id from the xdg menu specification.
11382 * Note that the returned ID may be %NULL, depending on how
11383 * the @appinfo has been constructed.
11385 * Returns: (nullable): a string containing the application's ID.
11390 * g_app_info_get_name:
11391 * @appinfo: a #GAppInfo.
11393 * Gets the installed name of the application.
11395 * Returns: the name of the application for @appinfo.
11400 * g_app_info_get_recommended_for_type:
11401 * @content_type: the content type to find a #GAppInfo for
11403 * Gets a list of recommended #GAppInfos for a given content type, i.e.
11404 * those applications which claim to support the given content type exactly,
11405 * and not by MIME type subclassing.
11406 * Note that the first application of the list is the last used one, i.e.
11407 * the last one for which g_app_info_set_as_last_used_for_type() has been
11410 * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos
11411 * for given @content_type or %NULL on error.
11417 * g_app_info_get_supported_types:
11418 * @appinfo: a #GAppInfo that can handle files
11420 * Retrieves the list of content types that @app_info claims to support.
11421 * If this information is not provided by the environment, this function
11422 * will return %NULL.
11423 * This function does not take in consideration associations added with
11424 * g_app_info_add_supports_type(), but only those exported directly by
11427 * Returns: (transfer none) (array zero-terminated=1) (element-type utf8):
11428 * a list of content types.
11434 * g_app_info_launch:
11435 * @appinfo: a #GAppInfo
11436 * @files: (nullable) (element-type GFile): a #GList of #GFile objects
11437 * @context: (nullable): a #GAppLaunchContext or %NULL
11438 * @error: a #GError
11440 * Launches the application. Passes @files to the launched application
11441 * as arguments, using the optional @context to get information
11442 * about the details of the launcher (like what screen it is on).
11443 * On error, @error will be set accordingly.
11445 * To launch the application without arguments pass a %NULL @files list.
11447 * Note that even if the launch is successful the application launched
11448 * can fail to start if it runs into problems during startup. There is
11449 * no way to detect this.
11451 * Some URIs can be changed when passed through a GFile (for instance
11452 * unsupported URIs with strange formats like mailto:), so if you have
11453 * a textual URI you want to pass in as argument, consider using
11454 * g_app_info_launch_uris() instead.
11456 * The launched application inherits the environment of the launching
11457 * process, but it can be modified with g_app_launch_context_setenv()
11458 * and g_app_launch_context_unsetenv().
11460 * On UNIX, this function sets the `GIO_LAUNCHED_DESKTOP_FILE`
11461 * environment variable with the path of the launched desktop file and
11462 * `GIO_LAUNCHED_DESKTOP_FILE_PID` to the process id of the launched
11463 * process. This can be used to ignore `GIO_LAUNCHED_DESKTOP_FILE`,
11464 * should it be inherited by further processes. The `DISPLAY` and
11465 * `DESKTOP_STARTUP_ID` environment variables are also set, based
11466 * on information provided in @context.
11468 * Returns: %TRUE on successful launch, %FALSE otherwise.
11473 * g_app_info_launch_default_for_uri:
11474 * @uri: the uri to show
11475 * @context: (nullable): an optional #GAppLaunchContext
11476 * @error: (nullable): return location for an error, or %NULL
11478 * Utility function that launches the default application
11479 * registered to handle the specified uri. Synchronous I/O
11480 * is done on the uri to detect the type of the file if
11483 * The D-Bus–activated applications don't have to be started if your application
11484 * terminates too soon after this function. To prevent this, use
11485 * g_app_info_launch_default_for_uri_async() instead.
11487 * Returns: %TRUE on success, %FALSE on error.
11492 * g_app_info_launch_default_for_uri_async:
11493 * @uri: the uri to show
11494 * @context: (nullable): an optional #GAppLaunchContext
11495 * @cancellable: (nullable): a #GCancellable
11496 * @callback: (nullable): a #GAsyncReadyCallback to call when the request is done
11497 * @user_data: (nullable): data to pass to @callback
11499 * Async version of g_app_info_launch_default_for_uri().
11501 * This version is useful if you are interested in receiving
11502 * error information in the case where the application is
11503 * sandboxed and the portal may present an application chooser
11504 * dialog to the user.
11506 * This is also useful if you want to be sure that the D-Bus–activated
11507 * applications are really started before termination and if you are interested
11508 * in receiving error information from their activation.
11515 * g_app_info_launch_default_for_uri_finish:
11516 * @result: a #GAsyncResult
11517 * @error: (nullable): return location for an error, or %NULL
11519 * Finishes an asynchronous launch-default-for-uri operation.
11521 * Returns: %TRUE if the launch was successful, %FALSE if @error is set
11527 * g_app_info_launch_uris:
11528 * @appinfo: a #GAppInfo
11529 * @uris: (nullable) (element-type utf8): a #GList containing URIs to launch.
11530 * @context: (nullable): a #GAppLaunchContext or %NULL
11531 * @error: a #GError
11533 * Launches the application. This passes the @uris to the launched application
11534 * as arguments, using the optional @context to get information
11535 * about the details of the launcher (like what screen it is on).
11536 * On error, @error will be set accordingly.
11538 * To launch the application without arguments pass a %NULL @uris list.
11540 * Note that even if the launch is successful the application launched
11541 * can fail to start if it runs into problems during startup. There is
11542 * no way to detect this.
11544 * Returns: %TRUE on successful launch, %FALSE otherwise.
11549 * g_app_info_launch_uris_async:
11550 * @appinfo: a #GAppInfo
11551 * @uris: (nullable) (element-type utf8): a #GList containing URIs to launch.
11552 * @context: (nullable): a #GAppLaunchContext or %NULL
11553 * @cancellable: (nullable): a #GCancellable
11554 * @callback: (nullable): a #GAsyncReadyCallback to call when the request is done
11555 * @user_data: (nullable): data to pass to @callback
11557 * Async version of g_app_info_launch_uris().
11559 * The @callback is invoked immediately after the application launch, but it
11560 * waits for activation in case of D-Bus–activated applications and also provides
11561 * extended error information for sandboxed applications, see notes for
11562 * g_app_info_launch_default_for_uri_async().
11569 * g_app_info_launch_uris_finish:
11570 * @appinfo: a #GAppInfo
11571 * @result: a #GAsyncResult
11572 * @error: (nullable): a #GError
11574 * Finishes a g_app_info_launch_uris_async() operation.
11576 * Returns: %TRUE on successful launch, %FALSE otherwise.
11582 * g_app_info_monitor_get:
11584 * Gets the #GAppInfoMonitor for the current thread-default main
11587 * The #GAppInfoMonitor will emit a "changed" signal in the
11588 * thread-default main context whenever the list of installed
11589 * applications (as reported by g_app_info_get_all()) may have changed.
11591 * You must only call g_object_unref() on the return value from under
11592 * the same main context as you created it.
11594 * Returns: (transfer full): a reference to a #GAppInfoMonitor
11600 * g_app_info_remove_supports_type:
11601 * @appinfo: a #GAppInfo.
11602 * @content_type: a string.
11603 * @error: a #GError.
11605 * Removes a supported type from an application, if possible.
11607 * Returns: %TRUE on success, %FALSE on error.
11612 * g_app_info_reset_type_associations:
11613 * @content_type: a content type
11615 * Removes all changes to the type associations done by
11616 * g_app_info_set_as_default_for_type(),
11617 * g_app_info_set_as_default_for_extension(),
11618 * g_app_info_add_supports_type() or
11619 * g_app_info_remove_supports_type().
11626 * g_app_info_set_as_default_for_extension:
11627 * @appinfo: a #GAppInfo.
11628 * @extension: (type filename): a string containing the file extension
11629 * (without the dot).
11630 * @error: a #GError.
11632 * Sets the application as the default handler for the given file extension.
11634 * Returns: %TRUE on success, %FALSE on error.
11639 * g_app_info_set_as_default_for_type:
11640 * @appinfo: a #GAppInfo.
11641 * @content_type: the content type.
11642 * @error: a #GError.
11644 * Sets the application as the default handler for a given type.
11646 * Returns: %TRUE on success, %FALSE on error.
11651 * g_app_info_set_as_last_used_for_type:
11652 * @appinfo: a #GAppInfo.
11653 * @content_type: the content type.
11654 * @error: a #GError.
11656 * Sets the application as the last used application for a given type.
11657 * This will make the application appear as first in the list returned
11658 * by g_app_info_get_recommended_for_type(), regardless of the default
11659 * application for that content type.
11661 * Returns: %TRUE on success, %FALSE on error.
11666 * g_app_info_should_show:
11667 * @appinfo: a #GAppInfo.
11669 * Checks if the application info should be shown in menus that
11670 * list available applications.
11672 * Returns: %TRUE if the @appinfo should be shown, %FALSE otherwise.
11677 * g_app_info_supports_files:
11678 * @appinfo: a #GAppInfo.
11680 * Checks if the application accepts files as arguments.
11682 * Returns: %TRUE if the @appinfo supports files.
11687 * g_app_info_supports_uris:
11688 * @appinfo: a #GAppInfo.
11690 * Checks if the application supports reading files and directories from URIs.
11692 * Returns: %TRUE if the @appinfo supports URIs.
11697 * g_app_launch_context_get_display:
11698 * @context: a #GAppLaunchContext
11699 * @info: a #GAppInfo
11700 * @files: (element-type GFile): a #GList of #GFile objects
11702 * Gets the display string for the @context. This is used to ensure new
11703 * applications are started on the same display as the launching
11704 * application, by setting the `DISPLAY` environment variable.
11706 * Returns: (nullable): a display string for the display.
11711 * g_app_launch_context_get_environment:
11712 * @context: a #GAppLaunchContext
11714 * Gets the complete environment variable list to be passed to
11715 * the child process when @context is used to launch an application.
11716 * This is a %NULL-terminated array of strings, where each string has
11717 * the form `KEY=VALUE`.
11719 * Returns: (array zero-terminated=1) (element-type filename) (transfer full):
11720 * the child's environment
11726 * g_app_launch_context_get_startup_notify_id:
11727 * @context: a #GAppLaunchContext
11728 * @info: a #GAppInfo
11729 * @files: (element-type GFile): a #GList of of #GFile objects
11731 * Initiates startup notification for the application and returns the
11732 * `DESKTOP_STARTUP_ID` for the launched operation, if supported.
11734 * Startup notification IDs are defined in the
11735 * [FreeDesktop.Org Startup Notifications standard](http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt).
11737 * Returns: (nullable): a startup notification ID for the application, or %NULL if
11743 * g_app_launch_context_launch_failed:
11744 * @context: a #GAppLaunchContext.
11745 * @startup_notify_id: the startup notification id that was returned by g_app_launch_context_get_startup_notify_id().
11747 * Called when an application has failed to launch, so that it can cancel
11748 * the application startup notification started in g_app_launch_context_get_startup_notify_id().
11753 * g_app_launch_context_new:
11755 * Creates a new application launch context. This is not normally used,
11756 * instead you instantiate a subclass of this, such as #GdkAppLaunchContext.
11758 * Returns: a #GAppLaunchContext.
11763 * g_app_launch_context_setenv:
11764 * @context: a #GAppLaunchContext
11765 * @variable: (type filename): the environment variable to set
11766 * @value: (type filename): the value for to set the variable to.
11768 * Arranges for @variable to be set to @value in the child's
11769 * environment when @context is used to launch an application.
11776 * g_app_launch_context_unsetenv:
11777 * @context: a #GAppLaunchContext
11778 * @variable: (type filename): the environment variable to remove
11780 * Arranges for @variable to be unset in the child's environment
11781 * when @context is used to launch an application.
11788 * g_application_activate:
11789 * @application: a #GApplication
11791 * Activates the application.
11793 * In essence, this results in the #GApplication::activate signal being
11794 * emitted in the primary instance.
11796 * The application must be registered before calling this function.
11803 * g_application_add_main_option:
11804 * @application: the #GApplication
11805 * @long_name: the long name of an option used to specify it in a commandline
11806 * @short_name: the short name of an option
11807 * @flags: flags from #GOptionFlags
11808 * @arg: the type of the option, as a #GOptionArg
11809 * @description: the description for the option in `--help` output
11810 * @arg_description: (nullable): the placeholder to use for the extra argument
11811 * parsed by the option in `--help` output
11813 * Add an option to be handled by @application.
11815 * Calling this function is the equivalent of calling
11816 * g_application_add_main_option_entries() with a single #GOptionEntry
11817 * that has its arg_data member set to %NULL.
11819 * The parsed arguments will be packed into a #GVariantDict which
11820 * is passed to #GApplication::handle-local-options. If
11821 * %G_APPLICATION_HANDLES_COMMAND_LINE is set, then it will also
11822 * be sent to the primary instance. See
11823 * g_application_add_main_option_entries() for more details.
11825 * See #GOptionEntry for more documentation of the arguments.
11832 * g_application_add_main_option_entries:
11833 * @application: a #GApplication
11834 * @entries: (array zero-terminated=1) (element-type GOptionEntry): a
11835 * %NULL-terminated list of #GOptionEntrys
11837 * Adds main option entries to be handled by @application.
11839 * This function is comparable to g_option_context_add_main_entries().
11841 * After the commandline arguments are parsed, the
11842 * #GApplication::handle-local-options signal will be emitted. At this
11843 * point, the application can inspect the values pointed to by @arg_data
11844 * in the given #GOptionEntrys.
11846 * Unlike #GOptionContext, #GApplication supports giving a %NULL
11847 * @arg_data for a non-callback #GOptionEntry. This results in the
11848 * argument in question being packed into a #GVariantDict which is also
11849 * passed to #GApplication::handle-local-options, where it can be
11850 * inspected and modified. If %G_APPLICATION_HANDLES_COMMAND_LINE is
11851 * set, then the resulting dictionary is sent to the primary instance,
11852 * where g_application_command_line_get_options_dict() will return it.
11853 * This "packing" is done according to the type of the argument --
11854 * booleans for normal flags, strings for strings, bytestrings for
11855 * filenames, etc. The packing only occurs if the flag is given (ie: we
11856 * do not pack a "false" #GVariant in the case that a flag is missing).
11858 * In general, it is recommended that all commandline arguments are
11859 * parsed locally. The options dictionary should then be used to
11860 * transmit the result of the parsing to the primary instance, where
11861 * g_variant_dict_lookup() can be used. For local options, it is
11862 * possible to either use @arg_data in the usual way, or to consult (and
11863 * potentially remove) the option from the options dictionary.
11865 * This function is new in GLib 2.40. Before then, the only real choice
11866 * was to send all of the commandline arguments (options and all) to the
11867 * primary instance for handling. #GApplication ignored them completely
11868 * on the local side. Calling this function "opts in" to the new
11869 * behaviour, and in particular, means that unrecognised options will be
11870 * treated as errors. Unrecognised options have never been ignored when
11871 * %G_APPLICATION_HANDLES_COMMAND_LINE is unset.
11873 * If #GApplication::handle-local-options needs to see the list of
11874 * filenames, then the use of %G_OPTION_REMAINING is recommended. If
11875 * @arg_data is %NULL then %G_OPTION_REMAINING can be used as a key into
11876 * the options dictionary. If you do use %G_OPTION_REMAINING then you
11877 * need to handle these arguments for yourself because once they are
11878 * consumed, they will no longer be visible to the default handling
11879 * (which treats them as filenames to be opened).
11881 * It is important to use the proper GVariant format when retrieving
11882 * the options with g_variant_dict_lookup():
11883 * - for %G_OPTION_ARG_NONE, use `b`
11884 * - for %G_OPTION_ARG_STRING, use `&s`
11885 * - for %G_OPTION_ARG_INT, use `i`
11886 * - for %G_OPTION_ARG_INT64, use `x`
11887 * - for %G_OPTION_ARG_DOUBLE, use `d`
11888 * - for %G_OPTION_ARG_FILENAME, use `^&ay`
11889 * - for %G_OPTION_ARG_STRING_ARRAY, use `^a&s`
11890 * - for %G_OPTION_ARG_FILENAME_ARRAY, use `^a&ay`
11897 * g_application_add_option_group:
11898 * @application: the #GApplication
11899 * @group: (transfer full): a #GOptionGroup
11901 * Adds a #GOptionGroup to the commandline handling of @application.
11903 * This function is comparable to g_option_context_add_group().
11905 * Unlike g_application_add_main_option_entries(), this function does
11906 * not deal with %NULL @arg_data and never transmits options to the
11907 * primary instance.
11909 * The reason for that is because, by the time the options arrive at the
11910 * primary instance, it is typically too late to do anything with them.
11911 * Taking the GTK option group as an example: GTK will already have been
11912 * initialised by the time the #GApplication::command-line handler runs.
11913 * In the case that this is not the first-running instance of the
11914 * application, the existing instance may already have been running for
11915 * a very long time.
11917 * This means that the options from #GOptionGroup are only really usable
11918 * in the case that the instance of the application being run is the
11919 * first instance. Passing options like `--display=` or `--gdk-debug=`
11920 * on future runs will have no effect on the existing primary instance.
11922 * Calling this function will cause the options in the supplied option
11923 * group to be parsed, but it does not cause you to be "opted in" to the
11924 * new functionality whereby unrecognised options are rejected even if
11925 * %G_APPLICATION_HANDLES_COMMAND_LINE was given.
11932 * g_application_bind_busy_property:
11933 * @application: a #GApplication
11934 * @object: (type GObject.Object): a #GObject
11935 * @property: the name of a boolean property of @object
11937 * Marks @application as busy (see g_application_mark_busy()) while
11938 * @property on @object is %TRUE.
11940 * The binding holds a reference to @application while it is active, but
11941 * not to @object. Instead, the binding is destroyed when @object is
11949 * g_application_command_line_create_file_for_arg:
11950 * @cmdline: a #GApplicationCommandLine
11951 * @arg: (type filename): an argument from @cmdline
11953 * Creates a #GFile corresponding to a filename that was given as part
11954 * of the invocation of @cmdline.
11956 * This differs from g_file_new_for_commandline_arg() in that it
11957 * resolves relative pathnames using the current working directory of
11958 * the invoking process rather than the local process.
11960 * Returns: (transfer full): a new #GFile
11966 * g_application_command_line_get_arguments:
11967 * @cmdline: a #GApplicationCommandLine
11968 * @argc: (out) (optional): the length of the arguments array, or %NULL
11970 * Gets the list of arguments that was passed on the command line.
11972 * The strings in the array may contain non-UTF-8 data on UNIX (such as
11973 * filenames or arguments given in the system locale) but are always in
11974 * UTF-8 on Windows.
11976 * If you wish to use the return value with #GOptionContext, you must
11977 * use g_option_context_parse_strv().
11979 * The return value is %NULL-terminated and should be freed using
11982 * Returns: (array length=argc) (element-type filename) (transfer full):
11983 * the string array containing the arguments (the argv)
11989 * g_application_command_line_get_cwd:
11990 * @cmdline: a #GApplicationCommandLine
11992 * Gets the working directory of the command line invocation.
11993 * The string may contain non-utf8 data.
11995 * It is possible that the remote application did not send a working
11996 * directory, so this may be %NULL.
11998 * The return value should not be modified or freed and is valid for as
11999 * long as @cmdline exists.
12001 * Returns: (nullable) (type filename): the current directory, or %NULL
12007 * g_application_command_line_get_environ:
12008 * @cmdline: a #GApplicationCommandLine
12010 * Gets the contents of the 'environ' variable of the command line
12011 * invocation, as would be returned by g_get_environ(), ie as a
12012 * %NULL-terminated list of strings in the form 'NAME=VALUE'.
12013 * The strings may contain non-utf8 data.
12015 * The remote application usually does not send an environment. Use
12016 * %G_APPLICATION_SEND_ENVIRONMENT to affect that. Even with this flag
12017 * set it is possible that the environment is still not available (due
12018 * to invocation messages from other applications).
12020 * The return value should not be modified or freed and is valid for as
12021 * long as @cmdline exists.
12023 * See g_application_command_line_getenv() if you are only interested
12024 * in the value of a single environment variable.
12026 * Returns: (array zero-terminated=1) (element-type filename) (transfer none):
12027 * the environment strings, or %NULL if they were not sent
12033 * g_application_command_line_get_exit_status:
12034 * @cmdline: a #GApplicationCommandLine
12036 * Gets the exit status of @cmdline. See
12037 * g_application_command_line_set_exit_status() for more information.
12039 * Returns: the exit status
12045 * g_application_command_line_get_is_remote:
12046 * @cmdline: a #GApplicationCommandLine
12048 * Determines if @cmdline represents a remote invocation.
12050 * Returns: %TRUE if the invocation was remote
12056 * g_application_command_line_get_options_dict:
12057 * @cmdline: a #GApplicationCommandLine
12059 * Gets the options there were passed to g_application_command_line().
12061 * If you did not override local_command_line() then these are the same
12062 * options that were parsed according to the #GOptionEntrys added to the
12063 * application with g_application_add_main_option_entries() and possibly
12064 * modified from your GApplication::handle-local-options handler.
12066 * If no options were sent then an empty dictionary is returned so that
12067 * you don't need to check for %NULL.
12069 * Returns: (transfer none): a #GVariantDict with the options
12075 * g_application_command_line_get_platform_data:
12076 * @cmdline: #GApplicationCommandLine
12078 * Gets the platform data associated with the invocation of @cmdline.
12080 * This is a #GVariant dictionary containing information about the
12081 * context in which the invocation occurred. It typically contains
12082 * information like the current working directory and the startup
12085 * For local invocation, it will be %NULL.
12087 * Returns: (nullable): the platform data, or %NULL
12093 * g_application_command_line_get_stdin:
12094 * @cmdline: a #GApplicationCommandLine
12096 * Gets the stdin of the invoking process.
12098 * The #GInputStream can be used to read data passed to the standard
12099 * input of the invoking process.
12100 * This doesn't work on all platforms. Presently, it is only available
12101 * on UNIX when using a D-Bus daemon capable of passing file descriptors.
12102 * If stdin is not available then %NULL will be returned. In the
12103 * future, support may be expanded to other platforms.
12105 * You must only call this function once per commandline invocation.
12107 * Returns: (nullable) (transfer full): a #GInputStream for stdin
12113 * g_application_command_line_getenv:
12114 * @cmdline: a #GApplicationCommandLine
12115 * @name: (type filename): the environment variable to get
12117 * Gets the value of a particular environment variable of the command
12118 * line invocation, as would be returned by g_getenv(). The strings may
12119 * contain non-utf8 data.
12121 * The remote application usually does not send an environment. Use
12122 * %G_APPLICATION_SEND_ENVIRONMENT to affect that. Even with this flag
12123 * set it is possible that the environment is still not available (due
12124 * to invocation messages from other applications).
12126 * The return value should not be modified or freed and is valid for as
12127 * long as @cmdline exists.
12129 * Returns: (nullable): the value of the variable, or %NULL if unset or unsent
12135 * g_application_command_line_print:
12136 * @cmdline: a #GApplicationCommandLine
12137 * @format: a printf-style format string
12138 * @...: arguments, as per @format
12140 * Formats a message and prints it using the stdout print handler in the
12141 * invoking process.
12143 * If @cmdline is a local invocation then this is exactly equivalent to
12144 * g_print(). If @cmdline is remote then this is equivalent to calling
12145 * g_print() in the invoking process.
12152 * g_application_command_line_printerr:
12153 * @cmdline: a #GApplicationCommandLine
12154 * @format: a printf-style format string
12155 * @...: arguments, as per @format
12157 * Formats a message and prints it using the stderr print handler in the
12158 * invoking process.
12160 * If @cmdline is a local invocation then this is exactly equivalent to
12161 * g_printerr(). If @cmdline is remote then this is equivalent to
12162 * calling g_printerr() in the invoking process.
12169 * g_application_command_line_set_exit_status:
12170 * @cmdline: a #GApplicationCommandLine
12171 * @exit_status: the exit status
12173 * Sets the exit status that will be used when the invoking process
12176 * The return value of the #GApplication::command-line signal is
12177 * passed to this function when the handler returns. This is the usual
12178 * way of setting the exit status.
12180 * In the event that you want the remote invocation to continue running
12181 * and want to decide on the exit status in the future, you can use this
12182 * call. For the case of a remote invocation, the remote process will
12183 * typically exit when the last reference is dropped on @cmdline. The
12184 * exit status of the remote process will be equal to the last value
12185 * that was set with this function.
12187 * In the case that the commandline invocation is local, the situation
12188 * is slightly more complicated. If the commandline invocation results
12189 * in the mainloop running (ie: because the use-count of the application
12190 * increased to a non-zero value) then the application is considered to
12191 * have been 'successful' in a certain sense, and the exit status is
12192 * always zero. If the application use count is zero, though, the exit
12193 * status of the local #GApplicationCommandLine is used.
12200 * g_application_get_application_id:
12201 * @application: a #GApplication
12203 * Gets the unique identifier for @application.
12205 * Returns: (nullable): the identifier for @application, owned by @application
12211 * g_application_get_dbus_connection:
12212 * @application: a #GApplication
12214 * Gets the #GDBusConnection being used by the application, or %NULL.
12216 * If #GApplication is using its D-Bus backend then this function will
12217 * return the #GDBusConnection being used for uniqueness and
12218 * communication with the desktop environment and other instances of the
12221 * If #GApplication is not using D-Bus then this function will return
12222 * %NULL. This includes the situation where the D-Bus backend would
12223 * normally be in use but we were unable to connect to the bus.
12225 * This function must not be called before the application has been
12226 * registered. See g_application_get_is_registered().
12228 * Returns: (nullable) (transfer none): a #GDBusConnection, or %NULL
12234 * g_application_get_dbus_object_path:
12235 * @application: a #GApplication
12237 * Gets the D-Bus object path being used by the application, or %NULL.
12239 * If #GApplication is using its D-Bus backend then this function will
12240 * return the D-Bus object path that #GApplication is using. If the
12241 * application is the primary instance then there is an object published
12242 * at this path. If the application is not the primary instance then
12243 * the result of this function is undefined.
12245 * If #GApplication is not using D-Bus then this function will return
12246 * %NULL. This includes the situation where the D-Bus backend would
12247 * normally be in use but we were unable to connect to the bus.
12249 * This function must not be called before the application has been
12250 * registered. See g_application_get_is_registered().
12252 * Returns: (nullable): the object path, or %NULL
12258 * g_application_get_default:
12260 * Returns the default #GApplication instance for this process.
12262 * Normally there is only one #GApplication per process and it becomes
12263 * the default when it is created. You can exercise more control over
12264 * this by using g_application_set_default().
12266 * If there is no default application then %NULL is returned.
12268 * Returns: (nullable) (transfer none): the default application for this process, or %NULL
12274 * g_application_get_flags:
12275 * @application: a #GApplication
12277 * Gets the flags for @application.
12279 * See #GApplicationFlags.
12281 * Returns: the flags for @application
12287 * g_application_get_inactivity_timeout:
12288 * @application: a #GApplication
12290 * Gets the current inactivity timeout for the application.
12292 * This is the amount of time (in milliseconds) after the last call to
12293 * g_application_release() before the application stops running.
12295 * Returns: the timeout, in milliseconds
12301 * g_application_get_is_busy:
12302 * @application: a #GApplication
12304 * Gets the application's current busy state, as set through
12305 * g_application_mark_busy() or g_application_bind_busy_property().
12307 * Returns: %TRUE if @application is currently marked as busy
12313 * g_application_get_is_registered:
12314 * @application: a #GApplication
12316 * Checks if @application is registered.
12318 * An application is registered if g_application_register() has been
12319 * successfully called.
12321 * Returns: %TRUE if @application is registered
12327 * g_application_get_is_remote:
12328 * @application: a #GApplication
12330 * Checks if @application is remote.
12332 * If @application is remote then it means that another instance of
12333 * application already exists (the 'primary' instance). Calls to
12334 * perform actions on @application will result in the actions being
12335 * performed by the primary instance.
12337 * The value of this property cannot be accessed before
12338 * g_application_register() has been called. See
12339 * g_application_get_is_registered().
12341 * Returns: %TRUE if @application is remote
12347 * g_application_get_resource_base_path:
12348 * @application: a #GApplication
12350 * Gets the resource base path of @application.
12352 * See g_application_set_resource_base_path() for more information.
12354 * Returns: (nullable): the base resource path, if one is set
12360 * g_application_hold:
12361 * @application: a #GApplication
12363 * Increases the use count of @application.
12365 * Use this function to indicate that the application has a reason to
12366 * continue to run. For example, g_application_hold() is called by GTK+
12367 * when a toplevel window is on the screen.
12369 * To cancel the hold, call g_application_release().
12374 * g_application_id_is_valid:
12375 * @application_id: a potential application identifier
12377 * Checks if @application_id is a valid application identifier.
12379 * A valid ID is required for calls to g_application_new() and
12380 * g_application_set_application_id().
12382 * Application identifiers follow the same format as
12383 * [D-Bus well-known bus names](https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus).
12384 * For convenience, the restrictions on application identifiers are
12387 * - Application identifiers are composed of 1 or more elements separated by a
12388 * period (`.`) character. All elements must contain at least one character.
12390 * - Each element must only contain the ASCII characters `[A-Z][a-z][0-9]_-`,
12391 * with `-` discouraged in new application identifiers. Each element must not
12392 * begin with a digit.
12394 * - Application identifiers must contain at least one `.` (period) character
12395 * (and thus at least two elements).
12397 * - Application identifiers must not begin with a `.` (period) character.
12399 * - Application identifiers must not exceed 255 characters.
12401 * Note that the hyphen (`-`) character is allowed in application identifiers,
12402 * but is problematic or not allowed in various specifications and APIs that
12403 * refer to D-Bus, such as
12404 * [Flatpak application IDs](http://docs.flatpak.org/en/latest/introduction.html#identifiers),
12406 * [`DBusActivatable` interface in the Desktop Entry Specification](https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#dbus),
12407 * and the convention that an application's "main" interface and object path
12408 * resemble its application identifier and bus name. To avoid situations that
12409 * require special-case handling, it is recommended that new application
12410 * identifiers consistently replace hyphens with underscores.
12412 * Like D-Bus interface names, application identifiers should start with the
12413 * reversed DNS domain name of the author of the interface (in lower-case), and
12414 * it is conventional for the rest of the application identifier to consist of
12415 * words run together, with initial capital letters.
12417 * As with D-Bus interface names, if the author's DNS domain name contains
12418 * hyphen/minus characters they should be replaced by underscores, and if it
12419 * contains leading digits they should be escaped by prepending an underscore.
12420 * For example, if the owner of 7-zip.org used an application identifier for an
12421 * archiving application, it might be named `org._7_zip.Archiver`.
12423 * Returns: %TRUE if @application_id is valid
12428 * g_application_mark_busy:
12429 * @application: a #GApplication
12431 * Increases the busy count of @application.
12433 * Use this function to indicate that the application is busy, for instance
12434 * while a long running operation is pending.
12436 * The busy state will be exposed to other processes, so a session shell will
12437 * use that information to indicate the state to the user (e.g. with a
12440 * To cancel the busy indication, use g_application_unmark_busy().
12442 * The application must be registered before calling this function.
12449 * g_application_new:
12450 * @application_id: (nullable): the application id
12451 * @flags: the application flags
12453 * Creates a new #GApplication instance.
12455 * If non-%NULL, the application id must be valid. See
12456 * g_application_id_is_valid().
12458 * If no application ID is given then some features of #GApplication
12459 * (most notably application uniqueness) will be disabled.
12461 * Returns: a new #GApplication instance
12466 * g_application_open:
12467 * @application: a #GApplication
12468 * @files: (array length=n_files): an array of #GFiles to open
12469 * @n_files: the length of the @files array
12470 * @hint: a hint (or ""), but never %NULL
12472 * Opens the given files.
12474 * In essence, this results in the #GApplication::open signal being emitted
12475 * in the primary instance.
12477 * @n_files must be greater than zero.
12479 * @hint is simply passed through to the ::open signal. It is
12480 * intended to be used by applications that have multiple modes for
12481 * opening files (eg: "view" vs "edit", etc). Unless you have a need
12482 * for this functionality, you should use "".
12484 * The application must be registered before calling this function
12485 * and it must have the %G_APPLICATION_HANDLES_OPEN flag set.
12492 * g_application_quit:
12493 * @application: a #GApplication
12495 * Immediately quits the application.
12497 * Upon return to the mainloop, g_application_run() will return,
12498 * calling only the 'shutdown' function before doing so.
12500 * The hold count is ignored.
12501 * Take care if your code has called g_application_hold() on the application and
12502 * is therefore still expecting it to exist.
12503 * (Note that you may have called g_application_hold() indirectly, for example
12504 * through gtk_application_add_window().)
12506 * The result of calling g_application_run() again after it returns is
12514 * g_application_register:
12515 * @application: a #GApplication
12516 * @cancellable: (nullable): a #GCancellable, or %NULL
12517 * @error: a pointer to a NULL #GError, or %NULL
12519 * Attempts registration of the application.
12521 * This is the point at which the application discovers if it is the
12522 * primary instance or merely acting as a remote for an already-existing
12523 * primary instance. This is implemented by attempting to acquire the
12524 * application identifier as a unique bus name on the session bus using
12527 * If there is no application ID or if %G_APPLICATION_NON_UNIQUE was
12528 * given, then this process will always become the primary instance.
12530 * Due to the internal architecture of GDBus, method calls can be
12531 * dispatched at any time (even if a main loop is not running). For
12532 * this reason, you must ensure that any object paths that you wish to
12533 * register are registered before calling this function.
12535 * If the application has already been registered then %TRUE is
12536 * returned with no work performed.
12538 * The #GApplication::startup signal is emitted if registration succeeds
12539 * and @application is the primary instance (including the non-unique
12542 * In the event of an error (such as @cancellable being cancelled, or a
12543 * failure to connect to the session bus), %FALSE is returned and @error
12544 * is set appropriately.
12546 * Note: the return value of this function is not an indicator that this
12547 * instance is or is not the primary instance of the application. See
12548 * g_application_get_is_remote() for that.
12550 * Returns: %TRUE if registration succeeded
12556 * g_application_release:
12557 * @application: a #GApplication
12559 * Decrease the use count of @application.
12561 * When the use count reaches zero, the application will stop running.
12563 * Never call this function except to cancel the effect of a previous
12564 * call to g_application_hold().
12569 * g_application_run:
12570 * @application: a #GApplication
12571 * @argc: the argc from main() (or 0 if @argv is %NULL)
12572 * @argv: (array length=argc) (element-type filename) (nullable):
12573 * the argv from main(), or %NULL
12575 * Runs the application.
12577 * This function is intended to be run from main() and its return value
12578 * is intended to be returned by main(). Although you are expected to pass
12579 * the @argc, @argv parameters from main() to this function, it is possible
12580 * to pass %NULL if @argv is not available or commandline handling is not
12581 * required. Note that on Windows, @argc and @argv are ignored, and
12582 * g_win32_get_command_line() is called internally (for proper support
12583 * of Unicode commandline arguments).
12585 * #GApplication will attempt to parse the commandline arguments. You
12586 * can add commandline flags to the list of recognised options by way of
12587 * g_application_add_main_option_entries(). After this, the
12588 * #GApplication::handle-local-options signal is emitted, from which the
12589 * application can inspect the values of its #GOptionEntrys.
12591 * #GApplication::handle-local-options is a good place to handle options
12592 * such as `--version`, where an immediate reply from the local process is
12593 * desired (instead of communicating with an already-running instance).
12594 * A #GApplication::handle-local-options handler can stop further processing
12595 * by returning a non-negative value, which then becomes the exit status of
12598 * What happens next depends on the flags: if
12599 * %G_APPLICATION_HANDLES_COMMAND_LINE was specified then the remaining
12600 * commandline arguments are sent to the primary instance, where a
12601 * #GApplication::command-line signal is emitted. Otherwise, the
12602 * remaining commandline arguments are assumed to be a list of files.
12603 * If there are no files listed, the application is activated via the
12604 * #GApplication::activate signal. If there are one or more files, and
12605 * %G_APPLICATION_HANDLES_OPEN was specified then the files are opened
12606 * via the #GApplication::open signal.
12608 * If you are interested in doing more complicated local handling of the
12609 * commandline then you should implement your own #GApplication subclass
12610 * and override local_command_line(). In this case, you most likely want
12611 * to return %TRUE from your local_command_line() implementation to
12612 * suppress the default handling. See
12613 * [gapplication-example-cmdline2.c][https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-cmdline2.c]
12616 * If, after the above is done, the use count of the application is zero
12617 * then the exit status is returned immediately. If the use count is
12618 * non-zero then the default main context is iterated until the use count
12619 * falls to zero, at which point 0 is returned.
12621 * If the %G_APPLICATION_IS_SERVICE flag is set, then the service will
12622 * run for as much as 10 seconds with a use count of zero while waiting
12623 * for the message that caused the activation to arrive. After that,
12624 * if the use count falls to zero the application will exit immediately,
12625 * except in the case that g_application_set_inactivity_timeout() is in
12628 * This function sets the prgname (g_set_prgname()), if not already set,
12629 * to the basename of argv[0].
12631 * Much like g_main_loop_run(), this function will acquire the main context
12632 * for the duration that the application is running.
12634 * Since 2.40, applications that are not explicitly flagged as services
12635 * or launchers (ie: neither %G_APPLICATION_IS_SERVICE or
12636 * %G_APPLICATION_IS_LAUNCHER are given as flags) will check (from the
12637 * default handler for local_command_line) if "--gapplication-service"
12638 * was given in the command line. If this flag is present then normal
12639 * commandline processing is interrupted and the
12640 * %G_APPLICATION_IS_SERVICE flag is set. This provides a "compromise"
12641 * solution whereby running an application directly from the commandline
12642 * will invoke it in the normal way (which can be useful for debugging)
12643 * while still allowing applications to be D-Bus activated in service
12644 * mode. The D-Bus service file should invoke the executable with
12645 * "--gapplication-service" as the sole commandline argument. This
12646 * approach is suitable for use by most graphical applications but
12647 * should not be used from applications like editors that need precise
12648 * control over when processes invoked via the commandline will exit and
12649 * what their exit status will be.
12651 * Returns: the exit status
12657 * g_application_send_notification:
12658 * @application: a #GApplication
12659 * @id: (nullable): id of the notification, or %NULL
12660 * @notification: the #GNotification to send
12662 * Sends a notification on behalf of @application to the desktop shell.
12663 * There is no guarantee that the notification is displayed immediately,
12666 * Notifications may persist after the application exits. It will be
12667 * D-Bus-activated when the notification or one of its actions is
12670 * Modifying @notification after this call has no effect. However, the
12671 * object can be reused for a later call to this function.
12673 * @id may be any string that uniquely identifies the event for the
12674 * application. It does not need to be in any special format. For
12675 * example, "new-message" might be appropriate for a notification about
12678 * If a previous notification was sent with the same @id, it will be
12679 * replaced with @notification and shown again as if it was a new
12680 * notification. This works even for notifications sent from a previous
12681 * execution of the application, as long as @id is the same string.
12683 * @id may be %NULL, but it is impossible to replace or withdraw
12684 * notifications without an id.
12686 * If @notification is no longer relevant, it can be withdrawn with
12687 * g_application_withdraw_notification().
12694 * g_application_set_action_group:
12695 * @application: a #GApplication
12696 * @action_group: (nullable): a #GActionGroup, or %NULL
12698 * This used to be how actions were associated with a #GApplication.
12699 * Now there is #GActionMap for that.
12702 * Deprecated: 2.32: Use the #GActionMap interface instead. Never ever
12703 * mix use of this API with use of #GActionMap on the same @application
12704 * or things will go very badly wrong. This function is known to
12705 * introduce buggy behaviour (ie: signals not emitted on changes to the
12706 * action group), so you should really use #GActionMap instead.
12711 * g_application_set_application_id:
12712 * @application: a #GApplication
12713 * @application_id: (nullable): the identifier for @application
12715 * Sets the unique identifier for @application.
12717 * The application id can only be modified if @application has not yet
12720 * If non-%NULL, the application id must be valid. See
12721 * g_application_id_is_valid().
12728 * g_application_set_default:
12729 * @application: (nullable): the application to set as default, or %NULL
12731 * Sets or unsets the default application for the process, as returned
12732 * by g_application_get_default().
12734 * This function does not take its own reference on @application. If
12735 * @application is destroyed then the default application will revert
12743 * g_application_set_flags:
12744 * @application: a #GApplication
12745 * @flags: the flags for @application
12747 * Sets the flags for @application.
12749 * The flags can only be modified if @application has not yet been
12752 * See #GApplicationFlags.
12759 * g_application_set_inactivity_timeout:
12760 * @application: a #GApplication
12761 * @inactivity_timeout: the timeout, in milliseconds
12763 * Sets the current inactivity timeout for the application.
12765 * This is the amount of time (in milliseconds) after the last call to
12766 * g_application_release() before the application stops running.
12768 * This call has no side effects of its own. The value set here is only
12769 * used for next time g_application_release() drops the use count to
12770 * zero. Any timeouts currently in progress are not impacted.
12777 * g_application_set_option_context_description:
12778 * @application: the #GApplication
12779 * @description: (nullable): a string to be shown in `--help` output
12780 * after the list of options, or %NULL
12782 * Adds a description to the @application option context.
12784 * See g_option_context_set_description() for more information.
12791 * g_application_set_option_context_parameter_string:
12792 * @application: the #GApplication
12793 * @parameter_string: (nullable): a string which is displayed
12794 * in the first line of `--help` output, after the usage summary `programname [OPTION...]`.
12796 * Sets the parameter string to be used by the commandline handling of @application.
12798 * This function registers the argument to be passed to g_option_context_new()
12799 * when the internal #GOptionContext of @application is created.
12801 * See g_option_context_new() for more information about @parameter_string.
12808 * g_application_set_option_context_summary:
12809 * @application: the #GApplication
12810 * @summary: (nullable): a string to be shown in `--help` output
12811 * before the list of options, or %NULL
12813 * Adds a summary to the @application option context.
12815 * See g_option_context_set_summary() for more information.
12822 * g_application_set_resource_base_path:
12823 * @application: a #GApplication
12824 * @resource_path: (nullable): the resource path to use
12826 * Sets (or unsets) the base resource path of @application.
12828 * The path is used to automatically load various [application
12829 * resources][gresource] such as menu layouts and action descriptions.
12830 * The various types of resources will be found at fixed names relative
12831 * to the given base path.
12833 * By default, the resource base path is determined from the application
12834 * ID by prefixing '/' and replacing each '.' with '/'. This is done at
12835 * the time that the #GApplication object is constructed. Changes to
12836 * the application ID after that point will not have an impact on the
12837 * resource base path.
12839 * As an example, if the application has an ID of "org.example.app" then
12840 * the default resource base path will be "/org/example/app". If this
12841 * is a #GtkApplication (and you have not manually changed the path)
12842 * then Gtk will then search for the menus of the application at
12843 * "/org/example/app/gtk/menus.ui".
12845 * See #GResource for more information about adding resources to your
12848 * You can disable automatic resource loading functionality by setting
12849 * the path to %NULL.
12851 * Changing the resource base path once the application is running is
12852 * not recommended. The point at which the resource path is consulted
12853 * for forming paths for various purposes is unspecified. When writing
12854 * a sub-class of #GApplication you should either set the
12855 * #GApplication:resource-base-path property at construction time, or call
12856 * this function during the instance initialization. Alternatively, you
12857 * can call this function in the #GApplicationClass.startup virtual function,
12858 * before chaining up to the parent implementation.
12865 * g_application_unbind_busy_property:
12866 * @application: a #GApplication
12867 * @object: (type GObject.Object): a #GObject
12868 * @property: the name of a boolean property of @object
12870 * Destroys a binding between @property and the busy state of
12871 * @application that was previously created with
12872 * g_application_bind_busy_property().
12879 * g_application_unmark_busy:
12880 * @application: a #GApplication
12882 * Decreases the busy count of @application.
12884 * When the busy count reaches zero, the new state will be propagated
12885 * to other processes.
12887 * This function must only be called to cancel the effect of a previous
12888 * call to g_application_mark_busy().
12895 * g_application_withdraw_notification:
12896 * @application: a #GApplication
12897 * @id: id of a previously sent notification
12899 * Withdraws a notification that was sent with
12900 * g_application_send_notification().
12902 * This call does nothing if a notification with @id doesn't exist or
12903 * the notification was never sent.
12905 * This function works even for notifications sent in previous
12906 * executions of this application, as long @id is the same as it was for
12907 * the sent notification.
12909 * Note that notifications are dismissed when the user clicks on one
12910 * of the buttons in a notification or triggers its default action, so
12911 * there is no need to explicitly withdraw the notification in that case.
12918 * g_async_initable_init_async:
12919 * @initable: a #GAsyncInitable.
12920 * @io_priority: the [I/O priority][io-priority] of the operation
12921 * @cancellable: optional #GCancellable object, %NULL to ignore.
12922 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
12923 * @user_data: the data to pass to callback function
12925 * Starts asynchronous initialization of the object implementing the
12926 * interface. This must be done before any real use of the object after
12927 * initial construction. If the object also implements #GInitable you can
12928 * optionally call g_initable_init() instead.
12930 * This method is intended for language bindings. If writing in C,
12931 * g_async_initable_new_async() should typically be used instead.
12933 * When the initialization is finished, @callback will be called. You can
12934 * then call g_async_initable_init_finish() to get the result of the
12937 * Implementations may also support cancellation. If @cancellable is not
12938 * %NULL, then initialization can be cancelled by triggering the cancellable
12939 * object from another thread. If the operation was cancelled, the error
12940 * %G_IO_ERROR_CANCELLED will be returned. If @cancellable is not %NULL, and
12941 * the object doesn't support cancellable initialization, the error
12942 * %G_IO_ERROR_NOT_SUPPORTED will be returned.
12944 * As with #GInitable, if the object is not initialized, or initialization
12945 * returns with an error, then all operations on the object except
12946 * g_object_ref() and g_object_unref() are considered to be invalid, and
12947 * have undefined behaviour. They will often fail with g_critical() or
12948 * g_warning(), but this must not be relied on.
12950 * Callers should not assume that a class which implements #GAsyncInitable can
12951 * be initialized multiple times; for more information, see g_initable_init().
12952 * If a class explicitly supports being initialized multiple times,
12953 * implementation requires yielding all subsequent calls to init_async() on the
12954 * results of the first call.
12956 * For classes that also support the #GInitable interface, the default
12957 * implementation of this method will run the g_initable_init() function
12958 * in a thread, so if you want to support asynchronous initialization via
12959 * threads, just implement the #GAsyncInitable interface without overriding
12960 * any interface methods.
12967 * g_async_initable_init_finish:
12968 * @initable: a #GAsyncInitable.
12969 * @res: a #GAsyncResult.
12970 * @error: a #GError location to store the error occurring, or %NULL to
12973 * Finishes asynchronous initialization and returns the result.
12974 * See g_async_initable_init_async().
12976 * Returns: %TRUE if successful. If an error has occurred, this function
12977 * will return %FALSE and set @error appropriately if present.
12983 * g_async_initable_new_async:
12984 * @object_type: a #GType supporting #GAsyncInitable.
12985 * @io_priority: the [I/O priority][io-priority] of the operation
12986 * @cancellable: optional #GCancellable object, %NULL to ignore.
12987 * @callback: a #GAsyncReadyCallback to call when the initialization is
12989 * @user_data: the data to pass to callback function
12990 * @first_property_name: (nullable): the name of the first property, or %NULL if no
12992 * @...: the value of the first property, followed by other property
12993 * value pairs, and ended by %NULL.
12995 * Helper function for constructing #GAsyncInitable object. This is
12996 * similar to g_object_new() but also initializes the object asynchronously.
12998 * When the initialization is finished, @callback will be called. You can
12999 * then call g_async_initable_new_finish() to get the new object and check
13007 * g_async_initable_new_finish:
13008 * @initable: the #GAsyncInitable from the callback
13009 * @res: the #GAsyncResult from the callback
13010 * @error: return location for errors, or %NULL to ignore
13012 * Finishes the async construction for the various g_async_initable_new
13013 * calls, returning the created object or %NULL on error.
13015 * Returns: (type GObject.Object) (transfer full): a newly created #GObject,
13016 * or %NULL on error. Free with g_object_unref().
13022 * g_async_initable_new_valist_async:
13023 * @object_type: a #GType supporting #GAsyncInitable.
13024 * @first_property_name: the name of the first property, followed by
13025 * the value, and other property value pairs, and ended by %NULL.
13026 * @var_args: The var args list generated from @first_property_name.
13027 * @io_priority: the [I/O priority][io-priority] of the operation
13028 * @cancellable: optional #GCancellable object, %NULL to ignore.
13029 * @callback: a #GAsyncReadyCallback to call when the initialization is
13031 * @user_data: the data to pass to callback function
13033 * Helper function for constructing #GAsyncInitable object. This is
13034 * similar to g_object_new_valist() but also initializes the object
13037 * When the initialization is finished, @callback will be called. You can
13038 * then call g_async_initable_new_finish() to get the new object and check
13046 * g_async_initable_newv_async:
13047 * @object_type: a #GType supporting #GAsyncInitable.
13048 * @n_parameters: the number of parameters in @parameters
13049 * @parameters: the parameters to use to construct the object
13050 * @io_priority: the [I/O priority][io-priority] of the operation
13051 * @cancellable: optional #GCancellable object, %NULL to ignore.
13052 * @callback: a #GAsyncReadyCallback to call when the initialization is
13054 * @user_data: the data to pass to callback function
13056 * Helper function for constructing #GAsyncInitable object. This is
13057 * similar to g_object_newv() but also initializes the object asynchronously.
13059 * When the initialization is finished, @callback will be called. You can
13060 * then call g_async_initable_new_finish() to get the new object and check
13064 * Deprecated: 2.54: Use g_object_new_with_properties() and
13065 * g_async_initable_init_async() instead. See #GParameter for more information.
13070 * g_async_result_get_source_object:
13071 * @res: a #GAsyncResult
13073 * Gets the source object from a #GAsyncResult.
13075 * Returns: (transfer full) (nullable): a new reference to the source
13076 * object for the @res, or %NULL if there is none.
13081 * g_async_result_get_user_data:
13082 * @res: a #GAsyncResult.
13084 * Gets the user data from a #GAsyncResult.
13086 * Returns: (transfer full): the user data for @res.
13091 * g_async_result_is_tagged:
13092 * @res: a #GAsyncResult
13093 * @source_tag: an application-defined tag
13095 * Checks if @res has the given @source_tag (generally a function
13096 * pointer indicating the function @res was created by).
13098 * Returns: %TRUE if @res has the indicated @source_tag, %FALSE if
13105 * g_async_result_legacy_propagate_error:
13106 * @res: a #GAsyncResult
13107 * @error: (out): a location to propagate the error to.
13109 * If @res is a #GSimpleAsyncResult, this is equivalent to
13110 * g_simple_async_result_propagate_error(). Otherwise it returns
13113 * This can be used for legacy error handling in async *_finish()
13114 * wrapper functions that traditionally handled #GSimpleAsyncResult
13115 * error returns themselves rather than calling into the virtual method.
13116 * This should not be used in new code; #GAsyncResult errors that are
13117 * set by virtual methods should also be extracted by virtual methods,
13118 * to enable subclasses to chain up correctly.
13120 * Returns: %TRUE if @error is has been filled in with an error from
13121 * @res, %FALSE if not.
13127 * g_buffered_input_stream_fill:
13128 * @stream: a #GBufferedInputStream
13129 * @count: the number of bytes that will be read from the stream
13130 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore
13131 * @error: location to store the error occurring, or %NULL to ignore
13133 * Tries to read @count bytes from the stream into the buffer.
13134 * Will block during this read.
13136 * If @count is zero, returns zero and does nothing. A value of @count
13137 * larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
13139 * On success, the number of bytes read into the buffer is returned.
13140 * It is not an error if this is not the same as the requested size, as it
13141 * can happen e.g. near the end of a file. Zero is returned on end of file
13142 * (or if @count is zero), but never otherwise.
13144 * If @count is -1 then the attempted read size is equal to the number of
13145 * bytes that are required to fill the buffer.
13147 * If @cancellable is not %NULL, then the operation can be cancelled by
13148 * triggering the cancellable object from another thread. If the operation
13149 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
13150 * operation was partially finished when the operation was cancelled the
13151 * partial result will be returned, without an error.
13153 * On error -1 is returned and @error is set accordingly.
13155 * For the asynchronous, non-blocking, version of this function, see
13156 * g_buffered_input_stream_fill_async().
13158 * Returns: the number of bytes read into @stream's buffer, up to @count,
13164 * g_buffered_input_stream_fill_async:
13165 * @stream: a #GBufferedInputStream
13166 * @count: the number of bytes that will be read from the stream
13167 * @io_priority: the [I/O priority][io-priority] of the request
13168 * @cancellable: (nullable): optional #GCancellable object
13169 * @callback: (scope async): a #GAsyncReadyCallback
13170 * @user_data: (closure): a #gpointer
13172 * Reads data into @stream's buffer asynchronously, up to @count size.
13173 * @io_priority can be used to prioritize reads. For the synchronous
13174 * version of this function, see g_buffered_input_stream_fill().
13176 * If @count is -1 then the attempted read size is equal to the number
13177 * of bytes that are required to fill the buffer.
13182 * g_buffered_input_stream_fill_finish:
13183 * @stream: a #GBufferedInputStream
13184 * @result: a #GAsyncResult
13185 * @error: a #GError
13187 * Finishes an asynchronous read.
13189 * Returns: a #gssize of the read stream, or `-1` on an error.
13194 * g_buffered_input_stream_get_available:
13195 * @stream: #GBufferedInputStream
13197 * Gets the size of the available data within the stream.
13199 * Returns: size of the available stream.
13204 * g_buffered_input_stream_get_buffer_size:
13205 * @stream: a #GBufferedInputStream
13207 * Gets the size of the input buffer.
13209 * Returns: the current buffer size.
13214 * g_buffered_input_stream_new:
13215 * @base_stream: a #GInputStream
13217 * Creates a new #GInputStream from the given @base_stream, with
13218 * a buffer set to the default size (4 kilobytes).
13220 * Returns: a #GInputStream for the given @base_stream.
13225 * g_buffered_input_stream_new_sized:
13226 * @base_stream: a #GInputStream
13229 * Creates a new #GBufferedInputStream from the given @base_stream,
13230 * with a buffer set to @size.
13232 * Returns: a #GInputStream.
13237 * g_buffered_input_stream_peek:
13238 * @stream: a #GBufferedInputStream
13239 * @buffer: (array length=count) (element-type guint8): a pointer to
13240 * an allocated chunk of memory
13241 * @offset: a #gsize
13244 * Peeks in the buffer, copying data of size @count into @buffer,
13245 * offset @offset bytes.
13247 * Returns: a #gsize of the number of bytes peeked, or -1 on error.
13252 * g_buffered_input_stream_peek_buffer:
13253 * @stream: a #GBufferedInputStream
13254 * @count: (out): a #gsize to get the number of bytes available in the buffer
13256 * Returns the buffer with the currently available bytes. The returned
13257 * buffer must not be modified and will become invalid when reading from
13258 * the stream or filling the buffer.
13260 * Returns: (array length=count) (element-type guint8) (transfer none):
13266 * g_buffered_input_stream_read_byte:
13267 * @stream: a #GBufferedInputStream
13268 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore
13269 * @error: location to store the error occurring, or %NULL to ignore
13271 * Tries to read a single byte from the stream or the buffer. Will block
13272 * during this read.
13274 * On success, the byte read from the stream is returned. On end of stream
13275 * -1 is returned but it's not an exceptional error and @error is not set.
13277 * If @cancellable is not %NULL, then the operation can be cancelled by
13278 * triggering the cancellable object from another thread. If the operation
13279 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
13280 * operation was partially finished when the operation was cancelled the
13281 * partial result will be returned, without an error.
13283 * On error -1 is returned and @error is set accordingly.
13285 * Returns: the byte read from the @stream, or -1 on end of stream or error.
13290 * g_buffered_input_stream_set_buffer_size:
13291 * @stream: a #GBufferedInputStream
13294 * Sets the size of the internal buffer of @stream to @size, or to the
13295 * size of the contents of the buffer. The buffer can never be resized
13296 * smaller than its current contents.
13301 * g_buffered_output_stream_get_auto_grow:
13302 * @stream: a #GBufferedOutputStream.
13304 * Checks if the buffer automatically grows as data is added.
13306 * Returns: %TRUE if the @stream's buffer automatically grows,
13307 * %FALSE otherwise.
13312 * g_buffered_output_stream_get_buffer_size:
13313 * @stream: a #GBufferedOutputStream.
13315 * Gets the size of the buffer in the @stream.
13317 * Returns: the current size of the buffer.
13322 * g_buffered_output_stream_new:
13323 * @base_stream: a #GOutputStream.
13325 * Creates a new buffered output stream for a base stream.
13327 * Returns: a #GOutputStream for the given @base_stream.
13332 * g_buffered_output_stream_new_sized:
13333 * @base_stream: a #GOutputStream.
13336 * Creates a new buffered output stream with a given buffer size.
13338 * Returns: a #GOutputStream with an internal buffer set to @size.
13343 * g_buffered_output_stream_set_auto_grow:
13344 * @stream: a #GBufferedOutputStream.
13345 * @auto_grow: a #gboolean.
13347 * Sets whether or not the @stream's buffer should automatically grow.
13348 * If @auto_grow is true, then each write will just make the buffer
13349 * larger, and you must manually flush the buffer to actually write out
13350 * the data to the underlying stream.
13355 * g_buffered_output_stream_set_buffer_size:
13356 * @stream: a #GBufferedOutputStream.
13359 * Sets the size of the internal buffer to @size.
13365 * @bus_type: a #GBusType
13366 * @cancellable: (nullable): a #GCancellable or %NULL
13367 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
13368 * @user_data: the data to pass to @callback
13370 * Asynchronously connects to the message bus specified by @bus_type.
13372 * When the operation is finished, @callback will be invoked. You can
13373 * then call g_bus_get_finish() to get the result of the operation.
13375 * This is an asynchronous failable function. See g_bus_get_sync() for
13376 * the synchronous version.
13383 * g_bus_get_finish:
13384 * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed
13386 * @error: return location for error or %NULL
13388 * Finishes an operation started with g_bus_get().
13390 * The returned object is a singleton, that is, shared with other
13391 * callers of g_bus_get() and g_bus_get_sync() for @bus_type. In the
13392 * event that you need a private message bus connection, use
13393 * g_dbus_address_get_for_bus_sync() and
13394 * g_dbus_connection_new_for_address().
13396 * Note that the returned #GDBusConnection object will (usually) have
13397 * the #GDBusConnection:exit-on-close property set to %TRUE.
13399 * Returns: (transfer full): a #GDBusConnection or %NULL if @error is set.
13400 * Free with g_object_unref().
13407 * @bus_type: a #GBusType
13408 * @cancellable: (nullable): a #GCancellable or %NULL
13409 * @error: return location for error or %NULL
13411 * Synchronously connects to the message bus specified by @bus_type.
13412 * Note that the returned object may shared with other callers,
13413 * e.g. if two separate parts of a process calls this function with
13414 * the same @bus_type, they will share the same object.
13416 * This is a synchronous failable function. See g_bus_get() and
13417 * g_bus_get_finish() for the asynchronous version.
13419 * The returned object is a singleton, that is, shared with other
13420 * callers of g_bus_get() and g_bus_get_sync() for @bus_type. In the
13421 * event that you need a private message bus connection, use
13422 * g_dbus_address_get_for_bus_sync() and
13423 * g_dbus_connection_new_for_address().
13425 * Note that the returned #GDBusConnection object will (usually) have
13426 * the #GDBusConnection:exit-on-close property set to %TRUE.
13428 * Returns: (transfer full): a #GDBusConnection or %NULL if @error is set.
13429 * Free with g_object_unref().
13436 * @bus_type: the type of bus to own a name on
13437 * @name: the well-known name to own
13438 * @flags: a set of flags from the #GBusNameOwnerFlags enumeration
13439 * @bus_acquired_handler: (nullable): handler to invoke when connected to the bus of type @bus_type or %NULL
13440 * @name_acquired_handler: (nullable): handler to invoke when @name is acquired or %NULL
13441 * @name_lost_handler: (nullable): handler to invoke when @name is lost or %NULL
13442 * @user_data: user data to pass to handlers
13443 * @user_data_free_func: (nullable): function for freeing @user_data or %NULL
13445 * Starts acquiring @name on the bus specified by @bus_type and calls
13446 * @name_acquired_handler and @name_lost_handler when the name is
13447 * acquired respectively lost. Callbacks will be invoked in the
13448 * [thread-default main context][g-main-context-push-thread-default]
13449 * of the thread you are calling this function from.
13451 * You are guaranteed that one of the @name_acquired_handler and @name_lost_handler
13452 * callbacks will be invoked after calling this function - there are three
13455 * - @name_lost_handler with a %NULL connection (if a connection to the bus
13458 * - @bus_acquired_handler then @name_lost_handler (if the name can't be
13461 * - @bus_acquired_handler then @name_acquired_handler (if the name was
13464 * When you are done owning the name, just call g_bus_unown_name()
13465 * with the owner id this function returns.
13467 * If the name is acquired or lost (for example another application
13468 * could acquire the name if you allow replacement or the application
13469 * currently owning the name exits), the handlers are also invoked.
13470 * If the #GDBusConnection that is used for attempting to own the name
13471 * closes, then @name_lost_handler is invoked since it is no longer
13472 * possible for other processes to access the process.
13474 * You cannot use g_bus_own_name() several times for the same name (unless
13475 * interleaved with calls to g_bus_unown_name()) - only the first call
13478 * Another guarantee is that invocations of @name_acquired_handler
13479 * and @name_lost_handler are guaranteed to alternate; that
13480 * is, if @name_acquired_handler is invoked then you are
13481 * guaranteed that the next time one of the handlers is invoked, it
13482 * will be @name_lost_handler. The reverse is also true.
13484 * If you plan on exporting objects (using e.g.
13485 * g_dbus_connection_register_object()), note that it is generally too late
13486 * to export the objects in @name_acquired_handler. Instead, you can do this
13487 * in @bus_acquired_handler since you are guaranteed that this will run
13488 * before @name is requested from the bus.
13490 * This behavior makes it very simple to write applications that wants
13491 * to [own names][gdbus-owning-names] and export objects.
13492 * Simply register objects to be exported in @bus_acquired_handler and
13493 * unregister the objects (if any) in @name_lost_handler.
13495 * Returns: an identifier (never 0) that can be used with
13496 * g_bus_unown_name() to stop owning the name.
13502 * g_bus_own_name_on_connection:
13503 * @connection: a #GDBusConnection
13504 * @name: the well-known name to own
13505 * @flags: a set of flags from the #GBusNameOwnerFlags enumeration
13506 * @name_acquired_handler: (nullable): handler to invoke when @name is acquired or %NULL
13507 * @name_lost_handler: (nullable): handler to invoke when @name is lost or %NULL
13508 * @user_data: user data to pass to handlers
13509 * @user_data_free_func: (nullable): function for freeing @user_data or %NULL
13511 * Like g_bus_own_name() but takes a #GDBusConnection instead of a
13514 * Returns: an identifier (never 0) that can be used with
13515 * g_bus_unown_name() to stop owning the name
13521 * g_bus_own_name_on_connection_with_closures: (rename-to g_bus_own_name_on_connection)
13522 * @connection: a #GDBusConnection
13523 * @name: the well-known name to own
13524 * @flags: a set of flags from the #GBusNameOwnerFlags enumeration
13525 * @name_acquired_closure: (nullable): #GClosure to invoke when @name is
13526 * acquired or %NULL
13527 * @name_lost_closure: (nullable): #GClosure to invoke when @name is lost
13530 * Version of g_bus_own_name_on_connection() using closures instead of
13531 * callbacks for easier binding in other languages.
13533 * Returns: an identifier (never 0) that can be used with
13534 * g_bus_unown_name() to stop owning the name.
13540 * g_bus_own_name_with_closures: (rename-to g_bus_own_name)
13541 * @bus_type: the type of bus to own a name on
13542 * @name: the well-known name to own
13543 * @flags: a set of flags from the #GBusNameOwnerFlags enumeration
13544 * @bus_acquired_closure: (nullable): #GClosure to invoke when connected to
13545 * the bus of type @bus_type or %NULL
13546 * @name_acquired_closure: (nullable): #GClosure to invoke when @name is
13547 * acquired or %NULL
13548 * @name_lost_closure: (nullable): #GClosure to invoke when @name is lost or
13551 * Version of g_bus_own_name() using closures instead of callbacks for
13552 * easier binding in other languages.
13554 * Returns: an identifier (never 0) that can be used with
13555 * g_bus_unown_name() to stop owning the name.
13561 * g_bus_unown_name:
13562 * @owner_id: an identifier obtained from g_bus_own_name()
13564 * Stops owning a name.
13566 * Note that there may still be D-Bus traffic to process (relating to owning
13567 * and unowning the name) in the current thread-default #GMainContext after
13568 * this function has returned. You should continue to iterate the #GMainContext
13569 * until the #GDestroyNotify function passed to g_bus_own_name() is called, in
13570 * order to avoid memory leaks through callbacks queued on the #GMainContext
13571 * after it’s stopped being iterated.
13578 * g_bus_unwatch_name:
13579 * @watcher_id: An identifier obtained from g_bus_watch_name()
13581 * Stops watching a name.
13583 * Note that there may still be D-Bus traffic to process (relating to watching
13584 * and unwatching the name) in the current thread-default #GMainContext after
13585 * this function has returned. You should continue to iterate the #GMainContext
13586 * until the #GDestroyNotify function passed to g_bus_watch_name() is called, in
13587 * order to avoid memory leaks through callbacks queued on the #GMainContext
13588 * after it’s stopped being iterated.
13595 * g_bus_watch_name:
13596 * @bus_type: The type of bus to watch a name on.
13597 * @name: The name (well-known or unique) to watch.
13598 * @flags: Flags from the #GBusNameWatcherFlags enumeration.
13599 * @name_appeared_handler: (nullable): Handler to invoke when @name is known to exist or %NULL.
13600 * @name_vanished_handler: (nullable): Handler to invoke when @name is known to not exist or %NULL.
13601 * @user_data: User data to pass to handlers.
13602 * @user_data_free_func: (nullable): Function for freeing @user_data or %NULL.
13604 * Starts watching @name on the bus specified by @bus_type and calls
13605 * @name_appeared_handler and @name_vanished_handler when the name is
13606 * known to have an owner respectively known to lose its
13607 * owner. Callbacks will be invoked in the
13608 * [thread-default main context][g-main-context-push-thread-default]
13609 * of the thread you are calling this function from.
13611 * You are guaranteed that one of the handlers will be invoked after
13612 * calling this function. When you are done watching the name, just
13613 * call g_bus_unwatch_name() with the watcher id this function
13616 * If the name vanishes or appears (for example the application owning
13617 * the name could restart), the handlers are also invoked. If the
13618 * #GDBusConnection that is used for watching the name disconnects, then
13619 * @name_vanished_handler is invoked since it is no longer
13620 * possible to access the name.
13622 * Another guarantee is that invocations of @name_appeared_handler
13623 * and @name_vanished_handler are guaranteed to alternate; that
13624 * is, if @name_appeared_handler is invoked then you are
13625 * guaranteed that the next time one of the handlers is invoked, it
13626 * will be @name_vanished_handler. The reverse is also true.
13628 * This behavior makes it very simple to write applications that want
13629 * to take action when a certain [name exists][gdbus-watching-names].
13630 * Basically, the application should create object proxies in
13631 * @name_appeared_handler and destroy them again (if any) in
13632 * @name_vanished_handler.
13634 * Returns: An identifier (never 0) that can be used with
13635 * g_bus_unwatch_name() to stop watching the name.
13641 * g_bus_watch_name_on_connection:
13642 * @connection: A #GDBusConnection.
13643 * @name: The name (well-known or unique) to watch.
13644 * @flags: Flags from the #GBusNameWatcherFlags enumeration.
13645 * @name_appeared_handler: (nullable): Handler to invoke when @name is known to exist or %NULL.
13646 * @name_vanished_handler: (nullable): Handler to invoke when @name is known to not exist or %NULL.
13647 * @user_data: User data to pass to handlers.
13648 * @user_data_free_func: (nullable): Function for freeing @user_data or %NULL.
13650 * Like g_bus_watch_name() but takes a #GDBusConnection instead of a
13653 * Returns: An identifier (never 0) that can be used with
13654 * g_bus_unwatch_name() to stop watching the name.
13660 * g_bus_watch_name_on_connection_with_closures: (rename-to g_bus_watch_name_on_connection)
13661 * @connection: A #GDBusConnection.
13662 * @name: The name (well-known or unique) to watch.
13663 * @flags: Flags from the #GBusNameWatcherFlags enumeration.
13664 * @name_appeared_closure: (nullable): #GClosure to invoke when @name is known
13665 * to exist or %NULL.
13666 * @name_vanished_closure: (nullable): #GClosure to invoke when @name is known
13667 * to not exist or %NULL.
13669 * Version of g_bus_watch_name_on_connection() using closures instead of callbacks for
13670 * easier binding in other languages.
13672 * Returns: An identifier (never 0) that can be used with
13673 * g_bus_unwatch_name() to stop watching the name.
13679 * g_bus_watch_name_with_closures: (rename-to g_bus_watch_name)
13680 * @bus_type: The type of bus to watch a name on.
13681 * @name: The name (well-known or unique) to watch.
13682 * @flags: Flags from the #GBusNameWatcherFlags enumeration.
13683 * @name_appeared_closure: (nullable): #GClosure to invoke when @name is known
13684 * to exist or %NULL.
13685 * @name_vanished_closure: (nullable): #GClosure to invoke when @name is known
13686 * to not exist or %NULL.
13688 * Version of g_bus_watch_name() using closures instead of callbacks for
13689 * easier binding in other languages.
13691 * Returns: An identifier (never 0) that can be used with
13692 * g_bus_unwatch_name() to stop watching the name.
13698 * g_bytes_icon_get_bytes:
13701 * Gets the #GBytes associated with the given @icon.
13703 * Returns: (transfer none): a #GBytes.
13709 * g_bytes_icon_new:
13710 * @bytes: a #GBytes.
13712 * Creates a new icon for a bytes.
13714 * This cannot fail, but loading and interpreting the bytes may fail later on
13715 * (for example, if g_loadable_icon_load() is called) if the image is invalid.
13717 * Returns: (transfer full) (type GBytesIcon): a #GIcon for the given
13724 * g_cancellable_cancel:
13725 * @cancellable: (nullable): a #GCancellable object.
13727 * Will set @cancellable to cancelled, and will emit the
13728 * #GCancellable::cancelled signal. (However, see the warning about
13729 * race conditions in the documentation for that signal if you are
13730 * planning to connect to it.)
13732 * This function is thread-safe. In other words, you can safely call
13733 * it from a thread other than the one running the operation that was
13734 * passed the @cancellable.
13736 * If @cancellable is %NULL, this function returns immediately for convenience.
13738 * The convention within GIO is that cancelling an asynchronous
13739 * operation causes it to complete asynchronously. That is, if you
13740 * cancel the operation from the same thread in which it is running,
13741 * then the operation's #GAsyncReadyCallback will not be invoked until
13742 * the application returns to the main loop.
13747 * g_cancellable_connect:
13748 * @cancellable: A #GCancellable.
13749 * @callback: The #GCallback to connect.
13750 * @data: Data to pass to @callback.
13751 * @data_destroy_func: (nullable): Free function for @data or %NULL.
13753 * Convenience function to connect to the #GCancellable::cancelled
13754 * signal. Also handles the race condition that may happen
13755 * if the cancellable is cancelled right before connecting.
13757 * @callback is called at most once, either directly at the
13758 * time of the connect if @cancellable is already cancelled,
13759 * or when @cancellable is cancelled in some thread.
13761 * @data_destroy_func will be called when the handler is
13762 * disconnected, or immediately if the cancellable is already
13765 * See #GCancellable::cancelled for details on how to use this.
13767 * Since GLib 2.40, the lock protecting @cancellable is not held when
13768 * @callback is invoked. This lifts a restriction in place for
13769 * earlier GLib versions which now makes it easier to write cleanup
13770 * code that unconditionally invokes e.g. g_cancellable_cancel().
13772 * Returns: The id of the signal handler or 0 if @cancellable has already
13779 * g_cancellable_disconnect:
13780 * @cancellable: (nullable): A #GCancellable or %NULL.
13781 * @handler_id: Handler id of the handler to be disconnected, or `0`.
13783 * Disconnects a handler from a cancellable instance similar to
13784 * g_signal_handler_disconnect(). Additionally, in the event that a
13785 * signal handler is currently running, this call will block until the
13786 * handler has finished. Calling this function from a
13787 * #GCancellable::cancelled signal handler will therefore result in a
13790 * This avoids a race condition where a thread cancels at the
13791 * same time as the cancellable operation is finished and the
13792 * signal handler is removed. See #GCancellable::cancelled for
13793 * details on how to use this.
13795 * If @cancellable is %NULL or @handler_id is `0` this function does
13803 * g_cancellable_get_current:
13805 * Gets the top cancellable from the stack.
13807 * Returns: (nullable) (transfer none): a #GCancellable from the top
13808 * of the stack, or %NULL if the stack is empty.
13813 * g_cancellable_get_fd:
13814 * @cancellable: a #GCancellable.
13816 * Gets the file descriptor for a cancellable job. This can be used to
13817 * implement cancellable operations on Unix systems. The returned fd will
13818 * turn readable when @cancellable is cancelled.
13820 * You are not supposed to read from the fd yourself, just check for
13821 * readable status. Reading to unset the readable status is done
13822 * with g_cancellable_reset().
13824 * After a successful return from this function, you should use
13825 * g_cancellable_release_fd() to free up resources allocated for
13826 * the returned file descriptor.
13828 * See also g_cancellable_make_pollfd().
13830 * Returns: A valid file descriptor. `-1` if the file descriptor
13831 * is not supported, or on errors.
13836 * g_cancellable_is_cancelled:
13837 * @cancellable: (nullable): a #GCancellable or %NULL
13839 * Checks if a cancellable job has been cancelled.
13841 * Returns: %TRUE if @cancellable is cancelled,
13842 * FALSE if called with %NULL or if item is not cancelled.
13847 * g_cancellable_make_pollfd:
13848 * @cancellable: (nullable): a #GCancellable or %NULL
13849 * @pollfd: a pointer to a #GPollFD
13851 * Creates a #GPollFD corresponding to @cancellable; this can be passed
13852 * to g_poll() and used to poll for cancellation. This is useful both
13853 * for unix systems without a native poll and for portability to
13856 * When this function returns %TRUE, you should use
13857 * g_cancellable_release_fd() to free up resources allocated for the
13858 * @pollfd. After a %FALSE return, do not call g_cancellable_release_fd().
13860 * If this function returns %FALSE, either no @cancellable was given or
13861 * resource limits prevent this function from allocating the necessary
13862 * structures for polling. (On Linux, you will likely have reached
13863 * the maximum number of file descriptors.) The suggested way to handle
13864 * these cases is to ignore the @cancellable.
13866 * You are not supposed to read from the fd yourself, just check for
13867 * readable status. Reading to unset the readable status is done
13868 * with g_cancellable_reset().
13870 * Returns: %TRUE if @pollfd was successfully initialized, %FALSE on
13871 * failure to prepare the cancellable.
13877 * g_cancellable_new:
13879 * Creates a new #GCancellable object.
13881 * Applications that want to start one or more operations
13882 * that should be cancellable should create a #GCancellable
13883 * and pass it to the operations.
13885 * One #GCancellable can be used in multiple consecutive
13886 * operations or in multiple concurrent operations.
13888 * Returns: a #GCancellable.
13893 * g_cancellable_pop_current:
13894 * @cancellable: a #GCancellable object
13896 * Pops @cancellable off the cancellable stack (verifying that @cancellable
13897 * is on the top of the stack).
13902 * g_cancellable_push_current:
13903 * @cancellable: a #GCancellable object
13905 * Pushes @cancellable onto the cancellable stack. The current
13906 * cancellable can then be received using g_cancellable_get_current().
13908 * This is useful when implementing cancellable operations in
13909 * code that does not allow you to pass down the cancellable object.
13911 * This is typically called automatically by e.g. #GFile operations,
13912 * so you rarely have to call this yourself.
13917 * g_cancellable_release_fd:
13918 * @cancellable: a #GCancellable
13920 * Releases a resources previously allocated by g_cancellable_get_fd()
13921 * or g_cancellable_make_pollfd().
13923 * For compatibility reasons with older releases, calling this function
13924 * is not strictly required, the resources will be automatically freed
13925 * when the @cancellable is finalized. However, the @cancellable will
13926 * block scarce file descriptors until it is finalized if this function
13927 * is not called. This can cause the application to run out of file
13928 * descriptors when many #GCancellables are used at the same time.
13935 * g_cancellable_reset:
13936 * @cancellable: a #GCancellable object.
13938 * Resets @cancellable to its uncancelled state.
13940 * If cancellable is currently in use by any cancellable operation
13941 * then the behavior of this function is undefined.
13943 * Note that it is generally not a good idea to reuse an existing
13944 * cancellable for more operations after it has been cancelled once,
13945 * as this function might tempt you to do. The recommended practice
13946 * is to drop the reference to a cancellable after cancelling it,
13947 * and let it die with the outstanding async operations. You should
13948 * create a fresh cancellable for further async operations.
13953 * g_cancellable_set_error_if_cancelled:
13954 * @cancellable: (nullable): a #GCancellable or %NULL
13955 * @error: #GError to append error state to
13957 * If the @cancellable is cancelled, sets the error to notify
13958 * that the operation was cancelled.
13960 * Returns: %TRUE if @cancellable was cancelled, %FALSE if it was not
13965 * g_cancellable_source_new:
13966 * @cancellable: (nullable): a #GCancellable, or %NULL
13968 * Creates a source that triggers if @cancellable is cancelled and
13969 * calls its callback of type #GCancellableSourceFunc. This is
13970 * primarily useful for attaching to another (non-cancellable) source
13971 * with g_source_add_child_source() to add cancellability to it.
13973 * For convenience, you can call this with a %NULL #GCancellable,
13974 * in which case the source will never trigger.
13976 * The new #GSource will hold a reference to the #GCancellable.
13978 * Returns: (transfer full): the new #GSource.
13984 * g_charset_converter_get_num_fallbacks:
13985 * @converter: a #GCharsetConverter
13987 * Gets the number of fallbacks that @converter has applied so far.
13989 * Returns: the number of fallbacks that @converter has applied
13995 * g_charset_converter_get_use_fallback:
13996 * @converter: a #GCharsetConverter
13998 * Gets the #GCharsetConverter:use-fallback property.
14000 * Returns: %TRUE if fallbacks are used by @converter
14006 * g_charset_converter_new:
14007 * @to_charset: destination charset
14008 * @from_charset: source charset
14009 * @error: #GError for error reporting, or %NULL to ignore.
14011 * Creates a new #GCharsetConverter.
14013 * Returns: a new #GCharsetConverter or %NULL on error.
14019 * g_charset_converter_set_use_fallback:
14020 * @converter: a #GCharsetConverter
14021 * @use_fallback: %TRUE to use fallbacks
14023 * Sets the #GCharsetConverter:use-fallback property.
14030 * g_content_type_can_be_executable:
14031 * @type: a content type string
14033 * Checks if a content type can be executable. Note that for instance
14034 * things like text files can be executables (i.e. scripts and batch files).
14036 * Returns: %TRUE if the file type corresponds to a type that
14037 * can be executable, %FALSE otherwise.
14042 * g_content_type_equals:
14043 * @type1: a content type string
14044 * @type2: a content type string
14046 * Compares two content types for equality.
14048 * Returns: %TRUE if the two strings are identical or equivalent,
14049 * %FALSE otherwise.
14054 * g_content_type_from_mime_type:
14055 * @mime_type: a mime type string
14057 * Tries to find a content type based on the mime type name.
14059 * Returns: (nullable): Newly allocated string with content type or
14060 * %NULL. Free with g_free()
14066 * g_content_type_get_description:
14067 * @type: a content type string
14069 * Gets the human readable description of the content type.
14071 * Returns: a short description of the content type @type. Free the
14072 * returned string with g_free()
14077 * g_content_type_get_generic_icon_name:
14078 * @type: a content type string
14080 * Gets the generic icon name for a content type.
14083 * [shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec)
14084 * specification for more on the generic icon name.
14086 * Returns: (nullable): the registered generic icon name for the given @type,
14087 * or %NULL if unknown. Free with g_free()
14093 * g_content_type_get_icon:
14094 * @type: a content type string
14096 * Gets the icon for a content type.
14098 * Returns: (transfer full): #GIcon corresponding to the content type. Free the returned
14099 * object with g_object_unref()
14104 * g_content_type_get_mime_dirs:
14106 * Get the list of directories which MIME data is loaded from. See
14107 * g_content_type_set_mime_dirs() for details.
14109 * Returns: (transfer none) (array zero-terminated=1): %NULL-terminated list of
14110 * directories to load MIME data from, including any `mime/` subdirectory,
14111 * and with the first directory to try listed first
14117 * g_content_type_get_mime_type:
14118 * @type: a content type string
14120 * Gets the mime type for the content type, if one is registered.
14122 * Returns: (nullable) (transfer full): the registered mime type for the
14123 * given @type, or %NULL if unknown; free with g_free().
14128 * g_content_type_get_symbolic_icon:
14129 * @type: a content type string
14131 * Gets the symbolic icon for a content type.
14133 * Returns: (transfer full): symbolic #GIcon corresponding to the content type.
14134 * Free the returned object with g_object_unref()
14140 * g_content_type_guess:
14141 * @filename: (nullable): a string, or %NULL
14142 * @data: (nullable) (array length=data_size): a stream of data, or %NULL
14143 * @data_size: the size of @data
14144 * @result_uncertain: (out) (optional): return location for the certainty
14145 * of the result, or %NULL
14147 * Guesses the content type based on example data. If the function is
14148 * uncertain, @result_uncertain will be set to %TRUE. Either @filename
14149 * or @data may be %NULL, in which case the guess will be based solely
14150 * on the other argument.
14152 * Returns: a string indicating a guessed content type for the
14153 * given data. Free with g_free()
14158 * g_content_type_guess_for_tree:
14159 * @root: the root of the tree to guess a type for
14161 * Tries to guess the type of the tree with root @root, by
14162 * looking at the files it contains. The result is an array
14163 * of content types, with the best guess coming first.
14165 * The types returned all have the form x-content/foo, e.g.
14166 * x-content/audio-cdda (for audio CDs) or x-content/image-dcf
14167 * (for a camera memory card). See the
14168 * [shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec)
14169 * specification for more on x-content types.
14171 * This function is useful in the implementation of
14172 * g_mount_guess_content_type().
14174 * Returns: (transfer full) (array zero-terminated=1): an %NULL-terminated
14175 * array of zero or more content types. Free with g_strfreev()
14181 * g_content_type_is_a:
14182 * @type: a content type string
14183 * @supertype: a content type string
14185 * Determines if @type is a subset of @supertype.
14187 * Returns: %TRUE if @type is a kind of @supertype,
14188 * %FALSE otherwise.
14193 * g_content_type_is_mime_type:
14194 * @type: a content type string
14195 * @mime_type: a mime type string
14197 * Determines if @type is a subset of @mime_type.
14198 * Convenience wrapper around g_content_type_is_a().
14200 * Returns: %TRUE if @type is a kind of @mime_type,
14201 * %FALSE otherwise.
14207 * g_content_type_is_unknown:
14208 * @type: a content type string
14210 * Checks if the content type is the generic "unknown" type.
14211 * On UNIX this is the "application/octet-stream" mimetype,
14212 * while on win32 it is "*" and on OSX it is a dynamic type
14215 * Returns: %TRUE if the type is the unknown type.
14220 * g_content_type_set_mime_dirs:
14221 * @dirs: (array zero-terminated=1) (nullable): %NULL-terminated list of
14222 * directories to load MIME data from, including any `mime/` subdirectory,
14223 * and with the first directory to try listed first
14225 * Set the list of directories used by GIO to load the MIME database.
14226 * If @dirs is %NULL, the directories used are the default:
14228 * - the `mime` subdirectory of the directory in `$XDG_DATA_HOME`
14229 * - the `mime` subdirectory of every directory in `$XDG_DATA_DIRS`
14231 * This function is intended to be used when writing tests that depend on
14232 * information stored in the MIME database, in order to control the data.
14234 * Typically, in case your tests use %G_TEST_OPTION_ISOLATE_DIRS, but they
14235 * depend on the system’s MIME database, you should call this function
14236 * with @dirs set to %NULL before calling g_test_init(), for instance:
14238 * |[<!-- language="C" -->
14239 * // Load MIME data from the system
14240 * g_content_type_set_mime_dirs (NULL);
14241 * // Isolate the environment
14242 * g_test_init (&argc, &argv, G_TEST_OPTION_ISOLATE_DIRS, NULL);
14246 * return g_test_run ();
14254 * g_content_types_get_registered:
14256 * Gets a list of strings containing all the registered content types
14257 * known to the system. The list and its data should be freed using
14258 * `g_list_free_full (list, g_free)`.
14260 * Returns: (element-type utf8) (transfer full): list of the registered
14266 * g_converter_convert:
14267 * @converter: a #GConverter.
14268 * @inbuf: (array length=inbuf_size) (element-type guint8): the buffer
14269 * containing the data to convert.
14270 * @inbuf_size: the number of bytes in @inbuf
14271 * @outbuf: (element-type guint8) (array length=outbuf_size): a buffer to write
14272 * converted data in.
14273 * @outbuf_size: the number of bytes in @outbuf, must be at least one
14274 * @flags: a #GConverterFlags controlling the conversion details
14275 * @bytes_read: (out): will be set to the number of bytes read from @inbuf on success
14276 * @bytes_written: (out): will be set to the number of bytes written to @outbuf on success
14277 * @error: location to store the error occurring, or %NULL to ignore
14279 * This is the main operation used when converting data. It is to be called
14280 * multiple times in a loop, and each time it will do some work, i.e.
14281 * producing some output (in @outbuf) or consuming some input (from @inbuf) or
14282 * both. If its not possible to do any work an error is returned.
14284 * Note that a single call may not consume all input (or any input at all).
14285 * Also a call may produce output even if given no input, due to state stored
14286 * in the converter producing output.
14288 * If any data was either produced or consumed, and then an error happens, then
14289 * only the successful conversion is reported and the error is returned on the
14292 * A full conversion loop involves calling this method repeatedly, each time
14293 * giving it new input and space output space. When there is no more input
14294 * data after the data in @inbuf, the flag %G_CONVERTER_INPUT_AT_END must be set.
14295 * The loop will be (unless some error happens) returning %G_CONVERTER_CONVERTED
14296 * each time until all data is consumed and all output is produced, then
14297 * %G_CONVERTER_FINISHED is returned instead. Note, that %G_CONVERTER_FINISHED
14298 * may be returned even if %G_CONVERTER_INPUT_AT_END is not set, for instance
14299 * in a decompression converter where the end of data is detectable from the
14300 * data (and there might even be other data after the end of the compressed data).
14302 * When some data has successfully been converted @bytes_read and is set to
14303 * the number of bytes read from @inbuf, and @bytes_written is set to indicate
14304 * how many bytes was written to @outbuf. If there are more data to output
14305 * or consume (i.e. unless the %G_CONVERTER_INPUT_AT_END is specified) then
14306 * %G_CONVERTER_CONVERTED is returned, and if no more data is to be output
14307 * then %G_CONVERTER_FINISHED is returned.
14309 * On error %G_CONVERTER_ERROR is returned and @error is set accordingly.
14310 * Some errors need special handling:
14312 * %G_IO_ERROR_NO_SPACE is returned if there is not enough space
14313 * to write the resulting converted data, the application should
14314 * call the function again with a larger @outbuf to continue.
14316 * %G_IO_ERROR_PARTIAL_INPUT is returned if there is not enough
14317 * input to fully determine what the conversion should produce,
14318 * and the %G_CONVERTER_INPUT_AT_END flag is not set. This happens for
14319 * example with an incomplete multibyte sequence when converting text,
14320 * or when a regexp matches up to the end of the input (and may match
14321 * further input). It may also happen when @inbuf_size is zero and
14322 * there is no more data to produce.
14324 * When this happens the application should read more input and then
14325 * call the function again. If further input shows that there is no
14326 * more data call the function again with the same data but with
14327 * the %G_CONVERTER_INPUT_AT_END flag set. This may cause the conversion
14328 * to finish as e.g. in the regexp match case (or, to fail again with
14329 * %G_IO_ERROR_PARTIAL_INPUT in e.g. a charset conversion where the
14330 * input is actually partial).
14332 * After g_converter_convert() has returned %G_CONVERTER_FINISHED the
14333 * converter object is in an invalid state where its not allowed
14334 * to call g_converter_convert() anymore. At this time you can only
14335 * free the object or call g_converter_reset() to reset it to the
14338 * If the flag %G_CONVERTER_FLUSH is set then conversion is modified
14339 * to try to write out all internal state to the output. The application
14340 * has to call the function multiple times with the flag set, and when
14341 * the available input has been consumed and all internal state has
14342 * been produced then %G_CONVERTER_FLUSHED (or %G_CONVERTER_FINISHED if
14343 * really at the end) is returned instead of %G_CONVERTER_CONVERTED.
14344 * This is somewhat similar to what happens at the end of the input stream,
14345 * but done in the middle of the data.
14347 * This has different meanings for different conversions. For instance
14348 * in a compression converter it would mean that we flush all the
14349 * compression state into output such that if you uncompress the
14350 * compressed data you get back all the input data. Doing this may
14351 * make the final file larger due to padding though. Another example
14352 * is a regexp conversion, where if you at the end of the flushed data
14353 * have a match, but there is also a potential longer match. In the
14354 * non-flushed case we would ask for more input, but when flushing we
14355 * treat this as the end of input and do the match.
14357 * Flushing is not always possible (like if a charset converter flushes
14358 * at a partial multibyte sequence). Converters are supposed to try
14359 * to produce as much output as possible and then return an error
14360 * (typically %G_IO_ERROR_PARTIAL_INPUT).
14362 * Returns: a #GConverterResult, %G_CONVERTER_ERROR on error.
14368 * g_converter_input_stream_get_converter:
14369 * @converter_stream: a #GConverterInputStream
14371 * Gets the #GConverter that is used by @converter_stream.
14373 * Returns: (transfer none): the converter of the converter input stream
14379 * g_converter_input_stream_new:
14380 * @base_stream: a #GInputStream
14381 * @converter: a #GConverter
14383 * Creates a new converter input stream for the @base_stream.
14385 * Returns: a new #GInputStream.
14390 * g_converter_output_stream_get_converter:
14391 * @converter_stream: a #GConverterOutputStream
14393 * Gets the #GConverter that is used by @converter_stream.
14395 * Returns: (transfer none): the converter of the converter output stream
14401 * g_converter_output_stream_new:
14402 * @base_stream: a #GOutputStream
14403 * @converter: a #GConverter
14405 * Creates a new converter output stream for the @base_stream.
14407 * Returns: a new #GOutputStream.
14412 * g_converter_reset:
14413 * @converter: a #GConverter.
14415 * Resets all internal state in the converter, making it behave
14416 * as if it was just created. If the converter has any internal
14417 * state that would produce output then that output is lost.
14424 * g_credentials_get_native: (skip)
14425 * @credentials: A #GCredentials.
14426 * @native_type: The type of native credentials to get.
14428 * Gets a pointer to native credentials of type @native_type from
14431 * It is a programming error (which will cause a warning to be
14432 * logged) to use this method if there is no #GCredentials support for
14433 * the OS or if @native_type isn't supported by the OS.
14435 * Returns: (transfer none) (nullable): The pointer to native credentials or
14436 * %NULL if there is no #GCredentials support for the OS or if @native_type
14437 * isn't supported by the OS. Do not free the returned data, it is owned
14444 * g_credentials_get_unix_pid:
14445 * @credentials: A #GCredentials
14446 * @error: Return location for error or %NULL.
14448 * Tries to get the UNIX process identifier from @credentials. This
14449 * method is only available on UNIX platforms.
14451 * This operation can fail if #GCredentials is not supported on the
14452 * OS or if the native credentials type does not contain information
14453 * about the UNIX process ID (for example this is the case for
14454 * %G_CREDENTIALS_TYPE_APPLE_XUCRED).
14456 * Returns: The UNIX process ID, or `-1` if @error is set.
14462 * g_credentials_get_unix_user:
14463 * @credentials: A #GCredentials
14464 * @error: Return location for error or %NULL.
14466 * Tries to get the UNIX user identifier from @credentials. This
14467 * method is only available on UNIX platforms.
14469 * This operation can fail if #GCredentials is not supported on the
14470 * OS or if the native credentials type does not contain information
14471 * about the UNIX user.
14473 * Returns: The UNIX user identifier or `-1` if @error is set.
14479 * g_credentials_is_same_user:
14480 * @credentials: A #GCredentials.
14481 * @other_credentials: A #GCredentials.
14482 * @error: Return location for error or %NULL.
14484 * Checks if @credentials and @other_credentials is the same user.
14486 * This operation can fail if #GCredentials is not supported on the
14489 * Returns: %TRUE if @credentials and @other_credentials has the same
14490 * user, %FALSE otherwise or if @error is set.
14496 * g_credentials_new:
14498 * Creates a new #GCredentials object with credentials matching the
14499 * the current process.
14501 * Returns: (transfer full): A #GCredentials. Free with g_object_unref().
14507 * g_credentials_set_native:
14508 * @credentials: A #GCredentials.
14509 * @native_type: The type of native credentials to set.
14510 * @native: (not nullable): A pointer to native credentials.
14512 * Copies the native credentials of type @native_type from @native
14513 * into @credentials.
14515 * It is a programming error (which will cause a warning to be
14516 * logged) to use this method if there is no #GCredentials support for
14517 * the OS or if @native_type isn't supported by the OS.
14524 * g_credentials_set_unix_user:
14525 * @credentials: A #GCredentials.
14526 * @uid: The UNIX user identifier to set.
14527 * @error: Return location for error or %NULL.
14529 * Tries to set the UNIX user identifier on @credentials. This method
14530 * is only available on UNIX platforms.
14532 * This operation can fail if #GCredentials is not supported on the
14533 * OS or if the native credentials type does not contain information
14534 * about the UNIX user. It can also fail if the OS does not allow the
14535 * use of "spoofed" credentials.
14537 * Returns: %TRUE if @uid was set, %FALSE if error is set.
14543 * g_credentials_to_string:
14544 * @credentials: A #GCredentials object.
14546 * Creates a human-readable textual representation of @credentials
14547 * that can be used in logging and debug messages. The format of the
14548 * returned string may change in future GLib release.
14550 * Returns: (transfer full): A string that should be freed with g_free().
14556 * g_data_input_stream_get_byte_order:
14557 * @stream: a given #GDataInputStream.
14559 * Gets the byte order for the data input stream.
14561 * Returns: the @stream's current #GDataStreamByteOrder.
14566 * g_data_input_stream_get_newline_type:
14567 * @stream: a given #GDataInputStream.
14569 * Gets the current newline type for the @stream.
14571 * Returns: #GDataStreamNewlineType for the given @stream.
14576 * g_data_input_stream_new:
14577 * @base_stream: a #GInputStream.
14579 * Creates a new data input stream for the @base_stream.
14581 * Returns: a new #GDataInputStream.
14586 * g_data_input_stream_read_byte:
14587 * @stream: a given #GDataInputStream.
14588 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
14589 * @error: #GError for error reporting.
14591 * Reads an unsigned 8-bit/1-byte value from @stream.
14593 * Returns: an unsigned 8-bit/1-byte value read from the @stream or `0`
14594 * if an error occurred.
14599 * g_data_input_stream_read_int16:
14600 * @stream: a given #GDataInputStream.
14601 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
14602 * @error: #GError for error reporting.
14604 * Reads a 16-bit/2-byte value from @stream.
14606 * In order to get the correct byte order for this read operation,
14607 * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().
14609 * Returns: a signed 16-bit/2-byte value read from @stream or `0` if
14610 * an error occurred.
14615 * g_data_input_stream_read_int32:
14616 * @stream: a given #GDataInputStream.
14617 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
14618 * @error: #GError for error reporting.
14620 * Reads a signed 32-bit/4-byte value from @stream.
14622 * In order to get the correct byte order for this read operation,
14623 * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().
14625 * If @cancellable is not %NULL, then the operation can be cancelled by
14626 * triggering the cancellable object from another thread. If the operation
14627 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
14629 * Returns: a signed 32-bit/4-byte value read from the @stream or `0` if
14630 * an error occurred.
14635 * g_data_input_stream_read_int64:
14636 * @stream: a given #GDataInputStream.
14637 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
14638 * @error: #GError for error reporting.
14640 * Reads a 64-bit/8-byte value from @stream.
14642 * In order to get the correct byte order for this read operation,
14643 * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().
14645 * If @cancellable is not %NULL, then the operation can be cancelled by
14646 * triggering the cancellable object from another thread. If the operation
14647 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
14649 * Returns: a signed 64-bit/8-byte value read from @stream or `0` if
14650 * an error occurred.
14655 * g_data_input_stream_read_line:
14656 * @stream: a given #GDataInputStream.
14657 * @length: (out) (optional): a #gsize to get the length of the data read in.
14658 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
14659 * @error: #GError for error reporting.
14661 * Reads a line from the data input stream. Note that no encoding
14662 * checks or conversion is performed; the input is not guaranteed to
14663 * be UTF-8, and may in fact have embedded NUL characters.
14665 * If @cancellable is not %NULL, then the operation can be cancelled by
14666 * triggering the cancellable object from another thread. If the operation
14667 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
14669 * Returns: (nullable) (transfer full) (array zero-terminated=1) (element-type guint8):
14670 * a NUL terminated byte array with the line that was read in
14671 * (without the newlines). Set @length to a #gsize to get the length
14672 * of the read line. On an error, it will return %NULL and @error
14673 * will be set. If there's no content to read, it will still return
14674 * %NULL, but @error won't be set.
14679 * g_data_input_stream_read_line_async:
14680 * @stream: a given #GDataInputStream.
14681 * @io_priority: the [I/O priority][io-priority] of the request
14682 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
14683 * @callback: (scope async): callback to call when the request is satisfied.
14684 * @user_data: (closure): the data to pass to callback function.
14686 * The asynchronous version of g_data_input_stream_read_line(). It is
14687 * an error to have two outstanding calls to this function.
14689 * When the operation is finished, @callback will be called. You
14690 * can then call g_data_input_stream_read_line_finish() to get
14691 * the result of the operation.
14698 * g_data_input_stream_read_line_finish:
14699 * @stream: a given #GDataInputStream.
14700 * @result: the #GAsyncResult that was provided to the callback.
14701 * @length: (out) (optional): a #gsize to get the length of the data read in.
14702 * @error: #GError for error reporting.
14704 * Finish an asynchronous call started by
14705 * g_data_input_stream_read_line_async(). Note the warning about
14706 * string encoding in g_data_input_stream_read_line() applies here as
14709 * Returns: (nullable) (transfer full) (array zero-terminated=1) (element-type guint8):
14710 * a NUL-terminated byte array with the line that was read in
14711 * (without the newlines). Set @length to a #gsize to get the length
14712 * of the read line. On an error, it will return %NULL and @error
14713 * will be set. If there's no content to read, it will still return
14714 * %NULL, but @error won't be set.
14720 * g_data_input_stream_read_line_finish_utf8:
14721 * @stream: a given #GDataInputStream.
14722 * @result: the #GAsyncResult that was provided to the callback.
14723 * @length: (out) (optional): a #gsize to get the length of the data read in.
14724 * @error: #GError for error reporting.
14726 * Finish an asynchronous call started by
14727 * g_data_input_stream_read_line_async().
14729 * Returns: (nullable) (transfer full): a string with the line that
14730 * was read in (without the newlines). Set @length to a #gsize to
14731 * get the length of the read line. On an error, it will return
14732 * %NULL and @error will be set. For UTF-8 conversion errors, the set
14733 * error domain is %G_CONVERT_ERROR. If there's no content to read,
14734 * it will still return %NULL, but @error won't be set.
14740 * g_data_input_stream_read_line_utf8:
14741 * @stream: a given #GDataInputStream.
14742 * @length: (out) (optional): a #gsize to get the length of the data read in.
14743 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
14744 * @error: #GError for error reporting.
14746 * Reads a UTF-8 encoded line from the data input stream.
14748 * If @cancellable is not %NULL, then the operation can be cancelled by
14749 * triggering the cancellable object from another thread. If the operation
14750 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
14752 * Returns: (nullable) (transfer full): a NUL terminated UTF-8 string
14753 * with the line that was read in (without the newlines). Set
14754 * @length to a #gsize to get the length of the read line. On an
14755 * error, it will return %NULL and @error will be set. For UTF-8
14756 * conversion errors, the set error domain is %G_CONVERT_ERROR. If
14757 * there's no content to read, it will still return %NULL, but @error
14764 * g_data_input_stream_read_uint16:
14765 * @stream: a given #GDataInputStream.
14766 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
14767 * @error: #GError for error reporting.
14769 * Reads an unsigned 16-bit/2-byte value from @stream.
14771 * In order to get the correct byte order for this read operation,
14772 * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().
14774 * Returns: an unsigned 16-bit/2-byte value read from the @stream or `0` if
14775 * an error occurred.
14780 * g_data_input_stream_read_uint32:
14781 * @stream: a given #GDataInputStream.
14782 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
14783 * @error: #GError for error reporting.
14785 * Reads an unsigned 32-bit/4-byte value from @stream.
14787 * In order to get the correct byte order for this read operation,
14788 * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().
14790 * If @cancellable is not %NULL, then the operation can be cancelled by
14791 * triggering the cancellable object from another thread. If the operation
14792 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
14794 * Returns: an unsigned 32-bit/4-byte value read from the @stream or `0` if
14795 * an error occurred.
14800 * g_data_input_stream_read_uint64:
14801 * @stream: a given #GDataInputStream.
14802 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
14803 * @error: #GError for error reporting.
14805 * Reads an unsigned 64-bit/8-byte value from @stream.
14807 * In order to get the correct byte order for this read operation,
14808 * see g_data_input_stream_get_byte_order().
14810 * If @cancellable is not %NULL, then the operation can be cancelled by
14811 * triggering the cancellable object from another thread. If the operation
14812 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
14814 * Returns: an unsigned 64-bit/8-byte read from @stream or `0` if
14815 * an error occurred.
14820 * g_data_input_stream_read_until:
14821 * @stream: a given #GDataInputStream.
14822 * @stop_chars: characters to terminate the read.
14823 * @length: (out) (optional): a #gsize to get the length of the data read in.
14824 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
14825 * @error: #GError for error reporting.
14827 * Reads a string from the data input stream, up to the first
14828 * occurrence of any of the stop characters.
14830 * Note that, in contrast to g_data_input_stream_read_until_async(),
14831 * this function consumes the stop character that it finds.
14833 * Don't use this function in new code. Its functionality is
14834 * inconsistent with g_data_input_stream_read_until_async(). Both
14835 * functions will be marked as deprecated in a future release. Use
14836 * g_data_input_stream_read_upto() instead, but note that that function
14837 * does not consume the stop character.
14839 * Returns: (transfer full): a string with the data that was read
14840 * before encountering any of the stop characters. Set @length to
14841 * a #gsize to get the length of the string. This function will
14842 * return %NULL on an error.
14843 * Deprecated: 2.56: Use g_data_input_stream_read_upto() instead, which has more
14844 * consistent behaviour regarding the stop character.
14849 * g_data_input_stream_read_until_async:
14850 * @stream: a given #GDataInputStream.
14851 * @stop_chars: characters to terminate the read.
14852 * @io_priority: the [I/O priority][io-priority] of the request
14853 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
14854 * @callback: (scope async): callback to call when the request is satisfied.
14855 * @user_data: (closure): the data to pass to callback function.
14857 * The asynchronous version of g_data_input_stream_read_until().
14858 * It is an error to have two outstanding calls to this function.
14860 * Note that, in contrast to g_data_input_stream_read_until(),
14861 * this function does not consume the stop character that it finds. You
14862 * must read it for yourself.
14864 * When the operation is finished, @callback will be called. You
14865 * can then call g_data_input_stream_read_until_finish() to get
14866 * the result of the operation.
14868 * Don't use this function in new code. Its functionality is
14869 * inconsistent with g_data_input_stream_read_until(). Both functions
14870 * will be marked as deprecated in a future release. Use
14871 * g_data_input_stream_read_upto_async() instead.
14874 * Deprecated: 2.56: Use g_data_input_stream_read_upto_async() instead, which
14875 * has more consistent behaviour regarding the stop character.
14880 * g_data_input_stream_read_until_finish:
14881 * @stream: a given #GDataInputStream.
14882 * @result: the #GAsyncResult that was provided to the callback.
14883 * @length: (out) (optional): a #gsize to get the length of the data read in.
14884 * @error: #GError for error reporting.
14886 * Finish an asynchronous call started by
14887 * g_data_input_stream_read_until_async().
14890 * Returns: (transfer full): a string with the data that was read
14891 * before encountering any of the stop characters. Set @length to
14892 * a #gsize to get the length of the string. This function will
14893 * return %NULL on an error.
14894 * Deprecated: 2.56: Use g_data_input_stream_read_upto_finish() instead, which
14895 * has more consistent behaviour regarding the stop character.
14900 * g_data_input_stream_read_upto:
14901 * @stream: a #GDataInputStream
14902 * @stop_chars: characters to terminate the read
14903 * @stop_chars_len: length of @stop_chars. May be -1 if @stop_chars is
14905 * @length: (out) (optional): a #gsize to get the length of the data read in
14906 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore
14907 * @error: #GError for error reporting
14909 * Reads a string from the data input stream, up to the first
14910 * occurrence of any of the stop characters.
14912 * In contrast to g_data_input_stream_read_until(), this function
14913 * does not consume the stop character. You have to use
14914 * g_data_input_stream_read_byte() to get it before calling
14915 * g_data_input_stream_read_upto() again.
14917 * Note that @stop_chars may contain '\0' if @stop_chars_len is
14920 * The returned string will always be nul-terminated on success.
14922 * Returns: (transfer full): a string with the data that was read
14923 * before encountering any of the stop characters. Set @length to
14924 * a #gsize to get the length of the string. This function will
14925 * return %NULL on an error
14931 * g_data_input_stream_read_upto_async:
14932 * @stream: a #GDataInputStream
14933 * @stop_chars: characters to terminate the read
14934 * @stop_chars_len: length of @stop_chars. May be -1 if @stop_chars is
14936 * @io_priority: the [I/O priority][io-priority] of the request
14937 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore
14938 * @callback: (scope async): callback to call when the request is satisfied
14939 * @user_data: (closure): the data to pass to callback function
14941 * The asynchronous version of g_data_input_stream_read_upto().
14942 * It is an error to have two outstanding calls to this function.
14944 * In contrast to g_data_input_stream_read_until(), this function
14945 * does not consume the stop character. You have to use
14946 * g_data_input_stream_read_byte() to get it before calling
14947 * g_data_input_stream_read_upto() again.
14949 * Note that @stop_chars may contain '\0' if @stop_chars_len is
14952 * When the operation is finished, @callback will be called. You
14953 * can then call g_data_input_stream_read_upto_finish() to get
14954 * the result of the operation.
14961 * g_data_input_stream_read_upto_finish:
14962 * @stream: a #GDataInputStream
14963 * @result: the #GAsyncResult that was provided to the callback
14964 * @length: (out) (optional): a #gsize to get the length of the data read in
14965 * @error: #GError for error reporting
14967 * Finish an asynchronous call started by
14968 * g_data_input_stream_read_upto_async().
14970 * Note that this function does not consume the stop character. You
14971 * have to use g_data_input_stream_read_byte() to get it before calling
14972 * g_data_input_stream_read_upto_async() again.
14974 * The returned string will always be nul-terminated on success.
14976 * Returns: (transfer full): a string with the data that was read
14977 * before encountering any of the stop characters. Set @length to
14978 * a #gsize to get the length of the string. This function will
14979 * return %NULL on an error.
14985 * g_data_input_stream_set_byte_order:
14986 * @stream: a given #GDataInputStream.
14987 * @order: a #GDataStreamByteOrder to set.
14989 * This function sets the byte order for the given @stream. All subsequent
14990 * reads from the @stream will be read in the given @order.
14995 * g_data_input_stream_set_newline_type:
14996 * @stream: a #GDataInputStream.
14997 * @type: the type of new line return as #GDataStreamNewlineType.
14999 * Sets the newline type for the @stream.
15001 * Note that using G_DATA_STREAM_NEWLINE_TYPE_ANY is slightly unsafe. If a read
15002 * chunk ends in "CR" we must read an additional byte to know if this is "CR" or
15003 * "CR LF", and this might block if there is no more data available.
15008 * g_data_output_stream_get_byte_order:
15009 * @stream: a #GDataOutputStream.
15011 * Gets the byte order for the stream.
15013 * Returns: the #GDataStreamByteOrder for the @stream.
15018 * g_data_output_stream_new:
15019 * @base_stream: a #GOutputStream.
15021 * Creates a new data output stream for @base_stream.
15023 * Returns: #GDataOutputStream.
15028 * g_data_output_stream_put_byte:
15029 * @stream: a #GDataOutputStream.
15030 * @data: a #guchar.
15031 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
15032 * @error: a #GError, %NULL to ignore.
15034 * Puts a byte into the output stream.
15036 * Returns: %TRUE if @data was successfully added to the @stream.
15041 * g_data_output_stream_put_int16:
15042 * @stream: a #GDataOutputStream.
15043 * @data: a #gint16.
15044 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
15045 * @error: a #GError, %NULL to ignore.
15047 * Puts a signed 16-bit integer into the output stream.
15049 * Returns: %TRUE if @data was successfully added to the @stream.
15054 * g_data_output_stream_put_int32:
15055 * @stream: a #GDataOutputStream.
15056 * @data: a #gint32.
15057 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
15058 * @error: a #GError, %NULL to ignore.
15060 * Puts a signed 32-bit integer into the output stream.
15062 * Returns: %TRUE if @data was successfully added to the @stream.
15067 * g_data_output_stream_put_int64:
15068 * @stream: a #GDataOutputStream.
15069 * @data: a #gint64.
15070 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
15071 * @error: a #GError, %NULL to ignore.
15073 * Puts a signed 64-bit integer into the stream.
15075 * Returns: %TRUE if @data was successfully added to the @stream.
15080 * g_data_output_stream_put_string:
15081 * @stream: a #GDataOutputStream.
15083 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
15084 * @error: a #GError, %NULL to ignore.
15086 * Puts a string into the output stream.
15088 * Returns: %TRUE if @string was successfully added to the @stream.
15093 * g_data_output_stream_put_uint16:
15094 * @stream: a #GDataOutputStream.
15095 * @data: a #guint16.
15096 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
15097 * @error: a #GError, %NULL to ignore.
15099 * Puts an unsigned 16-bit integer into the output stream.
15101 * Returns: %TRUE if @data was successfully added to the @stream.
15106 * g_data_output_stream_put_uint32:
15107 * @stream: a #GDataOutputStream.
15108 * @data: a #guint32.
15109 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
15110 * @error: a #GError, %NULL to ignore.
15112 * Puts an unsigned 32-bit integer into the stream.
15114 * Returns: %TRUE if @data was successfully added to the @stream.
15119 * g_data_output_stream_put_uint64:
15120 * @stream: a #GDataOutputStream.
15121 * @data: a #guint64.
15122 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
15123 * @error: a #GError, %NULL to ignore.
15125 * Puts an unsigned 64-bit integer into the stream.
15127 * Returns: %TRUE if @data was successfully added to the @stream.
15132 * g_data_output_stream_set_byte_order:
15133 * @stream: a #GDataOutputStream.
15134 * @order: a %GDataStreamByteOrder.
15136 * Sets the byte order of the data output stream to @order.
15141 * g_datagram_based_condition_check:
15142 * @datagram_based: a #GDatagramBased
15143 * @condition: a #GIOCondition mask to check
15145 * Checks on the readiness of @datagram_based to perform operations. The
15146 * operations specified in @condition are checked for and masked against the
15147 * currently-satisfied conditions on @datagram_based. The result is returned.
15149 * %G_IO_IN will be set in the return value if data is available to read with
15150 * g_datagram_based_receive_messages(), or if the connection is closed remotely
15151 * (EOS); and if the datagram_based has not been closed locally using some
15152 * implementation-specific method (such as g_socket_close() or
15153 * g_socket_shutdown() with @shutdown_read set, if it’s a #GSocket).
15155 * If the connection is shut down or closed (by calling g_socket_close() or
15156 * g_socket_shutdown() with @shutdown_read set, if it’s a #GSocket, for
15157 * example), all calls to this function will return %G_IO_ERROR_CLOSED.
15159 * %G_IO_OUT will be set if it is expected that at least one byte can be sent
15160 * using g_datagram_based_send_messages() without blocking. It will not be set
15161 * if the datagram_based has been closed locally.
15163 * %G_IO_HUP will be set if the connection has been closed locally.
15165 * %G_IO_ERR will be set if there was an asynchronous error in transmitting data
15166 * previously enqueued using g_datagram_based_send_messages().
15168 * Note that on Windows, it is possible for an operation to return
15169 * %G_IO_ERROR_WOULD_BLOCK even immediately after
15170 * g_datagram_based_condition_check() has claimed that the #GDatagramBased is
15171 * ready for writing. Rather than calling g_datagram_based_condition_check() and
15172 * then writing to the #GDatagramBased if it succeeds, it is generally better to
15173 * simply try writing right away, and try again later if the initial attempt
15174 * returns %G_IO_ERROR_WOULD_BLOCK.
15176 * It is meaningless to specify %G_IO_ERR or %G_IO_HUP in @condition; these
15177 * conditions will always be set in the output if they are true. Apart from
15178 * these flags, the output is guaranteed to be masked by @condition.
15180 * This call never blocks.
15182 * Returns: the #GIOCondition mask of the current state
15188 * g_datagram_based_condition_wait:
15189 * @datagram_based: a #GDatagramBased
15190 * @condition: a #GIOCondition mask to wait for
15191 * @timeout: the maximum time (in microseconds) to wait, 0 to not block, or -1
15192 * to block indefinitely
15193 * @cancellable: (nullable): a #GCancellable
15194 * @error: return location for a #GError
15196 * Waits for up to @timeout microseconds for condition to become true on
15197 * @datagram_based. If the condition is met, %TRUE is returned.
15199 * If @cancellable is cancelled before the condition is met, or if @timeout is
15200 * reached before the condition is met, then %FALSE is returned and @error is
15201 * set appropriately (%G_IO_ERROR_CANCELLED or %G_IO_ERROR_TIMED_OUT).
15203 * Returns: %TRUE if the condition was met, %FALSE otherwise
15209 * g_datagram_based_create_source:
15210 * @datagram_based: a #GDatagramBased
15211 * @condition: a #GIOCondition mask to monitor
15212 * @cancellable: (nullable): a #GCancellable
15214 * Creates a #GSource that can be attached to a #GMainContext to monitor for
15215 * the availability of the specified @condition on the #GDatagramBased. The
15216 * #GSource keeps a reference to the @datagram_based.
15218 * The callback on the source is of the #GDatagramBasedSourceFunc type.
15220 * It is meaningless to specify %G_IO_ERR or %G_IO_HUP in @condition; these
15221 * conditions will always be reported in the callback if they are true.
15223 * If non-%NULL, @cancellable can be used to cancel the source, which will
15224 * cause the source to trigger, reporting the current condition (which is
15225 * likely 0 unless cancellation happened at the same time as a condition
15226 * change). You can check for this in the callback using
15227 * g_cancellable_is_cancelled().
15229 * Returns: (transfer full): a newly allocated #GSource
15235 * g_datagram_based_receive_messages:
15236 * @datagram_based: a #GDatagramBased
15237 * @messages: (array length=num_messages): an array of #GInputMessage structs
15238 * @num_messages: the number of elements in @messages
15239 * @flags: an int containing #GSocketMsgFlags flags for the overall operation
15240 * @timeout: the maximum time (in microseconds) to wait, 0 to not block, or -1
15241 * to block indefinitely
15242 * @cancellable: (nullable): a %GCancellable
15243 * @error: return location for a #GError
15245 * Receive one or more data messages from @datagram_based in one go.
15247 * @messages must point to an array of #GInputMessage structs and
15248 * @num_messages must be the length of this array. Each #GInputMessage
15249 * contains a pointer to an array of #GInputVector structs describing the
15250 * buffers that the data received in each message will be written to.
15252 * @flags modify how all messages are received. The commonly available
15253 * arguments for this are available in the #GSocketMsgFlags enum, but the
15254 * values there are the same as the system values, and the flags
15255 * are passed in as-is, so you can pass in system-specific flags too. These
15256 * flags affect the overall receive operation. Flags affecting individual
15257 * messages are returned in #GInputMessage.flags.
15259 * The other members of #GInputMessage are treated as described in its
15262 * If @timeout is negative the call will block until @num_messages have been
15263 * received, the connection is closed remotely (EOS), @cancellable is cancelled,
15264 * or an error occurs.
15266 * If @timeout is 0 the call will return up to @num_messages without blocking,
15267 * or %G_IO_ERROR_WOULD_BLOCK if no messages are queued in the operating system
15270 * If @timeout is positive the call will block on the same conditions as if
15271 * @timeout were negative. If the timeout is reached
15272 * before any messages are received, %G_IO_ERROR_TIMED_OUT is returned,
15273 * otherwise it will return the number of messages received before timing out.
15274 * (Note: This is effectively the behaviour of `MSG_WAITFORONE` with
15277 * To be notified when messages are available, wait for the %G_IO_IN condition.
15278 * Note though that you may still receive %G_IO_ERROR_WOULD_BLOCK from
15279 * g_datagram_based_receive_messages() even if you were previously notified of a
15280 * %G_IO_IN condition.
15282 * If the remote peer closes the connection, any messages queued in the
15283 * underlying receive buffer will be returned, and subsequent calls to
15284 * g_datagram_based_receive_messages() will return 0 (with no error set).
15286 * If the connection is shut down or closed (by calling g_socket_close() or
15287 * g_socket_shutdown() with @shutdown_read set, if it’s a #GSocket, for
15288 * example), all calls to this function will return %G_IO_ERROR_CLOSED.
15290 * On error -1 is returned and @error is set accordingly. An error will only
15291 * be returned if zero messages could be received; otherwise the number of
15292 * messages successfully received before the error will be returned. If
15293 * @cancellable is cancelled, %G_IO_ERROR_CANCELLED is returned as with any
15296 * Returns: number of messages received, or -1 on error. Note that the number
15297 * of messages received may be smaller than @num_messages if @timeout is
15298 * zero or positive, if the peer closed the connection, or if @num_messages
15299 * was larger than `UIO_MAXIOV` (1024), in which case the caller may re-try
15300 * to receive the remaining messages.
15306 * g_datagram_based_send_messages:
15307 * @datagram_based: a #GDatagramBased
15308 * @messages: (array length=num_messages): an array of #GOutputMessage structs
15309 * @num_messages: the number of elements in @messages
15310 * @flags: an int containing #GSocketMsgFlags flags
15311 * @timeout: the maximum time (in microseconds) to wait, 0 to not block, or -1
15312 * to block indefinitely
15313 * @cancellable: (nullable): a %GCancellable
15314 * @error: return location for a #GError
15316 * Send one or more data messages from @datagram_based in one go.
15318 * @messages must point to an array of #GOutputMessage structs and
15319 * @num_messages must be the length of this array. Each #GOutputMessage
15320 * contains an address to send the data to, and a pointer to an array of
15321 * #GOutputVector structs to describe the buffers that the data to be sent
15322 * for each message will be gathered from.
15324 * @flags modify how the message is sent. The commonly available arguments
15325 * for this are available in the #GSocketMsgFlags enum, but the
15326 * values there are the same as the system values, and the flags
15327 * are passed in as-is, so you can pass in system-specific flags too.
15329 * The other members of #GOutputMessage are treated as described in its
15332 * If @timeout is negative the call will block until @num_messages have been
15333 * sent, @cancellable is cancelled, or an error occurs.
15335 * If @timeout is 0 the call will send up to @num_messages without blocking,
15336 * or will return %G_IO_ERROR_WOULD_BLOCK if there is no space to send messages.
15338 * If @timeout is positive the call will block on the same conditions as if
15339 * @timeout were negative. If the timeout is reached before any messages are
15340 * sent, %G_IO_ERROR_TIMED_OUT is returned, otherwise it will return the number
15341 * of messages sent before timing out.
15343 * To be notified when messages can be sent, wait for the %G_IO_OUT condition.
15344 * Note though that you may still receive %G_IO_ERROR_WOULD_BLOCK from
15345 * g_datagram_based_send_messages() even if you were previously notified of a
15346 * %G_IO_OUT condition. (On Windows in particular, this is very common due to
15347 * the way the underlying APIs work.)
15349 * If the connection is shut down or closed (by calling g_socket_close() or
15350 * g_socket_shutdown() with @shutdown_write set, if it’s a #GSocket, for
15351 * example), all calls to this function will return %G_IO_ERROR_CLOSED.
15353 * On error -1 is returned and @error is set accordingly. An error will only
15354 * be returned if zero messages could be sent; otherwise the number of messages
15355 * successfully sent before the error will be returned. If @cancellable is
15356 * cancelled, %G_IO_ERROR_CANCELLED is returned as with any other error.
15358 * Returns: number of messages sent, or -1 on error. Note that the number of
15359 * messages sent may be smaller than @num_messages if @timeout is zero
15360 * or positive, or if @num_messages was larger than `UIO_MAXIOV` (1024), in
15361 * which case the caller may re-try to send the remaining messages.
15367 * g_dbus_action_group_get:
15368 * @connection: A #GDBusConnection
15369 * @bus_name: (nullable): the bus name which exports the action
15370 * group or %NULL if @connection is not a message bus connection
15371 * @object_path: the object path at which the action group is exported
15373 * Obtains a #GDBusActionGroup for the action group which is exported at
15374 * the given @bus_name and @object_path.
15376 * The thread default main context is taken at the time of this call.
15377 * All signals on the menu model (and any linked models) are reported
15378 * with respect to this context. All calls on the returned menu model
15379 * (and linked models) must also originate from this same context, with
15380 * the thread default main context unchanged.
15382 * This call is non-blocking. The returned action group may or may not
15383 * already be filled in. The correct thing to do is connect the signals
15384 * for the action group to monitor for changes and then to call
15385 * g_action_group_list_actions() to get the initial list.
15387 * Returns: (transfer full): a #GDBusActionGroup
15393 * g_dbus_address_escape_value:
15394 * @string: an unescaped string to be included in a D-Bus address
15395 * as the value in a key-value pair
15397 * Escape @string so it can appear in a D-Bus address as the value
15398 * part of a key-value pair.
15400 * For instance, if @string is `/run/bus-for-:0`,
15401 * this function would return `/run/bus-for-%3A0`,
15402 * which could be used in a D-Bus address like
15403 * `unix:nonce-tcp:host=127.0.0.1,port=42,noncefile=/run/bus-for-%3A0`.
15405 * Returns: (transfer full): a copy of @string with all
15406 * non-optionally-escaped bytes escaped
15412 * g_dbus_address_get_for_bus_sync:
15413 * @bus_type: a #GBusType
15414 * @cancellable: (nullable): a #GCancellable or %NULL
15415 * @error: return location for error or %NULL
15417 * Synchronously looks up the D-Bus address for the well-known message
15418 * bus instance specified by @bus_type. This may involve using various
15419 * platform specific mechanisms.
15421 * The returned address will be in the
15422 * [D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses).
15424 * Returns: (transfer full): a valid D-Bus address string for @bus_type or
15425 * %NULL if @error is set
15431 * g_dbus_address_get_stream:
15432 * @address: A valid D-Bus address.
15433 * @cancellable: (nullable): A #GCancellable or %NULL.
15434 * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
15435 * @user_data: Data to pass to @callback.
15437 * Asynchronously connects to an endpoint specified by @address and
15438 * sets up the connection so it is in a state to run the client-side
15439 * of the D-Bus authentication conversation. @address must be in the
15440 * [D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses).
15442 * When the operation is finished, @callback will be invoked. You can
15443 * then call g_dbus_address_get_stream_finish() to get the result of
15446 * This is an asynchronous failable function. See
15447 * g_dbus_address_get_stream_sync() for the synchronous version.
15454 * g_dbus_address_get_stream_finish:
15455 * @res: A #GAsyncResult obtained from the GAsyncReadyCallback passed to g_dbus_address_get_stream().
15456 * @out_guid: (optional) (out) (nullable): %NULL or return location to store the GUID extracted from @address, if any.
15457 * @error: Return location for error or %NULL.
15459 * Finishes an operation started with g_dbus_address_get_stream().
15461 * A server is not required to set a GUID, so @out_guid may be set to %NULL
15464 * Returns: (transfer full): A #GIOStream or %NULL if @error is set.
15470 * g_dbus_address_get_stream_sync:
15471 * @address: A valid D-Bus address.
15472 * @out_guid: (optional) (out) (nullable): %NULL or return location to store the GUID extracted from @address, if any.
15473 * @cancellable: (nullable): A #GCancellable or %NULL.
15474 * @error: Return location for error or %NULL.
15476 * Synchronously connects to an endpoint specified by @address and
15477 * sets up the connection so it is in a state to run the client-side
15478 * of the D-Bus authentication conversation. @address must be in the
15479 * [D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses).
15481 * A server is not required to set a GUID, so @out_guid may be set to %NULL
15484 * This is a synchronous failable function. See
15485 * g_dbus_address_get_stream() for the asynchronous version.
15487 * Returns: (transfer full): A #GIOStream or %NULL if @error is set.
15493 * g_dbus_annotation_info_lookup:
15494 * @annotations: (array zero-terminated=1) (nullable): A %NULL-terminated array of annotations or %NULL.
15495 * @name: The name of the annotation to look up.
15497 * Looks up the value of an annotation.
15499 * The cost of this function is O(n) in number of annotations.
15501 * Returns: (nullable): The value or %NULL if not found. Do not free, it is owned by @annotations.
15507 * g_dbus_annotation_info_ref:
15508 * @info: A #GDBusNodeInfo
15510 * If @info is statically allocated does nothing. Otherwise increases
15511 * the reference count.
15513 * Returns: (not nullable): The same @info.
15519 * g_dbus_annotation_info_unref:
15520 * @info: A #GDBusAnnotationInfo.
15522 * If @info is statically allocated, does nothing. Otherwise decreases
15523 * the reference count of @info. When its reference count drops to 0,
15524 * the memory used is freed.
15531 * g_dbus_arg_info_ref:
15532 * @info: A #GDBusArgInfo
15534 * If @info is statically allocated does nothing. Otherwise increases
15535 * the reference count.
15537 * Returns: (not nullable): The same @info.
15543 * g_dbus_arg_info_unref:
15544 * @info: A #GDBusArgInfo.
15546 * If @info is statically allocated, does nothing. Otherwise decreases
15547 * the reference count of @info. When its reference count drops to 0,
15548 * the memory used is freed.
15555 * g_dbus_auth_observer_allow_mechanism:
15556 * @observer: A #GDBusAuthObserver.
15557 * @mechanism: The name of the mechanism, e.g. `DBUS_COOKIE_SHA1`.
15559 * Emits the #GDBusAuthObserver::allow-mechanism signal on @observer.
15561 * Returns: %TRUE if @mechanism can be used to authenticate the other peer, %FALSE if not.
15567 * g_dbus_auth_observer_authorize_authenticated_peer:
15568 * @observer: A #GDBusAuthObserver.
15569 * @stream: A #GIOStream for the #GDBusConnection.
15570 * @credentials: (nullable): Credentials received from the peer or %NULL.
15572 * Emits the #GDBusAuthObserver::authorize-authenticated-peer signal on @observer.
15574 * Returns: %TRUE if the peer is authorized, %FALSE if not.
15580 * g_dbus_auth_observer_new:
15582 * Creates a new #GDBusAuthObserver object.
15584 * Returns: A #GDBusAuthObserver. Free with g_object_unref().
15590 * g_dbus_connection_add_filter:
15591 * @connection: a #GDBusConnection
15592 * @filter_function: a filter function
15593 * @user_data: user data to pass to @filter_function
15594 * @user_data_free_func: function to free @user_data with when filter
15595 * is removed or %NULL
15597 * Adds a message filter. Filters are handlers that are run on all
15598 * incoming and outgoing messages, prior to standard dispatch. Filters
15599 * are run in the order that they were added. The same handler can be
15600 * added as a filter more than once, in which case it will be run more
15601 * than once. Filters added during a filter callback won't be run on
15602 * the message being processed. Filter functions are allowed to modify
15603 * and even drop messages.
15605 * Note that filters are run in a dedicated message handling thread so
15606 * they can't block and, generally, can't do anything but signal a
15607 * worker thread. Also note that filters are rarely needed - use API
15608 * such as g_dbus_connection_send_message_with_reply(),
15609 * g_dbus_connection_signal_subscribe() or g_dbus_connection_call() instead.
15611 * If a filter consumes an incoming message the message is not
15612 * dispatched anywhere else - not even the standard dispatch machinery
15613 * (that API such as g_dbus_connection_signal_subscribe() and
15614 * g_dbus_connection_send_message_with_reply() relies on) will see the
15615 * message. Similarly, if a filter consumes an outgoing message, the
15616 * message will not be sent to the other peer.
15618 * If @user_data_free_func is non-%NULL, it will be called (in the
15619 * thread-default main context of the thread you are calling this
15620 * method from) at some point after @user_data is no longer
15621 * needed. (It is not guaranteed to be called synchronously when the
15622 * filter is removed, and may be called after @connection has been
15625 * Returns: a filter identifier that can be used with
15626 * g_dbus_connection_remove_filter()
15632 * g_dbus_connection_call:
15633 * @connection: a #GDBusConnection
15634 * @bus_name: (nullable): a unique or well-known bus name or %NULL if
15635 * @connection is not a message bus connection
15636 * @object_path: path of remote object
15637 * @interface_name: D-Bus interface to invoke method on
15638 * @method_name: the name of the method to invoke
15639 * @parameters: (nullable): a #GVariant tuple with parameters for the method
15640 * or %NULL if not passing parameters
15641 * @reply_type: (nullable): the expected type of the reply (which will be a
15643 * @flags: flags from the #GDBusCallFlags enumeration
15644 * @timeout_msec: the timeout in milliseconds, -1 to use the default
15645 * timeout or %G_MAXINT for no timeout
15646 * @cancellable: (nullable): a #GCancellable or %NULL
15647 * @callback: (nullable): a #GAsyncReadyCallback to call when the request
15648 * is satisfied or %NULL if you don't care about the result of the
15649 * method invocation
15650 * @user_data: the data to pass to @callback
15652 * Asynchronously invokes the @method_name method on the
15653 * @interface_name D-Bus interface on the remote object at
15654 * @object_path owned by @bus_name.
15656 * If @connection is closed then the operation will fail with
15657 * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will
15658 * fail with %G_IO_ERROR_CANCELLED. If @parameters contains a value
15659 * not compatible with the D-Bus protocol, the operation fails with
15660 * %G_IO_ERROR_INVALID_ARGUMENT.
15662 * If @reply_type is non-%NULL then the reply will be checked for having this type and an
15663 * error will be raised if it does not match. Said another way, if you give a @reply_type
15664 * then any non-%NULL return value will be of this type. Unless it’s
15665 * %G_VARIANT_TYPE_UNIT, the @reply_type will be a tuple containing one or more
15668 * If the @parameters #GVariant is floating, it is consumed. This allows
15669 * convenient 'inline' use of g_variant_new(), e.g.:
15670 * |[<!-- language="C" -->
15671 * g_dbus_connection_call (connection,
15672 * "org.freedesktop.StringThings",
15673 * "/org/freedesktop/StringThings",
15674 * "org.freedesktop.StringThings",
15676 * g_variant_new ("(ss)",
15680 * G_DBUS_CALL_FLAGS_NONE,
15683 * (GAsyncReadyCallback) two_strings_done,
15687 * This is an asynchronous method. When the operation is finished,
15688 * @callback will be invoked in the
15689 * [thread-default main context][g-main-context-push-thread-default]
15690 * of the thread you are calling this method from. You can then call
15691 * g_dbus_connection_call_finish() to get the result of the operation.
15692 * See g_dbus_connection_call_sync() for the synchronous version of this
15695 * If @callback is %NULL then the D-Bus method call message will be sent with
15696 * the %G_DBUS_MESSAGE_FLAGS_NO_REPLY_EXPECTED flag set.
15703 * g_dbus_connection_call_finish:
15704 * @connection: a #GDBusConnection
15705 * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_call()
15706 * @error: return location for error or %NULL
15708 * Finishes an operation started with g_dbus_connection_call().
15710 * Returns: (transfer full): %NULL if @error is set. Otherwise a non-floating
15711 * #GVariant tuple with return values. Free with g_variant_unref().
15717 * g_dbus_connection_call_sync:
15718 * @connection: a #GDBusConnection
15719 * @bus_name: (nullable): a unique or well-known bus name or %NULL if
15720 * @connection is not a message bus connection
15721 * @object_path: path of remote object
15722 * @interface_name: D-Bus interface to invoke method on
15723 * @method_name: the name of the method to invoke
15724 * @parameters: (nullable): a #GVariant tuple with parameters for the method
15725 * or %NULL if not passing parameters
15726 * @reply_type: (nullable): the expected type of the reply, or %NULL
15727 * @flags: flags from the #GDBusCallFlags enumeration
15728 * @timeout_msec: the timeout in milliseconds, -1 to use the default
15729 * timeout or %G_MAXINT for no timeout
15730 * @cancellable: (nullable): a #GCancellable or %NULL
15731 * @error: return location for error or %NULL
15733 * Synchronously invokes the @method_name method on the
15734 * @interface_name D-Bus interface on the remote object at
15735 * @object_path owned by @bus_name.
15737 * If @connection is closed then the operation will fail with
15738 * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the
15739 * operation will fail with %G_IO_ERROR_CANCELLED. If @parameters
15740 * contains a value not compatible with the D-Bus protocol, the operation
15741 * fails with %G_IO_ERROR_INVALID_ARGUMENT.
15743 * If @reply_type is non-%NULL then the reply will be checked for having
15744 * this type and an error will be raised if it does not match. Said
15745 * another way, if you give a @reply_type then any non-%NULL return
15746 * value will be of this type.
15748 * If the @parameters #GVariant is floating, it is consumed.
15749 * This allows convenient 'inline' use of g_variant_new(), e.g.:
15750 * |[<!-- language="C" -->
15751 * g_dbus_connection_call_sync (connection,
15752 * "org.freedesktop.StringThings",
15753 * "/org/freedesktop/StringThings",
15754 * "org.freedesktop.StringThings",
15756 * g_variant_new ("(ss)",
15760 * G_DBUS_CALL_FLAGS_NONE,
15766 * The calling thread is blocked until a reply is received. See
15767 * g_dbus_connection_call() for the asynchronous version of
15770 * Returns: (transfer full): %NULL if @error is set. Otherwise a non-floating
15771 * #GVariant tuple with return values. Free with g_variant_unref().
15777 * g_dbus_connection_call_with_unix_fd_list:
15778 * @connection: a #GDBusConnection
15779 * @bus_name: (nullable): a unique or well-known bus name or %NULL if
15780 * @connection is not a message bus connection
15781 * @object_path: path of remote object
15782 * @interface_name: D-Bus interface to invoke method on
15783 * @method_name: the name of the method to invoke
15784 * @parameters: (nullable): a #GVariant tuple with parameters for the method
15785 * or %NULL if not passing parameters
15786 * @reply_type: (nullable): the expected type of the reply, or %NULL
15787 * @flags: flags from the #GDBusCallFlags enumeration
15788 * @timeout_msec: the timeout in milliseconds, -1 to use the default
15789 * timeout or %G_MAXINT for no timeout
15790 * @fd_list: (nullable): a #GUnixFDList or %NULL
15791 * @cancellable: (nullable): a #GCancellable or %NULL
15792 * @callback: (nullable): a #GAsyncReadyCallback to call when the request is
15793 * satisfied or %NULL if you don't * care about the result of the
15794 * method invocation
15795 * @user_data: The data to pass to @callback.
15797 * Like g_dbus_connection_call() but also takes a #GUnixFDList object.
15799 * The file descriptors normally correspond to %G_VARIANT_TYPE_HANDLE
15800 * values in the body of the message. For example, if a message contains
15801 * two file descriptors, @fd_list would have length 2, and
15802 * `g_variant_new_handle (0)` and `g_variant_new_handle (1)` would appear
15803 * somewhere in the body of the message (not necessarily in that order!)
15804 * to represent the file descriptors at indexes 0 and 1 respectively.
15806 * When designing D-Bus APIs that are intended to be interoperable,
15807 * please note that non-GDBus implementations of D-Bus can usually only
15808 * access file descriptors if they are referenced in this way by a
15809 * value of type %G_VARIANT_TYPE_HANDLE in the body of the message.
15811 * This method is only available on UNIX.
15818 * g_dbus_connection_call_with_unix_fd_list_finish:
15819 * @connection: a #GDBusConnection
15820 * @out_fd_list: (out) (optional): return location for a #GUnixFDList or %NULL
15821 * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed to
15822 * g_dbus_connection_call_with_unix_fd_list()
15823 * @error: return location for error or %NULL
15825 * Finishes an operation started with g_dbus_connection_call_with_unix_fd_list().
15827 * The file descriptors normally correspond to %G_VARIANT_TYPE_HANDLE
15828 * values in the body of the message. For example,
15829 * if g_variant_get_handle() returns 5, that is intended to be a reference
15830 * to the file descriptor that can be accessed by
15831 * `g_unix_fd_list_get (*out_fd_list, 5, ...)`.
15833 * When designing D-Bus APIs that are intended to be interoperable,
15834 * please note that non-GDBus implementations of D-Bus can usually only
15835 * access file descriptors if they are referenced in this way by a
15836 * value of type %G_VARIANT_TYPE_HANDLE in the body of the message.
15838 * Returns: (transfer full): %NULL if @error is set. Otherwise a non-floating
15839 * #GVariant tuple with return values. Free with g_variant_unref().
15845 * g_dbus_connection_call_with_unix_fd_list_sync:
15846 * @connection: a #GDBusConnection
15847 * @bus_name: (nullable): a unique or well-known bus name or %NULL
15848 * if @connection is not a message bus connection
15849 * @object_path: path of remote object
15850 * @interface_name: D-Bus interface to invoke method on
15851 * @method_name: the name of the method to invoke
15852 * @parameters: (nullable): a #GVariant tuple with parameters for
15853 * the method or %NULL if not passing parameters
15854 * @reply_type: (nullable): the expected type of the reply, or %NULL
15855 * @flags: flags from the #GDBusCallFlags enumeration
15856 * @timeout_msec: the timeout in milliseconds, -1 to use the default
15857 * timeout or %G_MAXINT for no timeout
15858 * @fd_list: (nullable): a #GUnixFDList or %NULL
15859 * @out_fd_list: (out) (optional): return location for a #GUnixFDList or %NULL
15860 * @cancellable: (nullable): a #GCancellable or %NULL
15861 * @error: return location for error or %NULL
15863 * Like g_dbus_connection_call_sync() but also takes and returns #GUnixFDList objects.
15864 * See g_dbus_connection_call_with_unix_fd_list() and
15865 * g_dbus_connection_call_with_unix_fd_list_finish() for more details.
15867 * This method is only available on UNIX.
15869 * Returns: (transfer full): %NULL if @error is set. Otherwise a non-floating
15870 * #GVariant tuple with return values. Free with g_variant_unref().
15876 * g_dbus_connection_close:
15877 * @connection: a #GDBusConnection
15878 * @cancellable: (nullable): a #GCancellable or %NULL
15879 * @callback: (nullable): a #GAsyncReadyCallback to call when the request is
15880 * satisfied or %NULL if you don't care about the result
15881 * @user_data: The data to pass to @callback
15883 * Closes @connection. Note that this never causes the process to
15884 * exit (this might only happen if the other end of a shared message
15885 * bus connection disconnects, see #GDBusConnection:exit-on-close).
15887 * Once the connection is closed, operations such as sending a message
15888 * will return with the error %G_IO_ERROR_CLOSED. Closing a connection
15889 * will not automatically flush the connection so queued messages may
15890 * be lost. Use g_dbus_connection_flush() if you need such guarantees.
15892 * If @connection is already closed, this method fails with
15893 * %G_IO_ERROR_CLOSED.
15895 * When @connection has been closed, the #GDBusConnection::closed
15896 * signal is emitted in the
15897 * [thread-default main context][g-main-context-push-thread-default]
15898 * of the thread that @connection was constructed in.
15900 * This is an asynchronous method. When the operation is finished,
15901 * @callback will be invoked in the
15902 * [thread-default main context][g-main-context-push-thread-default]
15903 * of the thread you are calling this method from. You can
15904 * then call g_dbus_connection_close_finish() to get the result of the
15905 * operation. See g_dbus_connection_close_sync() for the synchronous
15913 * g_dbus_connection_close_finish:
15914 * @connection: a #GDBusConnection
15915 * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed
15916 * to g_dbus_connection_close()
15917 * @error: return location for error or %NULL
15919 * Finishes an operation started with g_dbus_connection_close().
15921 * Returns: %TRUE if the operation succeeded, %FALSE if @error is set
15927 * g_dbus_connection_close_sync:
15928 * @connection: a #GDBusConnection
15929 * @cancellable: (nullable): a #GCancellable or %NULL
15930 * @error: return location for error or %NULL
15932 * Synchronously closes @connection. The calling thread is blocked
15933 * until this is done. See g_dbus_connection_close() for the
15934 * asynchronous version of this method and more details about what it
15937 * Returns: %TRUE if the operation succeeded, %FALSE if @error is set
15943 * g_dbus_connection_emit_signal:
15944 * @connection: a #GDBusConnection
15945 * @destination_bus_name: (nullable): the unique bus name for the destination
15946 * for the signal or %NULL to emit to all listeners
15947 * @object_path: path of remote object
15948 * @interface_name: D-Bus interface to emit a signal on
15949 * @signal_name: the name of the signal to emit
15950 * @parameters: (nullable): a #GVariant tuple with parameters for the signal
15951 * or %NULL if not passing parameters
15952 * @error: Return location for error or %NULL
15956 * If the parameters GVariant is floating, it is consumed.
15958 * This can only fail if @parameters is not compatible with the D-Bus protocol
15959 * (%G_IO_ERROR_INVALID_ARGUMENT), or if @connection has been closed
15960 * (%G_IO_ERROR_CLOSED).
15962 * Returns: %TRUE unless @error is set
15968 * g_dbus_connection_export_action_group:
15969 * @connection: a #GDBusConnection
15970 * @object_path: a D-Bus object path
15971 * @action_group: a #GActionGroup
15972 * @error: a pointer to a %NULL #GError, or %NULL
15974 * Exports @action_group on @connection at @object_path.
15976 * The implemented D-Bus API should be considered private. It is
15977 * subject to change in the future.
15979 * A given object path can only have one action group exported on it.
15980 * If this constraint is violated, the export will fail and 0 will be
15981 * returned (with @error set accordingly).
15983 * You can unexport the action group using
15984 * g_dbus_connection_unexport_action_group() with the return value of
15987 * The thread default main context is taken at the time of this call.
15988 * All incoming action activations and state change requests are
15989 * reported from this context. Any changes on the action group that
15990 * cause it to emit signals must also come from this same context.
15991 * Since incoming action activations and state change requests are
15992 * rather likely to cause changes on the action group, this effectively
15993 * limits a given action group to being exported from only one main
15996 * Returns: the ID of the export (never zero), or 0 in case of failure
16002 * g_dbus_connection_export_menu_model:
16003 * @connection: a #GDBusConnection
16004 * @object_path: a D-Bus object path
16005 * @menu: a #GMenuModel
16006 * @error: return location for an error, or %NULL
16008 * Exports @menu on @connection at @object_path.
16010 * The implemented D-Bus API should be considered private.
16011 * It is subject to change in the future.
16013 * An object path can only have one menu model exported on it. If this
16014 * constraint is violated, the export will fail and 0 will be
16015 * returned (with @error set accordingly).
16017 * You can unexport the menu model using
16018 * g_dbus_connection_unexport_menu_model() with the return value of
16021 * Returns: the ID of the export (never zero), or 0 in case of failure
16027 * g_dbus_connection_flush:
16028 * @connection: a #GDBusConnection
16029 * @cancellable: (nullable): a #GCancellable or %NULL
16030 * @callback: (nullable): a #GAsyncReadyCallback to call when the
16031 * request is satisfied or %NULL if you don't care about the result
16032 * @user_data: The data to pass to @callback
16034 * Asynchronously flushes @connection, that is, writes all queued
16035 * outgoing message to the transport and then flushes the transport
16036 * (using g_output_stream_flush_async()). This is useful in programs
16037 * that wants to emit a D-Bus signal and then exit immediately. Without
16038 * flushing the connection, there is no guaranteed that the message has
16039 * been sent to the networking buffers in the OS kernel.
16041 * This is an asynchronous method. When the operation is finished,
16042 * @callback will be invoked in the
16043 * [thread-default main context][g-main-context-push-thread-default]
16044 * of the thread you are calling this method from. You can
16045 * then call g_dbus_connection_flush_finish() to get the result of the
16046 * operation. See g_dbus_connection_flush_sync() for the synchronous
16054 * g_dbus_connection_flush_finish:
16055 * @connection: a #GDBusConnection
16056 * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed
16057 * to g_dbus_connection_flush()
16058 * @error: return location for error or %NULL
16060 * Finishes an operation started with g_dbus_connection_flush().
16062 * Returns: %TRUE if the operation succeeded, %FALSE if @error is set
16068 * g_dbus_connection_flush_sync:
16069 * @connection: a #GDBusConnection
16070 * @cancellable: (nullable): a #GCancellable or %NULL
16071 * @error: return location for error or %NULL
16073 * Synchronously flushes @connection. The calling thread is blocked
16074 * until this is done. See g_dbus_connection_flush() for the
16075 * asynchronous version of this method and more details about what it
16078 * Returns: %TRUE if the operation succeeded, %FALSE if @error is set
16084 * g_dbus_connection_get_capabilities:
16085 * @connection: a #GDBusConnection
16087 * Gets the capabilities negotiated with the remote peer
16089 * Returns: zero or more flags from the #GDBusCapabilityFlags enumeration
16095 * g_dbus_connection_get_exit_on_close:
16096 * @connection: a #GDBusConnection
16098 * Gets whether the process is terminated when @connection is
16099 * closed by the remote peer. See
16100 * #GDBusConnection:exit-on-close for more details.
16102 * Returns: whether the process is terminated when @connection is
16103 * closed by the remote peer
16109 * g_dbus_connection_get_flags:
16110 * @connection: a #GDBusConnection
16112 * Gets the flags used to construct this connection
16114 * Returns: zero or more flags from the #GDBusConnectionFlags enumeration
16120 * g_dbus_connection_get_guid:
16121 * @connection: a #GDBusConnection
16123 * The GUID of the peer performing the role of server when
16124 * authenticating. See #GDBusConnection:guid for more details.
16126 * Returns: (not nullable): The GUID. Do not free this string, it is owned by
16133 * g_dbus_connection_get_last_serial:
16134 * @connection: a #GDBusConnection
16136 * Retrieves the last serial number assigned to a #GDBusMessage on
16137 * the current thread. This includes messages sent via both low-level
16138 * API such as g_dbus_connection_send_message() as well as
16139 * high-level API such as g_dbus_connection_emit_signal(),
16140 * g_dbus_connection_call() or g_dbus_proxy_call().
16142 * Returns: the last used serial or zero when no message has been sent
16143 * within the current thread
16149 * g_dbus_connection_get_peer_credentials:
16150 * @connection: a #GDBusConnection
16152 * Gets the credentials of the authenticated peer. This will always
16153 * return %NULL unless @connection acted as a server
16154 * (e.g. %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER was passed)
16155 * when set up and the client passed credentials as part of the
16156 * authentication process.
16158 * In a message bus setup, the message bus is always the server and
16159 * each application is a client. So this method will always return
16160 * %NULL for message bus clients.
16162 * Returns: (transfer none) (nullable): a #GCredentials or %NULL if not
16163 * available. Do not free this object, it is owned by @connection.
16169 * g_dbus_connection_get_stream:
16170 * @connection: a #GDBusConnection
16172 * Gets the underlying stream used for IO.
16174 * While the #GDBusConnection is active, it will interact with this
16175 * stream from a worker thread, so it is not safe to interact with
16176 * the stream directly.
16178 * Returns: (transfer none) (not nullable): the stream used for IO
16184 * g_dbus_connection_get_unique_name:
16185 * @connection: a #GDBusConnection
16187 * Gets the unique name of @connection as assigned by the message
16188 * bus. This can also be used to figure out if @connection is a
16189 * message bus connection.
16191 * Returns: (nullable): the unique name or %NULL if @connection is not a message
16192 * bus connection. Do not free this string, it is owned by
16199 * g_dbus_connection_is_closed:
16200 * @connection: a #GDBusConnection
16202 * Gets whether @connection is closed.
16204 * Returns: %TRUE if the connection is closed, %FALSE otherwise
16210 * g_dbus_connection_new:
16211 * @stream: a #GIOStream
16212 * @guid: (nullable): the GUID to use if authenticating as a server or %NULL
16213 * @flags: flags describing how to make the connection
16214 * @observer: (nullable): a #GDBusAuthObserver or %NULL
16215 * @cancellable: (nullable): a #GCancellable or %NULL
16216 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
16217 * @user_data: the data to pass to @callback
16219 * Asynchronously sets up a D-Bus connection for exchanging D-Bus messages
16220 * with the end represented by @stream.
16222 * If @stream is a #GSocketConnection, then the corresponding #GSocket
16223 * will be put into non-blocking mode.
16225 * The D-Bus connection will interact with @stream from a worker thread.
16226 * As a result, the caller should not interact with @stream after this
16227 * method has been called, except by calling g_object_unref() on it.
16229 * If @observer is not %NULL it may be used to control the
16230 * authentication process.
16232 * When the operation is finished, @callback will be invoked. You can
16233 * then call g_dbus_connection_new_finish() to get the result of the
16236 * This is an asynchronous failable constructor. See
16237 * g_dbus_connection_new_sync() for the synchronous
16245 * g_dbus_connection_new_finish:
16246 * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback
16247 * passed to g_dbus_connection_new().
16248 * @error: return location for error or %NULL
16250 * Finishes an operation started with g_dbus_connection_new().
16252 * Returns: (transfer full): a #GDBusConnection or %NULL if @error is set. Free
16253 * with g_object_unref().
16259 * g_dbus_connection_new_for_address:
16260 * @address: a D-Bus address
16261 * @flags: flags describing how to make the connection
16262 * @observer: (nullable): a #GDBusAuthObserver or %NULL
16263 * @cancellable: (nullable): a #GCancellable or %NULL
16264 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
16265 * @user_data: the data to pass to @callback
16267 * Asynchronously connects and sets up a D-Bus client connection for
16268 * exchanging D-Bus messages with an endpoint specified by @address
16269 * which must be in the
16270 * [D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses).
16272 * This constructor can only be used to initiate client-side
16273 * connections - use g_dbus_connection_new() if you need to act as the
16274 * server. In particular, @flags cannot contain the
16275 * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER,
16276 * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS or
16277 * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_REQUIRE_SAME_USER flags.
16279 * When the operation is finished, @callback will be invoked. You can
16280 * then call g_dbus_connection_new_for_address_finish() to get the result of
16283 * If @observer is not %NULL it may be used to control the
16284 * authentication process.
16286 * This is an asynchronous failable constructor. See
16287 * g_dbus_connection_new_for_address_sync() for the synchronous
16295 * g_dbus_connection_new_for_address_finish:
16296 * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed
16297 * to g_dbus_connection_new()
16298 * @error: return location for error or %NULL
16300 * Finishes an operation started with g_dbus_connection_new_for_address().
16302 * Returns: (transfer full): a #GDBusConnection or %NULL if @error is set.
16303 * Free with g_object_unref().
16309 * g_dbus_connection_new_for_address_sync:
16310 * @address: a D-Bus address
16311 * @flags: flags describing how to make the connection
16312 * @observer: (nullable): a #GDBusAuthObserver or %NULL
16313 * @cancellable: (nullable): a #GCancellable or %NULL
16314 * @error: return location for error or %NULL
16316 * Synchronously connects and sets up a D-Bus client connection for
16317 * exchanging D-Bus messages with an endpoint specified by @address
16318 * which must be in the
16319 * [D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses).
16321 * This constructor can only be used to initiate client-side
16322 * connections - use g_dbus_connection_new_sync() if you need to act
16323 * as the server. In particular, @flags cannot contain the
16324 * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER,
16325 * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS or
16326 * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_REQUIRE_SAME_USER flags.
16328 * This is a synchronous failable constructor. See
16329 * g_dbus_connection_new_for_address() for the asynchronous version.
16331 * If @observer is not %NULL it may be used to control the
16332 * authentication process.
16334 * Returns: (transfer full): a #GDBusConnection or %NULL if @error is set.
16335 * Free with g_object_unref().
16341 * g_dbus_connection_new_sync:
16342 * @stream: a #GIOStream
16343 * @guid: (nullable): the GUID to use if authenticating as a server or %NULL
16344 * @flags: flags describing how to make the connection
16345 * @observer: (nullable): a #GDBusAuthObserver or %NULL
16346 * @cancellable: (nullable): a #GCancellable or %NULL
16347 * @error: return location for error or %NULL
16349 * Synchronously sets up a D-Bus connection for exchanging D-Bus messages
16350 * with the end represented by @stream.
16352 * If @stream is a #GSocketConnection, then the corresponding #GSocket
16353 * will be put into non-blocking mode.
16355 * The D-Bus connection will interact with @stream from a worker thread.
16356 * As a result, the caller should not interact with @stream after this
16357 * method has been called, except by calling g_object_unref() on it.
16359 * If @observer is not %NULL it may be used to control the
16360 * authentication process.
16362 * This is a synchronous failable constructor. See
16363 * g_dbus_connection_new() for the asynchronous version.
16365 * Returns: (transfer full): a #GDBusConnection or %NULL if @error is set.
16366 * Free with g_object_unref().
16372 * g_dbus_connection_register_object:
16373 * @connection: a #GDBusConnection
16374 * @object_path: the object path to register at
16375 * @interface_info: introspection data for the interface
16376 * @vtable: (nullable): a #GDBusInterfaceVTable to call into or %NULL
16377 * @user_data: (nullable): data to pass to functions in @vtable
16378 * @user_data_free_func: function to call when the object path is unregistered
16379 * @error: return location for error or %NULL
16381 * Registers callbacks for exported objects at @object_path with the
16382 * D-Bus interface that is described in @interface_info.
16384 * Calls to functions in @vtable (and @user_data_free_func) will happen
16386 * [thread-default main context][g-main-context-push-thread-default]
16387 * of the thread you are calling this method from.
16389 * Note that all #GVariant values passed to functions in @vtable will match
16390 * the signature given in @interface_info - if a remote caller passes
16391 * incorrect values, the `org.freedesktop.DBus.Error.InvalidArgs`
16392 * is returned to the remote caller.
16394 * Additionally, if the remote caller attempts to invoke methods or
16395 * access properties not mentioned in @interface_info the
16396 * `org.freedesktop.DBus.Error.UnknownMethod` resp.
16397 * `org.freedesktop.DBus.Error.InvalidArgs` errors
16398 * are returned to the caller.
16400 * It is considered a programming error if the
16401 * #GDBusInterfaceGetPropertyFunc function in @vtable returns a
16402 * #GVariant of incorrect type.
16404 * If an existing callback is already registered at @object_path and
16405 * @interface_name, then @error is set to #G_IO_ERROR_EXISTS.
16407 * GDBus automatically implements the standard D-Bus interfaces
16408 * org.freedesktop.DBus.Properties, org.freedesktop.DBus.Introspectable
16409 * and org.freedesktop.Peer, so you don't have to implement those for the
16410 * objects you export. You can implement org.freedesktop.DBus.Properties
16411 * yourself, e.g. to handle getting and setting of properties asynchronously.
16413 * Note that the reference count on @interface_info will be
16414 * incremented by 1 (unless allocated statically, e.g. if the
16415 * reference count is -1, see g_dbus_interface_info_ref()) for as long
16416 * as the object is exported. Also note that @vtable will be copied.
16418 * See this [server][gdbus-server] for an example of how to use this method.
16420 * Returns: 0 if @error is set, otherwise a registration id (never 0)
16421 * that can be used with g_dbus_connection_unregister_object()
16427 * g_dbus_connection_register_object_with_closures: (rename-to g_dbus_connection_register_object)
16428 * @connection: A #GDBusConnection.
16429 * @object_path: The object path to register at.
16430 * @interface_info: Introspection data for the interface.
16431 * @method_call_closure: (nullable): #GClosure for handling incoming method calls.
16432 * @get_property_closure: (nullable): #GClosure for getting a property.
16433 * @set_property_closure: (nullable): #GClosure for setting a property.
16434 * @error: Return location for error or %NULL.
16436 * Version of g_dbus_connection_register_object() using closures instead of a
16437 * #GDBusInterfaceVTable for easier binding in other languages.
16439 * Returns: 0 if @error is set, otherwise a registration ID (never 0)
16440 * that can be used with g_dbus_connection_unregister_object() .
16446 * g_dbus_connection_register_subtree:
16447 * @connection: a #GDBusConnection
16448 * @object_path: the object path to register the subtree at
16449 * @vtable: a #GDBusSubtreeVTable to enumerate, introspect and
16450 * dispatch nodes in the subtree
16451 * @flags: flags used to fine tune the behavior of the subtree
16452 * @user_data: data to pass to functions in @vtable
16453 * @user_data_free_func: function to call when the subtree is unregistered
16454 * @error: return location for error or %NULL
16456 * Registers a whole subtree of dynamic objects.
16458 * The @enumerate and @introspection functions in @vtable are used to
16459 * convey, to remote callers, what nodes exist in the subtree rooted
16462 * When handling remote calls into any node in the subtree, first the
16463 * @enumerate function is used to check if the node exists. If the node exists
16464 * or the #G_DBUS_SUBTREE_FLAGS_DISPATCH_TO_UNENUMERATED_NODES flag is set
16465 * the @introspection function is used to check if the node supports the
16466 * requested method. If so, the @dispatch function is used to determine
16467 * where to dispatch the call. The collected #GDBusInterfaceVTable and
16468 * #gpointer will be used to call into the interface vtable for processing
16471 * All calls into user-provided code will be invoked in the
16472 * [thread-default main context][g-main-context-push-thread-default]
16473 * of the thread you are calling this method from.
16475 * If an existing subtree is already registered at @object_path or
16476 * then @error is set to #G_IO_ERROR_EXISTS.
16478 * Note that it is valid to register regular objects (using
16479 * g_dbus_connection_register_object()) in a subtree registered with
16480 * g_dbus_connection_register_subtree() - if so, the subtree handler
16481 * is tried as the last resort. One way to think about a subtree
16482 * handler is to consider it a fallback handler for object paths not
16483 * registered via g_dbus_connection_register_object() or other bindings.
16485 * Note that @vtable will be copied so you cannot change it after
16488 * See this [server][gdbus-subtree-server] for an example of how to use
16491 * Returns: 0 if @error is set, otherwise a subtree registration ID (never 0)
16492 * that can be used with g_dbus_connection_unregister_subtree()
16498 * g_dbus_connection_remove_filter:
16499 * @connection: a #GDBusConnection
16500 * @filter_id: an identifier obtained from g_dbus_connection_add_filter()
16502 * Removes a filter.
16504 * Note that since filters run in a different thread, there is a race
16505 * condition where it is possible that the filter will be running even
16506 * after calling g_dbus_connection_remove_filter(), so you cannot just
16507 * free data that the filter might be using. Instead, you should pass
16508 * a #GDestroyNotify to g_dbus_connection_add_filter(), which will be
16509 * called when it is guaranteed that the data is no longer needed.
16516 * g_dbus_connection_send_message:
16517 * @connection: a #GDBusConnection
16518 * @message: a #GDBusMessage
16519 * @flags: flags affecting how the message is sent
16520 * @out_serial: (out) (optional): return location for serial number assigned
16521 * to @message when sending it or %NULL
16522 * @error: Return location for error or %NULL
16524 * Asynchronously sends @message to the peer represented by @connection.
16526 * Unless @flags contain the
16527 * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number
16528 * will be assigned by @connection and set on @message via
16529 * g_dbus_message_set_serial(). If @out_serial is not %NULL, then the
16530 * serial number used will be written to this location prior to
16531 * submitting the message to the underlying transport. While it has a `volatile`
16532 * qualifier, this is a historical artifact and the argument passed to it should
16533 * not be `volatile`.
16535 * If @connection is closed then the operation will fail with
16536 * %G_IO_ERROR_CLOSED. If @message is not well-formed,
16537 * the operation fails with %G_IO_ERROR_INVALID_ARGUMENT.
16539 * See this [server][gdbus-server] and [client][gdbus-unix-fd-client]
16540 * for an example of how to use this low-level API to send and receive
16541 * UNIX file descriptors.
16543 * Note that @message must be unlocked, unless @flags contain the
16544 * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag.
16546 * Returns: %TRUE if the message was well-formed and queued for
16547 * transmission, %FALSE if @error is set
16553 * g_dbus_connection_send_message_with_reply:
16554 * @connection: a #GDBusConnection
16555 * @message: a #GDBusMessage
16556 * @flags: flags affecting how the message is sent
16557 * @timeout_msec: the timeout in milliseconds, -1 to use the default
16558 * timeout or %G_MAXINT for no timeout
16559 * @out_serial: (out) (optional): return location for serial number assigned
16560 * to @message when sending it or %NULL
16561 * @cancellable: (nullable): a #GCancellable or %NULL
16562 * @callback: (nullable): a #GAsyncReadyCallback to call when the request
16563 * is satisfied or %NULL if you don't care about the result
16564 * @user_data: The data to pass to @callback
16566 * Asynchronously sends @message to the peer represented by @connection.
16568 * Unless @flags contain the
16569 * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number
16570 * will be assigned by @connection and set on @message via
16571 * g_dbus_message_set_serial(). If @out_serial is not %NULL, then the
16572 * serial number used will be written to this location prior to
16573 * submitting the message to the underlying transport. While it has a `volatile`
16574 * qualifier, this is a historical artifact and the argument passed to it should
16575 * not be `volatile`.
16577 * If @connection is closed then the operation will fail with
16578 * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will
16579 * fail with %G_IO_ERROR_CANCELLED. If @message is not well-formed,
16580 * the operation fails with %G_IO_ERROR_INVALID_ARGUMENT.
16582 * This is an asynchronous method. When the operation is finished, @callback
16583 * will be invoked in the
16584 * [thread-default main context][g-main-context-push-thread-default]
16585 * of the thread you are calling this method from. You can then call
16586 * g_dbus_connection_send_message_with_reply_finish() to get the result of the operation.
16587 * See g_dbus_connection_send_message_with_reply_sync() for the synchronous version.
16589 * Note that @message must be unlocked, unless @flags contain the
16590 * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag.
16592 * See this [server][gdbus-server] and [client][gdbus-unix-fd-client]
16593 * for an example of how to use this low-level API to send and receive
16594 * UNIX file descriptors.
16601 * g_dbus_connection_send_message_with_reply_finish:
16602 * @connection: a #GDBusConnection
16603 * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed to
16604 * g_dbus_connection_send_message_with_reply()
16605 * @error: teturn location for error or %NULL
16607 * Finishes an operation started with g_dbus_connection_send_message_with_reply().
16609 * Note that @error is only set if a local in-process error
16610 * occurred. That is to say that the returned #GDBusMessage object may
16611 * be of type %G_DBUS_MESSAGE_TYPE_ERROR. Use
16612 * g_dbus_message_to_gerror() to transcode this to a #GError.
16614 * See this [server][gdbus-server] and [client][gdbus-unix-fd-client]
16615 * for an example of how to use this low-level API to send and receive
16616 * UNIX file descriptors.
16618 * Returns: (transfer full): a locked #GDBusMessage or %NULL if @error is set
16624 * g_dbus_connection_send_message_with_reply_sync:
16625 * @connection: a #GDBusConnection
16626 * @message: a #GDBusMessage
16627 * @flags: flags affecting how the message is sent.
16628 * @timeout_msec: the timeout in milliseconds, -1 to use the default
16629 * timeout or %G_MAXINT for no timeout
16630 * @out_serial: (out) (optional): return location for serial number
16631 * assigned to @message when sending it or %NULL
16632 * @cancellable: (nullable): a #GCancellable or %NULL
16633 * @error: return location for error or %NULL
16635 * Synchronously sends @message to the peer represented by @connection
16636 * and blocks the calling thread until a reply is received or the
16637 * timeout is reached. See g_dbus_connection_send_message_with_reply()
16638 * for the asynchronous version of this method.
16640 * Unless @flags contain the
16641 * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number
16642 * will be assigned by @connection and set on @message via
16643 * g_dbus_message_set_serial(). If @out_serial is not %NULL, then the
16644 * serial number used will be written to this location prior to
16645 * submitting the message to the underlying transport. While it has a `volatile`
16646 * qualifier, this is a historical artifact and the argument passed to it should
16647 * not be `volatile`.
16649 * If @connection is closed then the operation will fail with
16650 * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will
16651 * fail with %G_IO_ERROR_CANCELLED. If @message is not well-formed,
16652 * the operation fails with %G_IO_ERROR_INVALID_ARGUMENT.
16654 * Note that @error is only set if a local in-process error
16655 * occurred. That is to say that the returned #GDBusMessage object may
16656 * be of type %G_DBUS_MESSAGE_TYPE_ERROR. Use
16657 * g_dbus_message_to_gerror() to transcode this to a #GError.
16659 * See this [server][gdbus-server] and [client][gdbus-unix-fd-client]
16660 * for an example of how to use this low-level API to send and receive
16661 * UNIX file descriptors.
16663 * Note that @message must be unlocked, unless @flags contain the
16664 * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag.
16666 * Returns: (transfer full): a locked #GDBusMessage that is the reply
16667 * to @message or %NULL if @error is set
16673 * g_dbus_connection_set_exit_on_close:
16674 * @connection: a #GDBusConnection
16675 * @exit_on_close: whether the process should be terminated
16676 * when @connection is closed by the remote peer
16678 * Sets whether the process should be terminated when @connection is
16679 * closed by the remote peer. See #GDBusConnection:exit-on-close for
16682 * Note that this function should be used with care. Most modern UNIX
16683 * desktops tie the notion of a user session with the session bus, and expect
16684 * all of a user's applications to quit when their bus connection goes away.
16685 * If you are setting @exit_on_close to %FALSE for the shared session
16686 * bus connection, you should make sure that your application exits
16687 * when the user session ends.
16694 * g_dbus_connection_signal_subscribe:
16695 * @connection: a #GDBusConnection
16696 * @sender: (nullable): sender name to match on (unique or well-known name)
16697 * or %NULL to listen from all senders
16698 * @interface_name: (nullable): D-Bus interface name to match on or %NULL to
16699 * match on all interfaces
16700 * @member: (nullable): D-Bus signal name to match on or %NULL to match on
16702 * @object_path: (nullable): object path to match on or %NULL to match on
16704 * @arg0: (nullable): contents of first string argument to match on or %NULL
16705 * to match on all kinds of arguments
16706 * @flags: #GDBusSignalFlags describing how arg0 is used in subscribing to the
16708 * @callback: callback to invoke when there is a signal matching the requested data
16709 * @user_data: user data to pass to @callback
16710 * @user_data_free_func: (nullable): function to free @user_data with when
16711 * subscription is removed or %NULL
16713 * Subscribes to signals on @connection and invokes @callback with a whenever
16714 * the signal is received. Note that @callback will be invoked in the
16715 * [thread-default main context][g-main-context-push-thread-default]
16716 * of the thread you are calling this method from.
16718 * If @connection is not a message bus connection, @sender must be
16721 * If @sender is a well-known name note that @callback is invoked with
16722 * the unique name for the owner of @sender, not the well-known name
16723 * as one would expect. This is because the message bus rewrites the
16724 * name. As such, to avoid certain race conditions, users should be
16725 * tracking the name owner of the well-known name and use that when
16726 * processing the received signal.
16728 * If one of %G_DBUS_SIGNAL_FLAGS_MATCH_ARG0_NAMESPACE or
16729 * %G_DBUS_SIGNAL_FLAGS_MATCH_ARG0_PATH are given, @arg0 is
16730 * interpreted as part of a namespace or path. The first argument
16731 * of a signal is matched against that part as specified by D-Bus.
16733 * If @user_data_free_func is non-%NULL, it will be called (in the
16734 * thread-default main context of the thread you are calling this
16735 * method from) at some point after @user_data is no longer
16736 * needed. (It is not guaranteed to be called synchronously when the
16737 * signal is unsubscribed from, and may be called after @connection
16738 * has been destroyed.)
16740 * As @callback is potentially invoked in a different thread from where it’s
16741 * emitted, it’s possible for this to happen after
16742 * g_dbus_connection_signal_unsubscribe() has been called in another thread.
16743 * Due to this, @user_data should have a strong reference which is freed with
16744 * @user_data_free_func, rather than pointing to data whose lifecycle is tied
16745 * to the signal subscription. For example, if a #GObject is used to store the
16746 * subscription ID from g_dbus_connection_signal_subscribe(), a strong reference
16747 * to that #GObject must be passed to @user_data, and g_object_unref() passed to
16748 * @user_data_free_func. You are responsible for breaking the resulting
16749 * reference count cycle by explicitly unsubscribing from the signal when
16750 * dropping the last external reference to the #GObject. Alternatively, a weak
16751 * reference may be used.
16753 * It is guaranteed that if you unsubscribe from a signal using
16754 * g_dbus_connection_signal_unsubscribe() from the same thread which made the
16755 * corresponding g_dbus_connection_signal_subscribe() call, @callback will not
16756 * be invoked after g_dbus_connection_signal_unsubscribe() returns.
16758 * The returned subscription identifier is an opaque value which is guaranteed
16759 * to never be zero.
16761 * This function can never fail.
16763 * Returns: a subscription identifier that can be used with g_dbus_connection_signal_unsubscribe()
16769 * g_dbus_connection_signal_unsubscribe:
16770 * @connection: a #GDBusConnection
16771 * @subscription_id: a subscription id obtained from
16772 * g_dbus_connection_signal_subscribe()
16774 * Unsubscribes from signals.
16776 * Note that there may still be D-Bus traffic to process (relating to this
16777 * signal subscription) in the current thread-default #GMainContext after this
16778 * function has returned. You should continue to iterate the #GMainContext
16779 * until the #GDestroyNotify function passed to
16780 * g_dbus_connection_signal_subscribe() is called, in order to avoid memory
16781 * leaks through callbacks queued on the #GMainContext after it’s stopped being
16783 * Alternatively, any idle source with a priority lower than %G_PRIORITY_DEFAULT
16784 * that was scheduled after unsubscription, also indicates that all resources
16785 * of this subscription are released.
16792 * g_dbus_connection_start_message_processing:
16793 * @connection: a #GDBusConnection
16795 * If @connection was created with
16796 * %G_DBUS_CONNECTION_FLAGS_DELAY_MESSAGE_PROCESSING, this method
16797 * starts processing messages. Does nothing on if @connection wasn't
16798 * created with this flag or if the method has already been called.
16805 * g_dbus_connection_unexport_action_group:
16806 * @connection: a #GDBusConnection
16807 * @export_id: the ID from g_dbus_connection_export_action_group()
16809 * Reverses the effect of a previous call to
16810 * g_dbus_connection_export_action_group().
16812 * It is an error to call this function with an ID that wasn't returned
16813 * from g_dbus_connection_export_action_group() or to call it with the
16814 * same ID more than once.
16821 * g_dbus_connection_unexport_menu_model:
16822 * @connection: a #GDBusConnection
16823 * @export_id: the ID from g_dbus_connection_export_menu_model()
16825 * Reverses the effect of a previous call to
16826 * g_dbus_connection_export_menu_model().
16828 * It is an error to call this function with an ID that wasn't returned
16829 * from g_dbus_connection_export_menu_model() or to call it with the
16830 * same ID more than once.
16837 * g_dbus_connection_unregister_object:
16838 * @connection: a #GDBusConnection
16839 * @registration_id: a registration id obtained from
16840 * g_dbus_connection_register_object()
16842 * Unregisters an object.
16844 * Returns: %TRUE if the object was unregistered, %FALSE otherwise
16850 * g_dbus_connection_unregister_subtree:
16851 * @connection: a #GDBusConnection
16852 * @registration_id: a subtree registration id obtained from
16853 * g_dbus_connection_register_subtree()
16855 * Unregisters a subtree.
16857 * Returns: %TRUE if the subtree was unregistered, %FALSE otherwise
16863 * g_dbus_error_encode_gerror:
16864 * @error: A #GError.
16866 * Creates a D-Bus error name to use for @error. If @error matches
16867 * a registered error (cf. g_dbus_error_register_error()), the corresponding
16868 * D-Bus error name will be returned.
16870 * Otherwise the a name of the form
16871 * `org.gtk.GDBus.UnmappedGError.Quark._ESCAPED_QUARK_NAME.Code_ERROR_CODE`
16872 * will be used. This allows other GDBus applications to map the error
16873 * on the wire back to a #GError using g_dbus_error_new_for_dbus_error().
16875 * This function is typically only used in object mappings to put a
16876 * #GError on the wire. Regular applications should not use it.
16878 * Returns: (transfer full) (not nullable): A D-Bus error name (never %NULL).
16879 * Free with g_free().
16885 * g_dbus_error_get_remote_error:
16886 * @error: a #GError
16888 * Gets the D-Bus error name used for @error, if any.
16890 * This function is guaranteed to return a D-Bus error name for all
16891 * #GErrors returned from functions handling remote method calls
16892 * (e.g. g_dbus_connection_call_finish()) unless
16893 * g_dbus_error_strip_remote_error() has been used on @error.
16895 * Returns: (nullable) (transfer full): an allocated string or %NULL if the
16896 * D-Bus error name could not be found. Free with g_free().
16902 * g_dbus_error_is_remote_error:
16903 * @error: A #GError.
16905 * Checks if @error represents an error received via D-Bus from a remote peer. If so,
16906 * use g_dbus_error_get_remote_error() to get the name of the error.
16908 * Returns: %TRUE if @error represents an error from a remote peer,
16909 * %FALSE otherwise.
16915 * g_dbus_error_new_for_dbus_error:
16916 * @dbus_error_name: D-Bus error name.
16917 * @dbus_error_message: D-Bus error message.
16919 * Creates a #GError based on the contents of @dbus_error_name and
16920 * @dbus_error_message.
16922 * Errors registered with g_dbus_error_register_error() will be looked
16923 * up using @dbus_error_name and if a match is found, the error domain
16924 * and code is used. Applications can use g_dbus_error_get_remote_error()
16925 * to recover @dbus_error_name.
16927 * If a match against a registered error is not found and the D-Bus
16928 * error name is in a form as returned by g_dbus_error_encode_gerror()
16929 * the error domain and code encoded in the name is used to
16930 * create the #GError. Also, @dbus_error_name is added to the error message
16931 * such that it can be recovered with g_dbus_error_get_remote_error().
16933 * Otherwise, a #GError with the error code %G_IO_ERROR_DBUS_ERROR
16934 * in the #G_IO_ERROR error domain is returned. Also, @dbus_error_name is
16935 * added to the error message such that it can be recovered with
16936 * g_dbus_error_get_remote_error().
16938 * In all three cases, @dbus_error_name can always be recovered from the
16939 * returned #GError using the g_dbus_error_get_remote_error() function
16940 * (unless g_dbus_error_strip_remote_error() hasn't been used on the returned error).
16942 * This function is typically only used in object mappings to prepare
16943 * #GError instances for applications. Regular applications should not use
16946 * Returns: (transfer full): An allocated #GError. Free with g_error_free().
16952 * g_dbus_error_register_error:
16953 * @error_domain: A #GQuark for an error domain.
16954 * @error_code: An error code.
16955 * @dbus_error_name: A D-Bus error name.
16957 * Creates an association to map between @dbus_error_name and
16958 * #GErrors specified by @error_domain and @error_code.
16960 * This is typically done in the routine that returns the #GQuark for
16963 * Returns: %TRUE if the association was created, %FALSE if it already
16970 * g_dbus_error_register_error_domain:
16971 * @error_domain_quark_name: The error domain name.
16972 * @quark_volatile: A pointer where to store the #GQuark.
16973 * @entries: (array length=num_entries): A pointer to @num_entries #GDBusErrorEntry struct items.
16974 * @num_entries: Number of items to register.
16976 * Helper function for associating a #GError error domain with D-Bus error names.
16978 * While @quark_volatile has a `volatile` qualifier, this is a historical
16979 * artifact and the argument passed to it should not be `volatile`.
16986 * g_dbus_error_set_dbus_error:
16987 * @error: A pointer to a #GError or %NULL.
16988 * @dbus_error_name: D-Bus error name.
16989 * @dbus_error_message: D-Bus error message.
16990 * @format: (nullable): printf()-style format to prepend to @dbus_error_message or %NULL.
16991 * @...: Arguments for @format.
16993 * Does nothing if @error is %NULL. Otherwise sets *@error to
16994 * a new #GError created with g_dbus_error_new_for_dbus_error()
16995 * with @dbus_error_message prepend with @format (unless %NULL).
17002 * g_dbus_error_set_dbus_error_valist:
17003 * @error: A pointer to a #GError or %NULL.
17004 * @dbus_error_name: D-Bus error name.
17005 * @dbus_error_message: D-Bus error message.
17006 * @format: (nullable): printf()-style format to prepend to @dbus_error_message or %NULL.
17007 * @var_args: Arguments for @format.
17009 * Like g_dbus_error_set_dbus_error() but intended for language bindings.
17016 * g_dbus_error_strip_remote_error:
17017 * @error: A #GError.
17019 * Looks for extra information in the error message used to recover
17020 * the D-Bus error name and strips it if found. If stripped, the
17021 * message field in @error will correspond exactly to what was
17022 * received on the wire.
17024 * This is typically used when presenting errors to the end user.
17026 * Returns: %TRUE if information was stripped, %FALSE otherwise.
17032 * g_dbus_error_unregister_error:
17033 * @error_domain: A #GQuark for an error domain.
17034 * @error_code: An error code.
17035 * @dbus_error_name: A D-Bus error name.
17037 * Destroys an association previously set up with g_dbus_error_register_error().
17039 * Returns: %TRUE if the association was destroyed, %FALSE if it wasn't found.
17045 * g_dbus_escape_object_path:
17046 * @s: the string to escape
17048 * This is a language binding friendly version of g_dbus_escape_object_path_bytestring().
17050 * Returns: an escaped version of @s. Free with g_free().
17056 * g_dbus_escape_object_path_bytestring:
17057 * @bytes: (array zero-terminated=1) (element-type guint8): the string of bytes to escape
17059 * Escapes @bytes for use in a D-Bus object path component.
17060 * @bytes is an array of zero or more nonzero bytes in an
17061 * unspecified encoding, followed by a single zero byte.
17063 * The escaping method consists of replacing all non-alphanumeric
17064 * characters (see g_ascii_isalnum()) with their hexadecimal value
17065 * preceded by an underscore (`_`). For example:
17066 * `foo.bar.baz` will become `foo_2ebar_2ebaz`.
17068 * This method is appropriate to use when the input is nearly
17069 * a valid object path component but is not when your input
17070 * is far from being a valid object path component.
17071 * Other escaping algorithms are also valid to use with
17072 * D-Bus object paths.
17074 * This can be reversed with g_dbus_unescape_object_path().
17076 * Returns: an escaped version of @bytes. Free with g_free().
17082 * g_dbus_generate_guid:
17084 * Generate a D-Bus GUID that can be used with
17085 * e.g. g_dbus_connection_new().
17088 * [D-Bus specification](https://dbus.freedesktop.org/doc/dbus-specification.html#uuids)
17089 * regarding what strings are valid D-Bus GUIDs. The specification refers to
17090 * these as ‘UUIDs’ whereas GLib (for historical reasons) refers to them as
17091 * ‘GUIDs’. The terms are interchangeable.
17093 * Note that D-Bus GUIDs do not follow
17094 * [RFC 4122](https://datatracker.ietf.org/doc/html/rfc4122).
17096 * Returns: A valid D-Bus GUID. Free with g_free().
17102 * g_dbus_gvalue_to_gvariant:
17103 * @gvalue: A #GValue to convert to a #GVariant
17104 * @type: A #GVariantType
17106 * Converts a #GValue to a #GVariant of the type indicated by the @type
17109 * The conversion is using the following rules:
17111 * - #G_TYPE_STRING: 's', 'o', 'g' or 'ay'
17112 * - #G_TYPE_STRV: 'as', 'ao' or 'aay'
17113 * - #G_TYPE_BOOLEAN: 'b'
17114 * - #G_TYPE_UCHAR: 'y'
17115 * - #G_TYPE_INT: 'i', 'n'
17116 * - #G_TYPE_UINT: 'u', 'q'
17117 * - #G_TYPE_INT64 'x'
17118 * - #G_TYPE_UINT64: 't'
17119 * - #G_TYPE_DOUBLE: 'd'
17120 * - #G_TYPE_VARIANT: Any #GVariantType
17122 * This can fail if e.g. @gvalue is of type #G_TYPE_STRING and @type
17123 * is ['i'][G-VARIANT-TYPE-INT32:CAPS]. It will also fail for any #GType
17124 * (including e.g. #G_TYPE_OBJECT and #G_TYPE_BOXED derived-types) not
17125 * in the table above.
17127 * Note that if @gvalue is of type #G_TYPE_VARIANT and its value is
17128 * %NULL, the empty #GVariant instance (never %NULL) for @type is
17129 * returned (e.g. 0 for scalar types, the empty string for string types,
17130 * '/' for object path types, the empty array for any array type and so on).
17132 * See the g_dbus_gvariant_to_gvalue() function for how to convert a
17133 * #GVariant to a #GValue.
17135 * Returns: (transfer full): A #GVariant (never floating) of
17136 * #GVariantType @type holding the data from @gvalue or an empty #GVariant
17137 * in case of failure. Free with g_variant_unref().
17143 * g_dbus_gvariant_to_gvalue:
17144 * @value: A #GVariant.
17145 * @out_gvalue: (out): Return location pointing to a zero-filled (uninitialized) #GValue.
17147 * Converts a #GVariant to a #GValue. If @value is floating, it is consumed.
17149 * The rules specified in the g_dbus_gvalue_to_gvariant() function are
17150 * used - this function is essentially its reverse form. So, a #GVariant
17151 * containing any basic or string array type will be converted to a #GValue
17152 * containing a basic value or string array. Any other #GVariant (handle,
17153 * variant, tuple, dict entry) will be converted to a #GValue containing that
17156 * The conversion never fails - a valid #GValue is always returned in
17164 * g_dbus_interface_dup_object: (rename-to g_dbus_interface_get_object)
17165 * @interface_: An exported D-Bus interface.
17167 * Gets the #GDBusObject that @interface_ belongs to, if any.
17169 * Returns: (nullable) (transfer full): A #GDBusObject or %NULL. The returned
17170 * reference should be freed with g_object_unref().
17176 * g_dbus_interface_get_info:
17177 * @interface_: An exported D-Bus interface.
17179 * Gets D-Bus introspection information for the D-Bus interface
17180 * implemented by @interface_.
17182 * Returns: (transfer none): A #GDBusInterfaceInfo. Do not free.
17188 * g_dbus_interface_get_object: (skip)
17189 * @interface_: An exported D-Bus interface
17191 * Gets the #GDBusObject that @interface_ belongs to, if any.
17193 * It is not safe to use the returned object if @interface_ or
17194 * the returned object is being used from other threads. See
17195 * g_dbus_interface_dup_object() for a thread-safe alternative.
17197 * Returns: (nullable) (transfer none): A #GDBusObject or %NULL. The returned
17198 * reference belongs to @interface_ and should not be freed.
17204 * g_dbus_interface_info_cache_build:
17205 * @info: A #GDBusInterfaceInfo.
17207 * Builds a lookup-cache to speed up
17208 * g_dbus_interface_info_lookup_method(),
17209 * g_dbus_interface_info_lookup_signal() and
17210 * g_dbus_interface_info_lookup_property().
17212 * If this has already been called with @info, the existing cache is
17213 * used and its use count is increased.
17215 * Note that @info cannot be modified until
17216 * g_dbus_interface_info_cache_release() is called.
17223 * g_dbus_interface_info_cache_release:
17224 * @info: A GDBusInterfaceInfo
17226 * Decrements the usage count for the cache for @info built by
17227 * g_dbus_interface_info_cache_build() (if any) and frees the
17228 * resources used by the cache if the usage count drops to zero.
17235 * g_dbus_interface_info_generate_xml:
17236 * @info: A #GDBusNodeInfo
17237 * @indent: Indentation level.
17238 * @string_builder: A #GString to to append XML data to.
17240 * Appends an XML representation of @info (and its children) to @string_builder.
17242 * This function is typically used for generating introspection XML
17243 * documents at run-time for handling the
17244 * `org.freedesktop.DBus.Introspectable.Introspect`
17252 * g_dbus_interface_info_lookup_method:
17253 * @info: A #GDBusInterfaceInfo.
17254 * @name: A D-Bus method name (typically in CamelCase)
17256 * Looks up information about a method.
17258 * The cost of this function is O(n) in number of methods unless
17259 * g_dbus_interface_info_cache_build() has been used on @info.
17261 * Returns: (nullable) (transfer none): A #GDBusMethodInfo or %NULL if not found. Do not free, it is owned by @info.
17267 * g_dbus_interface_info_lookup_property:
17268 * @info: A #GDBusInterfaceInfo.
17269 * @name: A D-Bus property name (typically in CamelCase).
17271 * Looks up information about a property.
17273 * The cost of this function is O(n) in number of properties unless
17274 * g_dbus_interface_info_cache_build() has been used on @info.
17276 * Returns: (nullable) (transfer none): A #GDBusPropertyInfo or %NULL if not found. Do not free, it is owned by @info.
17282 * g_dbus_interface_info_lookup_signal:
17283 * @info: A #GDBusInterfaceInfo.
17284 * @name: A D-Bus signal name (typically in CamelCase)
17286 * Looks up information about a signal.
17288 * The cost of this function is O(n) in number of signals unless
17289 * g_dbus_interface_info_cache_build() has been used on @info.
17291 * Returns: (nullable) (transfer none): A #GDBusSignalInfo or %NULL if not found. Do not free, it is owned by @info.
17297 * g_dbus_interface_info_ref:
17298 * @info: A #GDBusInterfaceInfo
17300 * If @info is statically allocated does nothing. Otherwise increases
17301 * the reference count.
17303 * Returns: (not nullable): The same @info.
17309 * g_dbus_interface_info_unref:
17310 * @info: A #GDBusInterfaceInfo.
17312 * If @info is statically allocated, does nothing. Otherwise decreases
17313 * the reference count of @info. When its reference count drops to 0,
17314 * the memory used is freed.
17321 * g_dbus_interface_set_object:
17322 * @interface_: An exported D-Bus interface.
17323 * @object: (nullable): A #GDBusObject or %NULL.
17325 * Sets the #GDBusObject for @interface_ to @object.
17327 * Note that @interface_ will hold a weak reference to @object.
17334 * g_dbus_interface_skeleton_export:
17335 * @interface_: The D-Bus interface to export.
17336 * @connection: A #GDBusConnection to export @interface_ on.
17337 * @object_path: The path to export the interface at.
17338 * @error: Return location for error or %NULL.
17340 * Exports @interface_ at @object_path on @connection.
17342 * This can be called multiple times to export the same @interface_
17343 * onto multiple connections however the @object_path provided must be
17344 * the same for all connections.
17346 * Use g_dbus_interface_skeleton_unexport() to unexport the object.
17348 * Returns: %TRUE if the interface was exported on @connection, otherwise %FALSE with
17355 * g_dbus_interface_skeleton_flush:
17356 * @interface_: A #GDBusInterfaceSkeleton.
17358 * If @interface_ has outstanding changes, request for these changes to be
17359 * emitted immediately.
17361 * For example, an exported D-Bus interface may queue up property
17362 * changes and emit the
17363 * `org.freedesktop.DBus.Properties.PropertiesChanged`
17364 * signal later (e.g. in an idle handler). This technique is useful
17365 * for collapsing multiple property changes into one.
17372 * g_dbus_interface_skeleton_get_connection:
17373 * @interface_: A #GDBusInterfaceSkeleton.
17375 * Gets the first connection that @interface_ is exported on, if any.
17377 * Returns: (nullable) (transfer none): A #GDBusConnection or %NULL if @interface_ is
17378 * not exported anywhere. Do not free, the object belongs to @interface_.
17384 * g_dbus_interface_skeleton_get_connections:
17385 * @interface_: A #GDBusInterfaceSkeleton.
17387 * Gets a list of the connections that @interface_ is exported on.
17389 * Returns: (element-type GDBusConnection) (transfer full): A list of
17390 * all the connections that @interface_ is exported on. The returned
17391 * list should be freed with g_list_free() after each element has
17392 * been freed with g_object_unref().
17398 * g_dbus_interface_skeleton_get_flags:
17399 * @interface_: A #GDBusInterfaceSkeleton.
17401 * Gets the #GDBusInterfaceSkeletonFlags that describes what the behavior
17404 * Returns: One or more flags from the #GDBusInterfaceSkeletonFlags enumeration.
17410 * g_dbus_interface_skeleton_get_info:
17411 * @interface_: A #GDBusInterfaceSkeleton.
17413 * Gets D-Bus introspection information for the D-Bus interface
17414 * implemented by @interface_.
17416 * Returns: (transfer none): A #GDBusInterfaceInfo (never %NULL). Do not free.
17422 * g_dbus_interface_skeleton_get_object_path:
17423 * @interface_: A #GDBusInterfaceSkeleton.
17425 * Gets the object path that @interface_ is exported on, if any.
17427 * Returns: (nullable): A string owned by @interface_ or %NULL if @interface_ is not exported
17428 * anywhere. Do not free, the string belongs to @interface_.
17434 * g_dbus_interface_skeleton_get_properties:
17435 * @interface_: A #GDBusInterfaceSkeleton.
17437 * Gets all D-Bus properties for @interface_.
17439 * Returns: (transfer full): A #GVariant of type
17440 * ['a{sv}'][G-VARIANT-TYPE-VARDICT:CAPS].
17441 * Free with g_variant_unref().
17447 * g_dbus_interface_skeleton_get_vtable: (skip)
17448 * @interface_: A #GDBusInterfaceSkeleton.
17450 * Gets the interface vtable for the D-Bus interface implemented by
17451 * @interface_. The returned function pointers should expect @interface_
17452 * itself to be passed as @user_data.
17454 * Returns: A #GDBusInterfaceVTable (never %NULL).
17460 * g_dbus_interface_skeleton_has_connection:
17461 * @interface_: A #GDBusInterfaceSkeleton.
17462 * @connection: A #GDBusConnection.
17464 * Checks if @interface_ is exported on @connection.
17466 * Returns: %TRUE if @interface_ is exported on @connection, %FALSE otherwise.
17472 * g_dbus_interface_skeleton_set_flags:
17473 * @interface_: A #GDBusInterfaceSkeleton.
17474 * @flags: Flags from the #GDBusInterfaceSkeletonFlags enumeration.
17476 * Sets flags describing what the behavior of @skeleton should be.
17483 * g_dbus_interface_skeleton_unexport:
17484 * @interface_: A #GDBusInterfaceSkeleton.
17486 * Stops exporting @interface_ on all connections it is exported on.
17488 * To unexport @interface_ from only a single connection, use
17489 * g_dbus_interface_skeleton_unexport_from_connection()
17496 * g_dbus_interface_skeleton_unexport_from_connection:
17497 * @interface_: A #GDBusInterfaceSkeleton.
17498 * @connection: A #GDBusConnection.
17500 * Stops exporting @interface_ on @connection.
17502 * To stop exporting on all connections the interface is exported on,
17503 * use g_dbus_interface_skeleton_unexport().
17510 * g_dbus_is_address:
17511 * @string: A string.
17513 * Checks if @string is a
17514 * [D-Bus address](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses).
17516 * This doesn't check if @string is actually supported by #GDBusServer
17517 * or #GDBusConnection - use g_dbus_is_supported_address() to do more
17520 * Returns: %TRUE if @string is a valid D-Bus address, %FALSE otherwise.
17526 * g_dbus_is_error_name:
17527 * @string: The string to check.
17529 * Check whether @string is a valid D-Bus error name.
17531 * This function returns the same result as g_dbus_is_interface_name(),
17532 * because D-Bus error names are defined to have exactly the
17533 * same syntax as interface names.
17535 * Returns: %TRUE if valid, %FALSE otherwise.
17542 * @string: The string to check.
17544 * Checks if @string is a D-Bus GUID.
17546 * See the documentation for g_dbus_generate_guid() for more information about
17547 * the format of a GUID.
17549 * Returns: %TRUE if @string is a GUID, %FALSE otherwise.
17555 * g_dbus_is_interface_name:
17556 * @string: The string to check.
17558 * Checks if @string is a valid D-Bus interface name.
17560 * Returns: %TRUE if valid, %FALSE otherwise.
17566 * g_dbus_is_member_name:
17567 * @string: The string to check.
17569 * Checks if @string is a valid D-Bus member (e.g. signal or method) name.
17571 * Returns: %TRUE if valid, %FALSE otherwise.
17578 * @string: The string to check.
17580 * Checks if @string is a valid D-Bus bus name (either unique or well-known).
17582 * Returns: %TRUE if valid, %FALSE otherwise.
17588 * g_dbus_is_supported_address:
17589 * @string: A string.
17590 * @error: Return location for error or %NULL.
17592 * Like g_dbus_is_address() but also checks if the library supports the
17593 * transports in @string and that key/value pairs for each transport
17594 * are valid. See the specification of the
17595 * [D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses).
17597 * Returns: %TRUE if @string is a valid D-Bus address that is
17598 * supported by this library, %FALSE if @error is set.
17604 * g_dbus_is_unique_name:
17605 * @string: The string to check.
17607 * Checks if @string is a valid D-Bus unique bus name.
17609 * Returns: %TRUE if valid, %FALSE otherwise.
17615 * g_dbus_menu_model_get:
17616 * @connection: a #GDBusConnection
17617 * @bus_name: (nullable): the bus name which exports the menu model
17618 * or %NULL if @connection is not a message bus connection
17619 * @object_path: the object path at which the menu model is exported
17621 * Obtains a #GDBusMenuModel for the menu model which is exported
17622 * at the given @bus_name and @object_path.
17624 * The thread default main context is taken at the time of this call.
17625 * All signals on the menu model (and any linked models) are reported
17626 * with respect to this context. All calls on the returned menu model
17627 * (and linked models) must also originate from this same context, with
17628 * the thread default main context unchanged.
17630 * Returns: (transfer full): a #GDBusMenuModel object. Free with
17631 * g_object_unref().
17637 * g_dbus_message_bytes_needed:
17638 * @blob: (array length=blob_len) (element-type guint8): A blob representing a binary D-Bus message.
17639 * @blob_len: The length of @blob (must be at least 16).
17640 * @error: Return location for error or %NULL.
17642 * Utility function to calculate how many bytes are needed to
17643 * completely deserialize the D-Bus message stored at @blob.
17645 * Returns: Number of bytes needed or -1 if @error is set (e.g. if
17646 * @blob contains invalid data or not enough data is available to
17647 * determine the size).
17653 * g_dbus_message_copy:
17654 * @message: A #GDBusMessage.
17655 * @error: Return location for error or %NULL.
17657 * Copies @message. The copy is a deep copy and the returned
17658 * #GDBusMessage is completely identical except that it is guaranteed
17659 * to not be locked.
17661 * This operation can fail if e.g. @message contains file descriptors
17662 * and the per-process or system-wide open files limit is reached.
17664 * Returns: (transfer full): A new #GDBusMessage or %NULL if @error is set.
17665 * Free with g_object_unref().
17671 * g_dbus_message_get_arg0:
17672 * @message: A #GDBusMessage.
17674 * Convenience to get the first item in the body of @message.
17676 * Returns: (nullable): The string item or %NULL if the first item in the body of
17677 * @message is not a string.
17683 * g_dbus_message_get_body:
17684 * @message: A #GDBusMessage.
17686 * Gets the body of a message.
17688 * Returns: (nullable) (transfer none): A #GVariant or %NULL if the body is
17689 * empty. Do not free, it is owned by @message.
17695 * g_dbus_message_get_byte_order:
17696 * @message: A #GDBusMessage.
17698 * Gets the byte order of @message.
17700 * Returns: The byte order.
17705 * g_dbus_message_get_destination:
17706 * @message: A #GDBusMessage.
17708 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field.
17710 * Returns: (nullable): The value.
17716 * g_dbus_message_get_error_name:
17717 * @message: A #GDBusMessage.
17719 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field.
17721 * Returns: (nullable): The value.
17727 * g_dbus_message_get_flags:
17728 * @message: A #GDBusMessage.
17730 * Gets the flags for @message.
17732 * Returns: Flags that are set (typically values from the #GDBusMessageFlags enumeration bitwise ORed together).
17738 * g_dbus_message_get_header:
17739 * @message: A #GDBusMessage.
17740 * @header_field: A 8-bit unsigned integer (typically a value from the #GDBusMessageHeaderField enumeration)
17742 * Gets a header field on @message.
17744 * The caller is responsible for checking the type of the returned #GVariant
17745 * matches what is expected.
17747 * Returns: (transfer none) (nullable): A #GVariant with the value if the header was found, %NULL
17748 * otherwise. Do not free, it is owned by @message.
17754 * g_dbus_message_get_header_fields:
17755 * @message: A #GDBusMessage.
17757 * Gets an array of all header fields on @message that are set.
17759 * Returns: (array zero-terminated=1): An array of header fields
17760 * terminated by %G_DBUS_MESSAGE_HEADER_FIELD_INVALID. Each element
17761 * is a #guchar. Free with g_free().
17767 * g_dbus_message_get_interface:
17768 * @message: A #GDBusMessage.
17770 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE header field.
17772 * Returns: (nullable): The value.
17778 * g_dbus_message_get_locked:
17779 * @message: A #GDBusMessage.
17781 * Checks whether @message is locked. To monitor changes to this
17782 * value, conncet to the #GObject::notify signal to listen for changes
17783 * on the #GDBusMessage:locked property.
17785 * Returns: %TRUE if @message is locked, %FALSE otherwise.
17791 * g_dbus_message_get_member:
17792 * @message: A #GDBusMessage.
17794 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_MEMBER header field.
17796 * Returns: (nullable): The value.
17802 * g_dbus_message_get_message_type:
17803 * @message: A #GDBusMessage.
17805 * Gets the type of @message.
17807 * Returns: A 8-bit unsigned integer (typically a value from the #GDBusMessageType enumeration).
17813 * g_dbus_message_get_num_unix_fds:
17814 * @message: A #GDBusMessage.
17816 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header field.
17818 * Returns: The value.
17824 * g_dbus_message_get_path:
17825 * @message: A #GDBusMessage.
17827 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_PATH header field.
17829 * Returns: (nullable): The value.
17835 * g_dbus_message_get_reply_serial:
17836 * @message: A #GDBusMessage.
17838 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL header field.
17840 * Returns: The value.
17846 * g_dbus_message_get_sender:
17847 * @message: A #GDBusMessage.
17849 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_SENDER header field.
17851 * Returns: (nullable): The value.
17857 * g_dbus_message_get_serial:
17858 * @message: A #GDBusMessage.
17860 * Gets the serial for @message.
17862 * Returns: A #guint32.
17868 * g_dbus_message_get_signature:
17869 * @message: A #GDBusMessage.
17871 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field.
17873 * This will always be non-%NULL, but may be an empty string.
17875 * Returns: (not nullable): The value.
17881 * g_dbus_message_get_unix_fd_list:
17882 * @message: A #GDBusMessage.
17884 * Gets the UNIX file descriptors associated with @message, if any.
17886 * This method is only available on UNIX.
17888 * The file descriptors normally correspond to %G_VARIANT_TYPE_HANDLE
17889 * values in the body of the message. For example,
17890 * if g_variant_get_handle() returns 5, that is intended to be a reference
17891 * to the file descriptor that can be accessed by
17892 * `g_unix_fd_list_get (list, 5, ...)`.
17894 * Returns: (nullable) (transfer none): A #GUnixFDList or %NULL if no file descriptors are
17895 * associated. Do not free, this object is owned by @message.
17901 * g_dbus_message_lock:
17902 * @message: A #GDBusMessage.
17904 * If @message is locked, does nothing. Otherwise locks the message.
17911 * g_dbus_message_new:
17913 * Creates a new empty #GDBusMessage.
17915 * Returns: A #GDBusMessage. Free with g_object_unref().
17921 * g_dbus_message_new_from_blob:
17922 * @blob: (array length=blob_len) (element-type guint8): A blob representing a binary D-Bus message.
17923 * @blob_len: The length of @blob.
17924 * @capabilities: A #GDBusCapabilityFlags describing what protocol features are supported.
17925 * @error: Return location for error or %NULL.
17927 * Creates a new #GDBusMessage from the data stored at @blob. The byte
17928 * order that the message was in can be retrieved using
17929 * g_dbus_message_get_byte_order().
17931 * If the @blob cannot be parsed, contains invalid fields, or contains invalid
17932 * headers, %G_IO_ERROR_INVALID_ARGUMENT will be returned.
17934 * Returns: A new #GDBusMessage or %NULL if @error is set. Free with
17935 * g_object_unref().
17941 * g_dbus_message_new_method_call:
17942 * @name: (nullable): A valid D-Bus name or %NULL.
17943 * @path: A valid object path.
17944 * @interface_: (nullable): A valid D-Bus interface name or %NULL.
17945 * @method: A valid method name.
17947 * Creates a new #GDBusMessage for a method call.
17949 * Returns: A #GDBusMessage. Free with g_object_unref().
17955 * g_dbus_message_new_method_error:
17956 * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to
17957 * create a reply message to.
17958 * @error_name: A valid D-Bus error name.
17959 * @error_message_format: The D-Bus error message in a printf() format.
17960 * @...: Arguments for @error_message_format.
17962 * Creates a new #GDBusMessage that is an error reply to @method_call_message.
17964 * Returns: (transfer full): A #GDBusMessage. Free with g_object_unref().
17970 * g_dbus_message_new_method_error_literal:
17971 * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to
17972 * create a reply message to.
17973 * @error_name: A valid D-Bus error name.
17974 * @error_message: The D-Bus error message.
17976 * Creates a new #GDBusMessage that is an error reply to @method_call_message.
17978 * Returns: (transfer full): A #GDBusMessage. Free with g_object_unref().
17984 * g_dbus_message_new_method_error_valist:
17985 * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to
17986 * create a reply message to.
17987 * @error_name: A valid D-Bus error name.
17988 * @error_message_format: The D-Bus error message in a printf() format.
17989 * @var_args: Arguments for @error_message_format.
17991 * Like g_dbus_message_new_method_error() but intended for language bindings.
17993 * Returns: (transfer full): A #GDBusMessage. Free with g_object_unref().
17999 * g_dbus_message_new_method_reply:
18000 * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to
18001 * create a reply message to.
18003 * Creates a new #GDBusMessage that is a reply to @method_call_message.
18005 * Returns: (transfer full): #GDBusMessage. Free with g_object_unref().
18011 * g_dbus_message_new_signal:
18012 * @path: A valid object path.
18013 * @interface_: A valid D-Bus interface name.
18014 * @signal: A valid signal name.
18016 * Creates a new #GDBusMessage for a signal emission.
18018 * Returns: A #GDBusMessage. Free with g_object_unref().
18024 * g_dbus_message_print: (type method-return)
18025 * @message: A #GDBusMessage.
18026 * @indent: Indentation level.
18028 * Produces a human-readable multi-line description of @message.
18030 * The contents of the description has no ABI guarantees, the contents
18031 * and formatting is subject to change at any time. Typical output
18032 * looks something like this:
18038 * path -> objectpath '/org/gtk/GDBus/TestObject'
18039 * interface -> 'org.gtk.GDBus.TestInterface'
18040 * member -> 'GimmeStdout'
18041 * destination -> ':1.146'
18043 * UNIX File Descriptors:
18048 * Flags: no-reply-expected
18052 * reply-serial -> uint32 4
18053 * destination -> ':1.159'
18054 * sender -> ':1.146'
18055 * num-unix-fds -> uint32 1
18057 * UNIX File Descriptors:
18058 * fd 12: dev=0:10,mode=020620,ino=5,uid=500,gid=5,rdev=136:2,size=0,atime=1273085037,mtime=1273085851,ctime=1272982635
18061 * Returns: (not nullable): A string that should be freed with g_free().
18067 * g_dbus_message_set_body:
18068 * @message: A #GDBusMessage.
18069 * @body: Either %NULL or a #GVariant that is a tuple.
18071 * Sets the body @message. As a side-effect the
18072 * %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field is set to the
18073 * type string of @body (or cleared if @body is %NULL).
18075 * If @body is floating, @message assumes ownership of @body.
18082 * g_dbus_message_set_byte_order:
18083 * @message: A #GDBusMessage.
18084 * @byte_order: The byte order.
18086 * Sets the byte order of @message.
18091 * g_dbus_message_set_destination:
18092 * @message: A #GDBusMessage.
18093 * @value: (nullable): The value to set.
18095 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field.
18102 * g_dbus_message_set_error_name:
18103 * @message: (nullable): A #GDBusMessage.
18104 * @value: The value to set.
18106 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field.
18113 * g_dbus_message_set_flags:
18114 * @message: A #GDBusMessage.
18115 * @flags: Flags for @message that are set (typically values from the #GDBusMessageFlags
18116 * enumeration bitwise ORed together).
18118 * Sets the flags to set on @message.
18125 * g_dbus_message_set_header:
18126 * @message: A #GDBusMessage.
18127 * @header_field: A 8-bit unsigned integer (typically a value from the #GDBusMessageHeaderField enumeration)
18128 * @value: (nullable): A #GVariant to set the header field or %NULL to clear the header field.
18130 * Sets a header field on @message.
18132 * If @value is floating, @message assumes ownership of @value.
18139 * g_dbus_message_set_interface:
18140 * @message: A #GDBusMessage.
18141 * @value: (nullable): The value to set.
18143 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE header field.
18150 * g_dbus_message_set_member:
18151 * @message: A #GDBusMessage.
18152 * @value: (nullable): The value to set.
18154 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_MEMBER header field.
18161 * g_dbus_message_set_message_type:
18162 * @message: A #GDBusMessage.
18163 * @type: A 8-bit unsigned integer (typically a value from the #GDBusMessageType enumeration).
18165 * Sets @message to be of @type.
18172 * g_dbus_message_set_num_unix_fds:
18173 * @message: A #GDBusMessage.
18174 * @value: The value to set.
18176 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header field.
18183 * g_dbus_message_set_path:
18184 * @message: A #GDBusMessage.
18185 * @value: (nullable): The value to set.
18187 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_PATH header field.
18194 * g_dbus_message_set_reply_serial:
18195 * @message: A #GDBusMessage.
18196 * @value: The value to set.
18198 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL header field.
18205 * g_dbus_message_set_sender:
18206 * @message: A #GDBusMessage.
18207 * @value: (nullable): The value to set.
18209 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_SENDER header field.
18216 * g_dbus_message_set_serial:
18217 * @message: A #GDBusMessage.
18218 * @serial: A #guint32.
18220 * Sets the serial for @message.
18227 * g_dbus_message_set_signature:
18228 * @message: A #GDBusMessage.
18229 * @value: (nullable): The value to set.
18231 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field.
18238 * g_dbus_message_set_unix_fd_list:
18239 * @message: A #GDBusMessage.
18240 * @fd_list: (nullable): A #GUnixFDList or %NULL.
18242 * Sets the UNIX file descriptors associated with @message. As a
18243 * side-effect the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header
18244 * field is set to the number of fds in @fd_list (or cleared if
18245 * @fd_list is %NULL).
18247 * This method is only available on UNIX.
18249 * When designing D-Bus APIs that are intended to be interoperable,
18250 * please note that non-GDBus implementations of D-Bus can usually only
18251 * access file descriptors if they are referenced by a value of type
18252 * %G_VARIANT_TYPE_HANDLE in the body of the message.
18259 * g_dbus_message_to_blob:
18260 * @message: A #GDBusMessage.
18261 * @out_size: Return location for size of generated blob.
18262 * @capabilities: A #GDBusCapabilityFlags describing what protocol features are supported.
18263 * @error: Return location for error.
18265 * Serializes @message to a blob. The byte order returned by
18266 * g_dbus_message_get_byte_order() will be used.
18268 * Returns: (array length=out_size) (transfer full): A pointer to a
18269 * valid binary D-Bus message of @out_size bytes generated by @message
18270 * or %NULL if @error is set. Free with g_free().
18276 * g_dbus_message_to_gerror:
18277 * @message: A #GDBusMessage.
18278 * @error: The #GError to set.
18280 * If @message is not of type %G_DBUS_MESSAGE_TYPE_ERROR does
18281 * nothing and returns %FALSE.
18283 * Otherwise this method encodes the error in @message as a #GError
18284 * using g_dbus_error_set_dbus_error() using the information in the
18285 * %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field of @message as
18286 * well as the first string item in @message's body.
18288 * Returns: %TRUE if @error was set, %FALSE otherwise.
18294 * g_dbus_method_info_ref:
18295 * @info: A #GDBusMethodInfo
18297 * If @info is statically allocated does nothing. Otherwise increases
18298 * the reference count.
18300 * Returns: (not nullable): The same @info.
18306 * g_dbus_method_info_unref:
18307 * @info: A #GDBusMethodInfo.
18309 * If @info is statically allocated, does nothing. Otherwise decreases
18310 * the reference count of @info. When its reference count drops to 0,
18311 * the memory used is freed.
18318 * g_dbus_method_invocation_get_connection:
18319 * @invocation: A #GDBusMethodInvocation.
18321 * Gets the #GDBusConnection the method was invoked on.
18323 * Returns: (transfer none): A #GDBusConnection. Do not free, it is owned by @invocation.
18329 * g_dbus_method_invocation_get_interface_name:
18330 * @invocation: A #GDBusMethodInvocation.
18332 * Gets the name of the D-Bus interface the method was invoked on.
18334 * If this method call is a property Get, Set or GetAll call that has
18335 * been redirected to the method call handler then
18336 * "org.freedesktop.DBus.Properties" will be returned. See
18337 * #GDBusInterfaceVTable for more information.
18339 * Returns: A string. Do not free, it is owned by @invocation.
18345 * g_dbus_method_invocation_get_message:
18346 * @invocation: A #GDBusMethodInvocation.
18348 * Gets the #GDBusMessage for the method invocation. This is useful if
18349 * you need to use low-level protocol features, such as UNIX file
18350 * descriptor passing, that cannot be properly expressed in the
18353 * See this [server][gdbus-server] and [client][gdbus-unix-fd-client]
18354 * for an example of how to use this low-level API to send and receive
18355 * UNIX file descriptors.
18357 * Returns: (transfer none): #GDBusMessage. Do not free, it is owned by @invocation.
18363 * g_dbus_method_invocation_get_method_info:
18364 * @invocation: A #GDBusMethodInvocation.
18366 * Gets information about the method call, if any.
18368 * If this method invocation is a property Get, Set or GetAll call that
18369 * has been redirected to the method call handler then %NULL will be
18370 * returned. See g_dbus_method_invocation_get_property_info() and
18371 * #GDBusInterfaceVTable for more information.
18373 * Returns: (nullable): A #GDBusMethodInfo or %NULL. Do not free, it is owned by @invocation.
18379 * g_dbus_method_invocation_get_method_name:
18380 * @invocation: A #GDBusMethodInvocation.
18382 * Gets the name of the method that was invoked.
18384 * Returns: A string. Do not free, it is owned by @invocation.
18390 * g_dbus_method_invocation_get_object_path:
18391 * @invocation: A #GDBusMethodInvocation.
18393 * Gets the object path the method was invoked on.
18395 * Returns: A string. Do not free, it is owned by @invocation.
18401 * g_dbus_method_invocation_get_parameters:
18402 * @invocation: A #GDBusMethodInvocation.
18404 * Gets the parameters of the method invocation. If there are no input
18405 * parameters then this will return a GVariant with 0 children rather than NULL.
18407 * Returns: (transfer none): A #GVariant tuple. Do not unref this because it is owned by @invocation.
18413 * g_dbus_method_invocation_get_property_info:
18414 * @invocation: A #GDBusMethodInvocation
18416 * Gets information about the property that this method call is for, if
18419 * This will only be set in the case of an invocation in response to a
18420 * property Get or Set call that has been directed to the method call
18421 * handler for an object on account of its property_get() or
18422 * property_set() vtable pointers being unset.
18424 * See #GDBusInterfaceVTable for more information.
18426 * If the call was GetAll, %NULL will be returned.
18428 * Returns: (nullable) (transfer none): a #GDBusPropertyInfo or %NULL
18434 * g_dbus_method_invocation_get_sender:
18435 * @invocation: A #GDBusMethodInvocation.
18437 * Gets the bus name that invoked the method.
18439 * Returns: A string. Do not free, it is owned by @invocation.
18445 * g_dbus_method_invocation_get_user_data: (skip)
18446 * @invocation: A #GDBusMethodInvocation.
18448 * Gets the @user_data #gpointer passed to g_dbus_connection_register_object().
18450 * Returns: A #gpointer.
18456 * g_dbus_method_invocation_return_dbus_error:
18457 * @invocation: (transfer full): A #GDBusMethodInvocation.
18458 * @error_name: A valid D-Bus error name.
18459 * @error_message: A valid D-Bus error message.
18461 * Finishes handling a D-Bus method call by returning an error.
18463 * This method will take ownership of @invocation. See
18464 * #GDBusInterfaceVTable for more information about the ownership of
18472 * g_dbus_method_invocation_return_error:
18473 * @invocation: (transfer full): A #GDBusMethodInvocation.
18474 * @domain: A #GQuark for the #GError error domain.
18475 * @code: The error code.
18476 * @format: printf()-style format.
18477 * @...: Parameters for @format.
18479 * Finishes handling a D-Bus method call by returning an error.
18481 * See g_dbus_error_encode_gerror() for details about what error name
18482 * will be returned on the wire. In a nutshell, if the given error is
18483 * registered using g_dbus_error_register_error() the name given
18484 * during registration is used. Otherwise, a name of the form
18485 * `org.gtk.GDBus.UnmappedGError.Quark...` is used. This provides
18486 * transparent mapping of #GError between applications using GDBus.
18488 * If you are writing an application intended to be portable,
18489 * always register errors with g_dbus_error_register_error()
18490 * or use g_dbus_method_invocation_return_dbus_error().
18492 * This method will take ownership of @invocation. See
18493 * #GDBusInterfaceVTable for more information about the ownership of
18496 * Since 2.48, if the method call requested for a reply not to be sent
18497 * then this call will free @invocation but otherwise do nothing (as per
18498 * the recommendations of the D-Bus specification).
18505 * g_dbus_method_invocation_return_error_literal:
18506 * @invocation: (transfer full): A #GDBusMethodInvocation.
18507 * @domain: A #GQuark for the #GError error domain.
18508 * @code: The error code.
18509 * @message: The error message.
18511 * Like g_dbus_method_invocation_return_error() but without printf()-style formatting.
18513 * This method will take ownership of @invocation. See
18514 * #GDBusInterfaceVTable for more information about the ownership of
18522 * g_dbus_method_invocation_return_error_valist:
18523 * @invocation: (transfer full): A #GDBusMethodInvocation.
18524 * @domain: A #GQuark for the #GError error domain.
18525 * @code: The error code.
18526 * @format: printf()-style format.
18527 * @var_args: #va_list of parameters for @format.
18529 * Like g_dbus_method_invocation_return_error() but intended for
18530 * language bindings.
18532 * This method will take ownership of @invocation. See
18533 * #GDBusInterfaceVTable for more information about the ownership of
18541 * g_dbus_method_invocation_return_gerror:
18542 * @invocation: (transfer full): A #GDBusMethodInvocation.
18543 * @error: A #GError.
18545 * Like g_dbus_method_invocation_return_error() but takes a #GError
18546 * instead of the error domain, error code and message.
18548 * This method will take ownership of @invocation. See
18549 * #GDBusInterfaceVTable for more information about the ownership of
18557 * g_dbus_method_invocation_return_value:
18558 * @invocation: (transfer full): A #GDBusMethodInvocation.
18559 * @parameters: (nullable): A #GVariant tuple with out parameters for the method or %NULL if not passing any parameters.
18561 * Finishes handling a D-Bus method call by returning @parameters.
18562 * If the @parameters GVariant is floating, it is consumed.
18564 * It is an error if @parameters is not of the right format: it must be a tuple
18565 * containing the out-parameters of the D-Bus method. Even if the method has a
18566 * single out-parameter, it must be contained in a tuple. If the method has no
18567 * out-parameters, @parameters may be %NULL or an empty tuple.
18569 * |[<!-- language="C" -->
18570 * GDBusMethodInvocation *invocation = some_invocation;
18571 * g_autofree gchar *result_string = NULL;
18572 * g_autoptr (GError) error = NULL;
18574 * result_string = calculate_result (&error);
18576 * if (error != NULL)
18577 * g_dbus_method_invocation_return_gerror (invocation, error);
18579 * g_dbus_method_invocation_return_value (invocation,
18580 * g_variant_new ("(s)", result_string));
18582 * // Do not free @invocation here; returning a value does that
18585 * This method will take ownership of @invocation. See
18586 * #GDBusInterfaceVTable for more information about the ownership of
18589 * Since 2.48, if the method call requested for a reply not to be sent
18590 * then this call will sink @parameters and free @invocation, but
18591 * otherwise do nothing (as per the recommendations of the D-Bus
18599 * g_dbus_method_invocation_return_value_with_unix_fd_list:
18600 * @invocation: (transfer full): A #GDBusMethodInvocation.
18601 * @parameters: (nullable): A #GVariant tuple with out parameters for the method or %NULL if not passing any parameters.
18602 * @fd_list: (nullable): A #GUnixFDList or %NULL.
18604 * Like g_dbus_method_invocation_return_value() but also takes a #GUnixFDList.
18606 * This method is only available on UNIX.
18608 * This method will take ownership of @invocation. See
18609 * #GDBusInterfaceVTable for more information about the ownership of
18617 * g_dbus_method_invocation_take_error: (skip)
18618 * @invocation: (transfer full): A #GDBusMethodInvocation.
18619 * @error: (transfer full): A #GError.
18621 * Like g_dbus_method_invocation_return_gerror() but takes ownership
18622 * of @error so the caller does not need to free it.
18624 * This method will take ownership of @invocation. See
18625 * #GDBusInterfaceVTable for more information about the ownership of
18633 * g_dbus_node_info_generate_xml:
18634 * @info: A #GDBusNodeInfo.
18635 * @indent: Indentation level.
18636 * @string_builder: A #GString to to append XML data to.
18638 * Appends an XML representation of @info (and its children) to @string_builder.
18640 * This function is typically used for generating introspection XML documents at run-time for
18641 * handling the `org.freedesktop.DBus.Introspectable.Introspect` method.
18648 * g_dbus_node_info_lookup_interface:
18649 * @info: A #GDBusNodeInfo.
18650 * @name: A D-Bus interface name.
18652 * Looks up information about an interface.
18654 * The cost of this function is O(n) in number of interfaces.
18656 * Returns: (nullable) (transfer none): A #GDBusInterfaceInfo or %NULL if not found. Do not free, it is owned by @info.
18662 * g_dbus_node_info_new_for_xml:
18663 * @xml_data: Valid D-Bus introspection XML.
18664 * @error: Return location for error.
18666 * Parses @xml_data and returns a #GDBusNodeInfo representing the data.
18668 * The introspection XML must contain exactly one top-level
18671 * Note that this routine is using a
18672 * [GMarkup][glib-Simple-XML-Subset-Parser.description]-based
18673 * parser that only accepts a subset of valid XML documents.
18675 * Returns: A #GDBusNodeInfo structure or %NULL if @error is set. Free
18676 * with g_dbus_node_info_unref().
18682 * g_dbus_node_info_ref:
18683 * @info: A #GDBusNodeInfo
18685 * If @info is statically allocated does nothing. Otherwise increases
18686 * the reference count.
18688 * Returns: (not nullable): The same @info.
18694 * g_dbus_node_info_unref:
18695 * @info: A #GDBusNodeInfo.
18697 * If @info is statically allocated, does nothing. Otherwise decreases
18698 * the reference count of @info. When its reference count drops to 0,
18699 * the memory used is freed.
18706 * g_dbus_object_get_interface:
18707 * @object: A #GDBusObject.
18708 * @interface_name: A D-Bus interface name.
18710 * Gets the D-Bus interface with name @interface_name associated with
18713 * Returns: (nullable) (transfer full): %NULL if not found, otherwise a
18714 * #GDBusInterface that must be freed with g_object_unref().
18720 * g_dbus_object_get_interfaces:
18721 * @object: A #GDBusObject.
18723 * Gets the D-Bus interfaces associated with @object.
18725 * Returns: (element-type GDBusInterface) (transfer full): A list of #GDBusInterface instances.
18726 * The returned list must be freed by g_list_free() after each element has been freed
18727 * with g_object_unref().
18733 * g_dbus_object_get_object_path:
18734 * @object: A #GDBusObject.
18736 * Gets the object path for @object.
18738 * Returns: A string owned by @object. Do not free.
18744 * g_dbus_object_manager_client_get_connection:
18745 * @manager: A #GDBusObjectManagerClient
18747 * Gets the #GDBusConnection used by @manager.
18749 * Returns: (transfer none): A #GDBusConnection object. Do not free,
18750 * the object belongs to @manager.
18756 * g_dbus_object_manager_client_get_flags:
18757 * @manager: A #GDBusObjectManagerClient
18759 * Gets the flags that @manager was constructed with.
18761 * Returns: Zero of more flags from the #GDBusObjectManagerClientFlags
18768 * g_dbus_object_manager_client_get_name:
18769 * @manager: A #GDBusObjectManagerClient
18771 * Gets the name that @manager is for, or %NULL if not a message bus
18774 * Returns: A unique or well-known name. Do not free, the string
18775 * belongs to @manager.
18781 * g_dbus_object_manager_client_get_name_owner:
18782 * @manager: A #GDBusObjectManagerClient.
18784 * The unique name that owns the name that @manager is for or %NULL if
18785 * no-one currently owns that name. You can connect to the
18786 * #GObject::notify signal to track changes to the
18787 * #GDBusObjectManagerClient:name-owner property.
18789 * Returns: (nullable): The name owner or %NULL if no name owner
18790 * exists. Free with g_free().
18796 * g_dbus_object_manager_client_new:
18797 * @connection: A #GDBusConnection.
18798 * @flags: Zero or more flags from the #GDBusObjectManagerClientFlags enumeration.
18799 * @name: The owner of the control object (unique or well-known name).
18800 * @object_path: The object path of the control object.
18801 * @get_proxy_type_func: (nullable): A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies.
18802 * @get_proxy_type_user_data: User data to pass to @get_proxy_type_func.
18803 * @get_proxy_type_destroy_notify: (nullable): Free function for @get_proxy_type_user_data or %NULL.
18804 * @cancellable: (nullable): A #GCancellable or %NULL
18805 * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
18806 * @user_data: The data to pass to @callback.
18808 * Asynchronously creates a new #GDBusObjectManagerClient object.
18810 * This is an asynchronous failable constructor. When the result is
18811 * ready, @callback will be invoked in the
18812 * [thread-default main context][g-main-context-push-thread-default]
18813 * of the thread you are calling this method from. You can
18814 * then call g_dbus_object_manager_client_new_finish() to get the result. See
18815 * g_dbus_object_manager_client_new_sync() for the synchronous version.
18822 * g_dbus_object_manager_client_new_finish:
18823 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_object_manager_client_new().
18824 * @error: Return location for error or %NULL.
18826 * Finishes an operation started with g_dbus_object_manager_client_new().
18828 * Returns: (transfer full) (type GDBusObjectManagerClient): A
18829 * #GDBusObjectManagerClient object or %NULL if @error is set. Free
18830 * with g_object_unref().
18836 * g_dbus_object_manager_client_new_for_bus:
18837 * @bus_type: A #GBusType.
18838 * @flags: Zero or more flags from the #GDBusObjectManagerClientFlags enumeration.
18839 * @name: The owner of the control object (unique or well-known name).
18840 * @object_path: The object path of the control object.
18841 * @get_proxy_type_func: (nullable): A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies.
18842 * @get_proxy_type_user_data: User data to pass to @get_proxy_type_func.
18843 * @get_proxy_type_destroy_notify: (nullable): Free function for @get_proxy_type_user_data or %NULL.
18844 * @cancellable: (nullable): A #GCancellable or %NULL
18845 * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
18846 * @user_data: The data to pass to @callback.
18848 * Like g_dbus_object_manager_client_new() but takes a #GBusType instead of a
18849 * #GDBusConnection.
18851 * This is an asynchronous failable constructor. When the result is
18852 * ready, @callback will be invoked in the
18853 * [thread-default main loop][g-main-context-push-thread-default]
18854 * of the thread you are calling this method from. You can
18855 * then call g_dbus_object_manager_client_new_for_bus_finish() to get the result. See
18856 * g_dbus_object_manager_client_new_for_bus_sync() for the synchronous version.
18863 * g_dbus_object_manager_client_new_for_bus_finish:
18864 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_object_manager_client_new_for_bus().
18865 * @error: Return location for error or %NULL.
18867 * Finishes an operation started with g_dbus_object_manager_client_new_for_bus().
18869 * Returns: (transfer full) (type GDBusObjectManagerClient): A
18870 * #GDBusObjectManagerClient object or %NULL if @error is set. Free
18871 * with g_object_unref().
18877 * g_dbus_object_manager_client_new_for_bus_sync:
18878 * @bus_type: A #GBusType.
18879 * @flags: Zero or more flags from the #GDBusObjectManagerClientFlags enumeration.
18880 * @name: The owner of the control object (unique or well-known name).
18881 * @object_path: The object path of the control object.
18882 * @get_proxy_type_func: (nullable): A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies.
18883 * @get_proxy_type_user_data: User data to pass to @get_proxy_type_func.
18884 * @get_proxy_type_destroy_notify: (nullable): Free function for @get_proxy_type_user_data or %NULL.
18885 * @cancellable: (nullable): A #GCancellable or %NULL
18886 * @error: Return location for error or %NULL.
18888 * Like g_dbus_object_manager_client_new_sync() but takes a #GBusType instead
18889 * of a #GDBusConnection.
18891 * This is a synchronous failable constructor - the calling thread is
18892 * blocked until a reply is received. See g_dbus_object_manager_client_new_for_bus()
18893 * for the asynchronous version.
18895 * Returns: (transfer full) (type GDBusObjectManagerClient): A
18896 * #GDBusObjectManagerClient object or %NULL if @error is set. Free
18897 * with g_object_unref().
18903 * g_dbus_object_manager_client_new_sync:
18904 * @connection: A #GDBusConnection.
18905 * @flags: Zero or more flags from the #GDBusObjectManagerClientFlags enumeration.
18906 * @name: (nullable): The owner of the control object (unique or well-known name), or %NULL when not using a message bus connection.
18907 * @object_path: The object path of the control object.
18908 * @get_proxy_type_func: (nullable): A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies.
18909 * @get_proxy_type_user_data: User data to pass to @get_proxy_type_func.
18910 * @get_proxy_type_destroy_notify: (nullable): Free function for @get_proxy_type_user_data or %NULL.
18911 * @cancellable: (nullable): A #GCancellable or %NULL
18912 * @error: Return location for error or %NULL.
18914 * Creates a new #GDBusObjectManagerClient object.
18916 * This is a synchronous failable constructor - the calling thread is
18917 * blocked until a reply is received. See g_dbus_object_manager_client_new()
18918 * for the asynchronous version.
18920 * Returns: (transfer full) (type GDBusObjectManagerClient): A
18921 * #GDBusObjectManagerClient object or %NULL if @error is set. Free
18922 * with g_object_unref().
18928 * g_dbus_object_manager_get_interface:
18929 * @manager: A #GDBusObjectManager.
18930 * @object_path: Object path to look up.
18931 * @interface_name: D-Bus interface name to look up.
18933 * Gets the interface proxy for @interface_name at @object_path, if
18936 * Returns: (transfer full) (nullable): A #GDBusInterface instance or %NULL. Free
18937 * with g_object_unref().
18943 * g_dbus_object_manager_get_object:
18944 * @manager: A #GDBusObjectManager.
18945 * @object_path: Object path to look up.
18947 * Gets the #GDBusObjectProxy at @object_path, if any.
18949 * Returns: (transfer full) (nullable): A #GDBusObject or %NULL. Free with
18950 * g_object_unref().
18956 * g_dbus_object_manager_get_object_path:
18957 * @manager: A #GDBusObjectManager.
18959 * Gets the object path that @manager is for.
18961 * Returns: A string owned by @manager. Do not free.
18967 * g_dbus_object_manager_get_objects:
18968 * @manager: A #GDBusObjectManager.
18970 * Gets all #GDBusObject objects known to @manager.
18972 * Returns: (transfer full) (element-type GDBusObject): A list of
18973 * #GDBusObject objects. The returned list should be freed with
18974 * g_list_free() after each element has been freed with
18975 * g_object_unref().
18981 * g_dbus_object_manager_server_export:
18982 * @manager: A #GDBusObjectManagerServer.
18983 * @object: A #GDBusObjectSkeleton.
18985 * Exports @object on @manager.
18987 * If there is already a #GDBusObject exported at the object path,
18988 * then the old object is removed.
18990 * The object path for @object must be in the hierarchy rooted by the
18991 * object path for @manager.
18993 * Note that @manager will take a reference on @object for as long as
19001 * g_dbus_object_manager_server_export_uniquely:
19002 * @manager: A #GDBusObjectManagerServer.
19003 * @object: An object.
19005 * Like g_dbus_object_manager_server_export() but appends a string of
19006 * the form _N (with N being a natural number) to @object's object path
19007 * if an object with the given path already exists. As such, the
19008 * #GDBusObjectProxy:g-object-path property of @object may be modified.
19015 * g_dbus_object_manager_server_get_connection:
19016 * @manager: A #GDBusObjectManagerServer
19018 * Gets the #GDBusConnection used by @manager.
19020 * Returns: (transfer full) (nullable): A #GDBusConnection object or %NULL if
19021 * @manager isn't exported on a connection. The returned object should
19022 * be freed with g_object_unref().
19028 * g_dbus_object_manager_server_is_exported:
19029 * @manager: A #GDBusObjectManagerServer.
19030 * @object: An object.
19032 * Returns whether @object is currently exported on @manager.
19034 * Returns: %TRUE if @object is exported
19040 * g_dbus_object_manager_server_new:
19041 * @object_path: The object path to export the manager object at.
19043 * Creates a new #GDBusObjectManagerServer object.
19045 * The returned server isn't yet exported on any connection. To do so,
19046 * use g_dbus_object_manager_server_set_connection(). Normally you
19047 * want to export all of your objects before doing so to avoid
19048 * [InterfacesAdded](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager)
19049 * signals being emitted.
19051 * Returns: A #GDBusObjectManagerServer object. Free with g_object_unref().
19057 * g_dbus_object_manager_server_set_connection:
19058 * @manager: A #GDBusObjectManagerServer.
19059 * @connection: (nullable): A #GDBusConnection or %NULL.
19061 * Exports all objects managed by @manager on @connection. If
19062 * @connection is %NULL, stops exporting objects.
19067 * g_dbus_object_manager_server_unexport:
19068 * @manager: A #GDBusObjectManagerServer.
19069 * @object_path: An object path.
19071 * If @manager has an object at @path, removes the object. Otherwise
19074 * Note that @object_path must be in the hierarchy rooted by the
19075 * object path for @manager.
19077 * Returns: %TRUE if object at @object_path was removed, %FALSE otherwise.
19083 * g_dbus_object_proxy_get_connection:
19084 * @proxy: a #GDBusObjectProxy
19086 * Gets the connection that @proxy is for.
19088 * Returns: (transfer none): A #GDBusConnection. Do not free, the
19089 * object is owned by @proxy.
19095 * g_dbus_object_proxy_new:
19096 * @connection: a #GDBusConnection
19097 * @object_path: the object path
19099 * Creates a new #GDBusObjectProxy for the given connection and
19102 * Returns: a new #GDBusObjectProxy
19108 * g_dbus_object_skeleton_add_interface:
19109 * @object: A #GDBusObjectSkeleton.
19110 * @interface_: A #GDBusInterfaceSkeleton.
19112 * Adds @interface_ to @object.
19114 * If @object already contains a #GDBusInterfaceSkeleton with the same
19115 * interface name, it is removed before @interface_ is added.
19117 * Note that @object takes its own reference on @interface_ and holds
19118 * it until removed.
19125 * g_dbus_object_skeleton_flush:
19126 * @object: A #GDBusObjectSkeleton.
19128 * This method simply calls g_dbus_interface_skeleton_flush() on all
19129 * interfaces belonging to @object. See that method for when flushing
19137 * g_dbus_object_skeleton_new:
19138 * @object_path: An object path.
19140 * Creates a new #GDBusObjectSkeleton.
19142 * Returns: A #GDBusObjectSkeleton. Free with g_object_unref().
19148 * g_dbus_object_skeleton_remove_interface:
19149 * @object: A #GDBusObjectSkeleton.
19150 * @interface_: A #GDBusInterfaceSkeleton.
19152 * Removes @interface_ from @object.
19159 * g_dbus_object_skeleton_remove_interface_by_name:
19160 * @object: A #GDBusObjectSkeleton.
19161 * @interface_name: A D-Bus interface name.
19163 * Removes the #GDBusInterface with @interface_name from @object.
19165 * If no D-Bus interface of the given interface exists, this function
19173 * g_dbus_object_skeleton_set_object_path:
19174 * @object: A #GDBusObjectSkeleton.
19175 * @object_path: A valid D-Bus object path.
19177 * Sets the object path for @object.
19184 * g_dbus_property_info_ref:
19185 * @info: A #GDBusPropertyInfo
19187 * If @info is statically allocated does nothing. Otherwise increases
19188 * the reference count.
19190 * Returns: (not nullable): The same @info.
19196 * g_dbus_property_info_unref:
19197 * @info: A #GDBusPropertyInfo.
19199 * If @info is statically allocated, does nothing. Otherwise decreases
19200 * the reference count of @info. When its reference count drops to 0,
19201 * the memory used is freed.
19208 * g_dbus_proxy_call:
19209 * @proxy: A #GDBusProxy.
19210 * @method_name: Name of method to invoke.
19211 * @parameters: (nullable): A #GVariant tuple with parameters for the signal or %NULL if not passing parameters.
19212 * @flags: Flags from the #GDBusCallFlags enumeration.
19213 * @timeout_msec: The timeout in milliseconds (with %G_MAXINT meaning
19214 * "infinite") or -1 to use the proxy default timeout.
19215 * @cancellable: (nullable): A #GCancellable or %NULL.
19216 * @callback: (nullable): A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't
19217 * care about the result of the method invocation.
19218 * @user_data: The data to pass to @callback.
19220 * Asynchronously invokes the @method_name method on @proxy.
19222 * If @method_name contains any dots, then @name is split into interface and
19223 * method name parts. This allows using @proxy for invoking methods on
19224 * other interfaces.
19226 * If the #GDBusConnection associated with @proxy is closed then
19227 * the operation will fail with %G_IO_ERROR_CLOSED. If
19228 * @cancellable is canceled, the operation will fail with
19229 * %G_IO_ERROR_CANCELLED. If @parameters contains a value not
19230 * compatible with the D-Bus protocol, the operation fails with
19231 * %G_IO_ERROR_INVALID_ARGUMENT.
19233 * If the @parameters #GVariant is floating, it is consumed. This allows
19234 * convenient 'inline' use of g_variant_new(), e.g.:
19235 * |[<!-- language="C" -->
19236 * g_dbus_proxy_call (proxy,
19238 * g_variant_new ("(ss)",
19241 * G_DBUS_CALL_FLAGS_NONE,
19244 * (GAsyncReadyCallback) two_strings_done,
19248 * If @proxy has an expected interface (see
19249 * #GDBusProxy:g-interface-info) and @method_name is referenced by it,
19250 * then the return value is checked against the return type.
19252 * This is an asynchronous method. When the operation is finished,
19253 * @callback will be invoked in the
19254 * [thread-default main context][g-main-context-push-thread-default]
19255 * of the thread you are calling this method from.
19256 * You can then call g_dbus_proxy_call_finish() to get the result of
19257 * the operation. See g_dbus_proxy_call_sync() for the synchronous
19258 * version of this method.
19260 * If @callback is %NULL then the D-Bus method call message will be sent with
19261 * the %G_DBUS_MESSAGE_FLAGS_NO_REPLY_EXPECTED flag set.
19268 * g_dbus_proxy_call_finish:
19269 * @proxy: A #GDBusProxy.
19270 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_proxy_call().
19271 * @error: Return location for error or %NULL.
19273 * Finishes an operation started with g_dbus_proxy_call().
19275 * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
19276 * return values. Free with g_variant_unref().
19282 * g_dbus_proxy_call_sync:
19283 * @proxy: A #GDBusProxy.
19284 * @method_name: Name of method to invoke.
19285 * @parameters: (nullable): A #GVariant tuple with parameters for the signal
19286 * or %NULL if not passing parameters.
19287 * @flags: Flags from the #GDBusCallFlags enumeration.
19288 * @timeout_msec: The timeout in milliseconds (with %G_MAXINT meaning
19289 * "infinite") or -1 to use the proxy default timeout.
19290 * @cancellable: (nullable): A #GCancellable or %NULL.
19291 * @error: Return location for error or %NULL.
19293 * Synchronously invokes the @method_name method on @proxy.
19295 * If @method_name contains any dots, then @name is split into interface and
19296 * method name parts. This allows using @proxy for invoking methods on
19297 * other interfaces.
19299 * If the #GDBusConnection associated with @proxy is disconnected then
19300 * the operation will fail with %G_IO_ERROR_CLOSED. If
19301 * @cancellable is canceled, the operation will fail with
19302 * %G_IO_ERROR_CANCELLED. If @parameters contains a value not
19303 * compatible with the D-Bus protocol, the operation fails with
19304 * %G_IO_ERROR_INVALID_ARGUMENT.
19306 * If the @parameters #GVariant is floating, it is consumed. This allows
19307 * convenient 'inline' use of g_variant_new(), e.g.:
19308 * |[<!-- language="C" -->
19309 * g_dbus_proxy_call_sync (proxy,
19311 * g_variant_new ("(ss)",
19314 * G_DBUS_CALL_FLAGS_NONE,
19320 * The calling thread is blocked until a reply is received. See
19321 * g_dbus_proxy_call() for the asynchronous version of this
19324 * If @proxy has an expected interface (see
19325 * #GDBusProxy:g-interface-info) and @method_name is referenced by it,
19326 * then the return value is checked against the return type.
19328 * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
19329 * return values. Free with g_variant_unref().
19335 * g_dbus_proxy_call_with_unix_fd_list:
19336 * @proxy: A #GDBusProxy.
19337 * @method_name: Name of method to invoke.
19338 * @parameters: (nullable): A #GVariant tuple with parameters for the signal or %NULL if not passing parameters.
19339 * @flags: Flags from the #GDBusCallFlags enumeration.
19340 * @timeout_msec: The timeout in milliseconds (with %G_MAXINT meaning
19341 * "infinite") or -1 to use the proxy default timeout.
19342 * @fd_list: (nullable): A #GUnixFDList or %NULL.
19343 * @cancellable: (nullable): A #GCancellable or %NULL.
19344 * @callback: (nullable): A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't
19345 * care about the result of the method invocation.
19346 * @user_data: The data to pass to @callback.
19348 * Like g_dbus_proxy_call() but also takes a #GUnixFDList object.
19350 * This method is only available on UNIX.
19357 * g_dbus_proxy_call_with_unix_fd_list_finish:
19358 * @proxy: A #GDBusProxy.
19359 * @out_fd_list: (out) (optional): Return location for a #GUnixFDList or %NULL.
19360 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_proxy_call_with_unix_fd_list().
19361 * @error: Return location for error or %NULL.
19363 * Finishes an operation started with g_dbus_proxy_call_with_unix_fd_list().
19365 * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
19366 * return values. Free with g_variant_unref().
19372 * g_dbus_proxy_call_with_unix_fd_list_sync:
19373 * @proxy: A #GDBusProxy.
19374 * @method_name: Name of method to invoke.
19375 * @parameters: (nullable): A #GVariant tuple with parameters for the signal
19376 * or %NULL if not passing parameters.
19377 * @flags: Flags from the #GDBusCallFlags enumeration.
19378 * @timeout_msec: The timeout in milliseconds (with %G_MAXINT meaning
19379 * "infinite") or -1 to use the proxy default timeout.
19380 * @fd_list: (nullable): A #GUnixFDList or %NULL.
19381 * @out_fd_list: (out) (optional): Return location for a #GUnixFDList or %NULL.
19382 * @cancellable: (nullable): A #GCancellable or %NULL.
19383 * @error: Return location for error or %NULL.
19385 * Like g_dbus_proxy_call_sync() but also takes and returns #GUnixFDList objects.
19387 * This method is only available on UNIX.
19389 * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
19390 * return values. Free with g_variant_unref().
19396 * g_dbus_proxy_get_cached_property:
19397 * @proxy: A #GDBusProxy.
19398 * @property_name: Property name.
19400 * Looks up the value for a property from the cache. This call does no
19403 * If @proxy has an expected interface (see
19404 * #GDBusProxy:g-interface-info) and @property_name is referenced by
19405 * it, then @value is checked against the type of the property.
19407 * Returns: (transfer full) (nullable): A reference to the #GVariant instance
19408 * that holds the value for @property_name or %NULL if the value is not in
19409 * the cache. The returned reference must be freed with g_variant_unref().
19415 * g_dbus_proxy_get_cached_property_names:
19416 * @proxy: A #GDBusProxy.
19418 * Gets the names of all cached properties on @proxy.
19420 * Returns: (transfer full) (nullable) (array zero-terminated=1): A
19421 * %NULL-terminated array of strings or %NULL if
19422 * @proxy has no cached properties. Free the returned array with
19429 * g_dbus_proxy_get_connection:
19430 * @proxy: A #GDBusProxy.
19432 * Gets the connection @proxy is for.
19434 * Returns: (transfer none) (not nullable): A #GDBusConnection owned by @proxy. Do not free.
19440 * g_dbus_proxy_get_default_timeout:
19441 * @proxy: A #GDBusProxy.
19443 * Gets the timeout to use if -1 (specifying default timeout) is
19444 * passed as @timeout_msec in the g_dbus_proxy_call() and
19445 * g_dbus_proxy_call_sync() functions.
19447 * See the #GDBusProxy:g-default-timeout property for more details.
19449 * Returns: Timeout to use for @proxy.
19455 * g_dbus_proxy_get_flags:
19456 * @proxy: A #GDBusProxy.
19458 * Gets the flags that @proxy was constructed with.
19460 * Returns: Flags from the #GDBusProxyFlags enumeration.
19466 * g_dbus_proxy_get_interface_info:
19467 * @proxy: A #GDBusProxy
19469 * Returns the #GDBusInterfaceInfo, if any, specifying the interface
19470 * that @proxy conforms to. See the #GDBusProxy:g-interface-info
19471 * property for more details.
19473 * Returns: (transfer none) (nullable): A #GDBusInterfaceInfo or %NULL.
19474 * Do not unref the returned object, it is owned by @proxy.
19480 * g_dbus_proxy_get_interface_name:
19481 * @proxy: A #GDBusProxy.
19483 * Gets the D-Bus interface name @proxy is for.
19485 * Returns: (not nullable): A string owned by @proxy. Do not free.
19491 * g_dbus_proxy_get_name:
19492 * @proxy: A #GDBusProxy.
19494 * Gets the name that @proxy was constructed for.
19496 * When connected to a message bus, this will usually be non-%NULL.
19497 * However, it may be %NULL for a proxy that communicates using a peer-to-peer
19500 * Returns: (nullable): A string owned by @proxy. Do not free.
19506 * g_dbus_proxy_get_name_owner:
19507 * @proxy: A #GDBusProxy.
19509 * The unique name that owns the name that @proxy is for or %NULL if
19510 * no-one currently owns that name. You may connect to the
19511 * #GObject::notify signal to track changes to the
19512 * #GDBusProxy:g-name-owner property.
19514 * Returns: (transfer full) (nullable): The name owner or %NULL if no name
19515 * owner exists. Free with g_free().
19521 * g_dbus_proxy_get_object_path:
19522 * @proxy: A #GDBusProxy.
19524 * Gets the object path @proxy is for.
19526 * Returns: (not nullable): A string owned by @proxy. Do not free.
19532 * g_dbus_proxy_new:
19533 * @connection: A #GDBusConnection.
19534 * @flags: Flags used when constructing the proxy.
19535 * @info: (nullable): A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL.
19536 * @name: (nullable): A bus name (well-known or unique) or %NULL if @connection is not a message bus connection.
19537 * @object_path: An object path.
19538 * @interface_name: A D-Bus interface name.
19539 * @cancellable: (nullable): A #GCancellable or %NULL.
19540 * @callback: Callback function to invoke when the proxy is ready.
19541 * @user_data: User data to pass to @callback.
19543 * Creates a proxy for accessing @interface_name on the remote object
19544 * at @object_path owned by @name at @connection and asynchronously
19545 * loads D-Bus properties unless the
19546 * %G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES flag is used. Connect to
19547 * the #GDBusProxy::g-properties-changed signal to get notified about
19548 * property changes.
19550 * If the %G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS flag is not set, also sets up
19551 * match rules for signals. Connect to the #GDBusProxy::g-signal signal
19552 * to handle signals from the remote object.
19554 * If both %G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES and
19555 * %G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS are set, this constructor is
19556 * guaranteed to complete immediately without blocking.
19558 * If @name is a well-known name and the
19559 * %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START and %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START_AT_CONSTRUCTION
19560 * flags aren't set and no name owner currently exists, the message bus
19561 * will be requested to launch a name owner for the name.
19563 * This is a failable asynchronous constructor - when the proxy is
19564 * ready, @callback will be invoked and you can use
19565 * g_dbus_proxy_new_finish() to get the result.
19567 * See g_dbus_proxy_new_sync() and for a synchronous version of this constructor.
19569 * #GDBusProxy is used in this [example][gdbus-wellknown-proxy].
19576 * g_dbus_proxy_new_finish:
19577 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback function passed to g_dbus_proxy_new().
19578 * @error: Return location for error or %NULL.
19580 * Finishes creating a #GDBusProxy.
19582 * Returns: (transfer full): A #GDBusProxy or %NULL if @error is set.
19583 * Free with g_object_unref().
19589 * g_dbus_proxy_new_for_bus:
19590 * @bus_type: A #GBusType.
19591 * @flags: Flags used when constructing the proxy.
19592 * @info: (nullable): A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL.
19593 * @name: A bus name (well-known or unique).
19594 * @object_path: An object path.
19595 * @interface_name: A D-Bus interface name.
19596 * @cancellable: (nullable): A #GCancellable or %NULL.
19597 * @callback: Callback function to invoke when the proxy is ready.
19598 * @user_data: User data to pass to @callback.
19600 * Like g_dbus_proxy_new() but takes a #GBusType instead of a #GDBusConnection.
19602 * #GDBusProxy is used in this [example][gdbus-wellknown-proxy].
19609 * g_dbus_proxy_new_for_bus_finish:
19610 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback function passed to g_dbus_proxy_new_for_bus().
19611 * @error: Return location for error or %NULL.
19613 * Finishes creating a #GDBusProxy.
19615 * Returns: (transfer full): A #GDBusProxy or %NULL if @error is set.
19616 * Free with g_object_unref().
19622 * g_dbus_proxy_new_for_bus_sync:
19623 * @bus_type: A #GBusType.
19624 * @flags: Flags used when constructing the proxy.
19625 * @info: (nullable): A #GDBusInterfaceInfo specifying the minimal interface
19626 * that @proxy conforms to or %NULL.
19627 * @name: A bus name (well-known or unique).
19628 * @object_path: An object path.
19629 * @interface_name: A D-Bus interface name.
19630 * @cancellable: (nullable): A #GCancellable or %NULL.
19631 * @error: Return location for error or %NULL.
19633 * Like g_dbus_proxy_new_sync() but takes a #GBusType instead of a #GDBusConnection.
19635 * #GDBusProxy is used in this [example][gdbus-wellknown-proxy].
19637 * Returns: (transfer full): A #GDBusProxy or %NULL if error is set.
19638 * Free with g_object_unref().
19644 * g_dbus_proxy_new_sync:
19645 * @connection: A #GDBusConnection.
19646 * @flags: Flags used when constructing the proxy.
19647 * @info: (nullable): A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL.
19648 * @name: (nullable): A bus name (well-known or unique) or %NULL if @connection is not a message bus connection.
19649 * @object_path: An object path.
19650 * @interface_name: A D-Bus interface name.
19651 * @cancellable: (nullable): A #GCancellable or %NULL.
19652 * @error: (nullable): Return location for error or %NULL.
19654 * Creates a proxy for accessing @interface_name on the remote object
19655 * at @object_path owned by @name at @connection and synchronously
19656 * loads D-Bus properties unless the
19657 * %G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES flag is used.
19659 * If the %G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS flag is not set, also sets up
19660 * match rules for signals. Connect to the #GDBusProxy::g-signal signal
19661 * to handle signals from the remote object.
19663 * If both %G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES and
19664 * %G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS are set, this constructor is
19665 * guaranteed to return immediately without blocking.
19667 * If @name is a well-known name and the
19668 * %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START and %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START_AT_CONSTRUCTION
19669 * flags aren't set and no name owner currently exists, the message bus
19670 * will be requested to launch a name owner for the name.
19672 * This is a synchronous failable constructor. See g_dbus_proxy_new()
19673 * and g_dbus_proxy_new_finish() for the asynchronous version.
19675 * #GDBusProxy is used in this [example][gdbus-wellknown-proxy].
19677 * Returns: (transfer full): A #GDBusProxy or %NULL if error is set.
19678 * Free with g_object_unref().
19684 * g_dbus_proxy_set_cached_property:
19685 * @proxy: A #GDBusProxy
19686 * @property_name: Property name.
19687 * @value: (nullable): Value for the property or %NULL to remove it from the cache.
19689 * If @value is not %NULL, sets the cached value for the property with
19690 * name @property_name to the value in @value.
19692 * If @value is %NULL, then the cached value is removed from the
19695 * If @proxy has an expected interface (see
19696 * #GDBusProxy:g-interface-info) and @property_name is referenced by
19697 * it, then @value is checked against the type of the property.
19699 * If the @value #GVariant is floating, it is consumed. This allows
19700 * convenient 'inline' use of g_variant_new(), e.g.
19701 * |[<!-- language="C" -->
19702 * g_dbus_proxy_set_cached_property (proxy,
19704 * g_variant_new ("(si)",
19709 * Normally you will not need to use this method since @proxy
19710 * is tracking changes using the
19711 * `org.freedesktop.DBus.Properties.PropertiesChanged`
19712 * D-Bus signal. However, for performance reasons an object may
19713 * decide to not use this signal for some properties and instead
19714 * use a proprietary out-of-band mechanism to transmit changes.
19716 * As a concrete example, consider an object with a property
19717 * `ChatroomParticipants` which is an array of strings. Instead of
19718 * transmitting the same (long) array every time the property changes,
19719 * it is more efficient to only transmit the delta using e.g. signals
19720 * `ChatroomParticipantJoined(String name)` and
19721 * `ChatroomParticipantParted(String name)`.
19728 * g_dbus_proxy_set_default_timeout:
19729 * @proxy: A #GDBusProxy.
19730 * @timeout_msec: Timeout in milliseconds.
19732 * Sets the timeout to use if -1 (specifying default timeout) is
19733 * passed as @timeout_msec in the g_dbus_proxy_call() and
19734 * g_dbus_proxy_call_sync() functions.
19736 * See the #GDBusProxy:g-default-timeout property for more details.
19743 * g_dbus_proxy_set_interface_info:
19744 * @proxy: A #GDBusProxy
19745 * @info: (transfer none) (nullable): Minimum interface this proxy conforms to
19746 * or %NULL to unset.
19748 * Ensure that interactions with @proxy conform to the given
19749 * interface. See the #GDBusProxy:g-interface-info property for more
19757 * g_dbus_server_get_client_address:
19758 * @server: A #GDBusServer.
19761 * [D-Bus address](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses)
19762 * string that can be used by clients to connect to @server.
19764 * This is valid and non-empty if initializing the #GDBusServer succeeded.
19766 * Returns: (not nullable): A D-Bus address string. Do not free, the string is owned
19773 * g_dbus_server_get_flags:
19774 * @server: A #GDBusServer.
19776 * Gets the flags for @server.
19778 * Returns: A set of flags from the #GDBusServerFlags enumeration.
19784 * g_dbus_server_get_guid:
19785 * @server: A #GDBusServer.
19787 * Gets the GUID for @server, as provided to g_dbus_server_new_sync().
19789 * Returns: (not nullable): A D-Bus GUID. Do not free this string, it is owned by @server.
19795 * g_dbus_server_is_active:
19796 * @server: A #GDBusServer.
19798 * Gets whether @server is active.
19800 * Returns: %TRUE if server is active, %FALSE otherwise.
19806 * g_dbus_server_new_sync:
19807 * @address: A D-Bus address.
19808 * @flags: Flags from the #GDBusServerFlags enumeration.
19809 * @guid: A D-Bus GUID.
19810 * @observer: (nullable): A #GDBusAuthObserver or %NULL.
19811 * @cancellable: (nullable): A #GCancellable or %NULL.
19812 * @error: Return location for server or %NULL.
19814 * Creates a new D-Bus server that listens on the first address in
19815 * @address that works.
19817 * Once constructed, you can use g_dbus_server_get_client_address() to
19818 * get a D-Bus address string that clients can use to connect.
19820 * To have control over the available authentication mechanisms and
19821 * the users that are authorized to connect, it is strongly recommended
19822 * to provide a non-%NULL #GDBusAuthObserver.
19824 * Connect to the #GDBusServer::new-connection signal to handle
19825 * incoming connections.
19827 * The returned #GDBusServer isn't active - you have to start it with
19828 * g_dbus_server_start().
19830 * #GDBusServer is used in this [example][gdbus-peer-to-peer].
19832 * This is a synchronous failable constructor. There is currently no
19833 * asynchronous version.
19835 * Returns: A #GDBusServer or %NULL if @error is set. Free with
19836 * g_object_unref().
19842 * g_dbus_server_start:
19843 * @server: A #GDBusServer.
19852 * g_dbus_server_stop:
19853 * @server: A #GDBusServer.
19862 * g_dbus_signal_info_ref:
19863 * @info: A #GDBusSignalInfo
19865 * If @info is statically allocated does nothing. Otherwise increases
19866 * the reference count.
19868 * Returns: (not nullable): The same @info.
19874 * g_dbus_signal_info_unref:
19875 * @info: A #GDBusSignalInfo.
19877 * If @info is statically allocated, does nothing. Otherwise decreases
19878 * the reference count of @info. When its reference count drops to 0,
19879 * the memory used is freed.
19886 * g_dbus_unescape_object_path:
19887 * @s: the string to unescape
19889 * Unescapes an string that was previously escaped with
19890 * g_dbus_escape_object_path(). If the string is in a format that could
19891 * not have been returned by g_dbus_escape_object_path(), this function
19894 * Encoding alphanumeric characters which do not need to be
19895 * encoded is not allowed (e.g `_63` is not valid, the string
19896 * should contain `c` instead).
19898 * Returns: (array zero-terminated=1) (element-type guint8) (nullable): an
19899 * unescaped version of @s, or %NULL if @s is not a string returned
19900 * from g_dbus_escape_object_path(). Free with g_free().
19906 * g_desktop_app_info_get_action_name:
19907 * @info: a #GDesktopAppInfo
19908 * @action_name: the name of the action as from
19909 * g_desktop_app_info_list_actions()
19911 * Gets the user-visible display name of the "additional application
19912 * action" specified by @action_name.
19914 * This corresponds to the "Name" key within the keyfile group for the
19917 * Returns: (transfer full): the locale-specific action name
19923 * g_desktop_app_info_get_boolean:
19924 * @info: a #GDesktopAppInfo
19925 * @key: the key to look up
19927 * Looks up a boolean value in the keyfile backing @info.
19929 * The @key is looked up in the "Desktop Entry" group.
19931 * Returns: the boolean value, or %FALSE if the key
19938 * g_desktop_app_info_get_categories:
19939 * @info: a #GDesktopAppInfo
19941 * Gets the categories from the desktop file.
19943 * Returns: (nullable): The unparsed Categories key from the desktop file;
19944 * i.e. no attempt is made to split it by ';' or validate it.
19949 * g_desktop_app_info_get_filename:
19950 * @info: a #GDesktopAppInfo
19952 * When @info was created from a known filename, return it. In some
19953 * situations such as the #GDesktopAppInfo returned from
19954 * g_desktop_app_info_new_from_keyfile(), this function will return %NULL.
19956 * Returns: (nullable) (type filename): The full path to the file for @info,
19957 * or %NULL if not known.
19963 * g_desktop_app_info_get_generic_name:
19964 * @info: a #GDesktopAppInfo
19966 * Gets the generic name from the desktop file.
19968 * Returns: (nullable): The value of the GenericName key
19973 * g_desktop_app_info_get_implementations:
19974 * @interface: the name of the interface
19976 * Gets all applications that implement @interface.
19978 * An application implements an interface if that interface is listed in
19979 * the Implements= line of the desktop file of the application.
19981 * Returns: (element-type GDesktopAppInfo) (transfer full): a list of #GDesktopAppInfo
19988 * g_desktop_app_info_get_is_hidden:
19989 * @info: a #GDesktopAppInfo.
19991 * A desktop file is hidden if the Hidden key in it is
19994 * Returns: %TRUE if hidden, %FALSE otherwise.
19999 * g_desktop_app_info_get_keywords:
20000 * @info: a #GDesktopAppInfo
20002 * Gets the keywords from the desktop file.
20004 * Returns: (transfer none): The value of the Keywords key
20010 * g_desktop_app_info_get_locale_string:
20011 * @info: a #GDesktopAppInfo
20012 * @key: the key to look up
20014 * Looks up a localized string value in the keyfile backing @info
20015 * translated to the current locale.
20017 * The @key is looked up in the "Desktop Entry" group.
20019 * Returns: (nullable): a newly allocated string, or %NULL if the key
20026 * g_desktop_app_info_get_nodisplay:
20027 * @info: a #GDesktopAppInfo
20029 * Gets the value of the NoDisplay key, which helps determine if the
20030 * application info should be shown in menus. See
20031 * #G_KEY_FILE_DESKTOP_KEY_NO_DISPLAY and g_app_info_should_show().
20033 * Returns: The value of the NoDisplay key
20039 * g_desktop_app_info_get_show_in:
20040 * @info: a #GDesktopAppInfo
20041 * @desktop_env: (nullable): a string specifying a desktop name
20043 * Checks if the application info should be shown in menus that list available
20044 * applications for a specific name of the desktop, based on the
20045 * `OnlyShowIn` and `NotShowIn` keys.
20047 * @desktop_env should typically be given as %NULL, in which case the
20048 * `XDG_CURRENT_DESKTOP` environment variable is consulted. If you want
20049 * to override the default mechanism then you may specify @desktop_env,
20050 * but this is not recommended.
20052 * Note that g_app_info_should_show() for @info will include this check (with
20053 * %NULL for @desktop_env) as well as additional checks.
20055 * Returns: %TRUE if the @info should be shown in @desktop_env according to the
20056 * `OnlyShowIn` and `NotShowIn` keys, %FALSE
20063 * g_desktop_app_info_get_startup_wm_class:
20064 * @info: a #GDesktopAppInfo that supports startup notify
20066 * Retrieves the StartupWMClass field from @info. This represents the
20067 * WM_CLASS property of the main window of the application, if launched
20070 * Returns: (nullable) (transfer none): the startup WM class, or %NULL if none is set
20071 * in the desktop file.
20077 * g_desktop_app_info_get_string:
20078 * @info: a #GDesktopAppInfo
20079 * @key: the key to look up
20081 * Looks up a string value in the keyfile backing @info.
20083 * The @key is looked up in the "Desktop Entry" group.
20085 * Returns: (nullable): a newly allocated string, or %NULL if the key
20092 * g_desktop_app_info_get_string_list:
20093 * @info: a #GDesktopAppInfo
20094 * @key: the key to look up
20095 * @length: (out) (optional): return location for the number of returned strings, or %NULL
20097 * Looks up a string list value in the keyfile backing @info.
20099 * The @key is looked up in the "Desktop Entry" group.
20101 * Returns: (array zero-terminated=1 length=length) (element-type utf8) (transfer full):
20102 * a %NULL-terminated string array or %NULL if the specified
20103 * key cannot be found. The array should be freed with g_strfreev().
20109 * g_desktop_app_info_has_key:
20110 * @info: a #GDesktopAppInfo
20111 * @key: the key to look up
20113 * Returns whether @key exists in the "Desktop Entry" group
20114 * of the keyfile backing @info.
20116 * Returns: %TRUE if the @key exists
20122 * g_desktop_app_info_launch_action:
20123 * @info: a #GDesktopAppInfo
20124 * @action_name: the name of the action as from
20125 * g_desktop_app_info_list_actions()
20126 * @launch_context: (nullable): a #GAppLaunchContext
20128 * Activates the named application action.
20130 * You may only call this function on action names that were
20131 * returned from g_desktop_app_info_list_actions().
20133 * Note that if the main entry of the desktop file indicates that the
20134 * application supports startup notification, and @launch_context is
20135 * non-%NULL, then startup notification will be used when activating the
20136 * action (and as such, invocation of the action on the receiving side
20137 * must signal the end of startup notification when it is completed).
20138 * This is the expected behaviour of applications declaring additional
20139 * actions, as per the desktop file specification.
20141 * As with g_app_info_launch() there is no way to detect failures that
20142 * occur while using this function.
20149 * g_desktop_app_info_launch_uris_as_manager:
20150 * @appinfo: a #GDesktopAppInfo
20151 * @uris: (element-type utf8): List of URIs
20152 * @launch_context: (nullable): a #GAppLaunchContext
20153 * @spawn_flags: #GSpawnFlags, used for each process
20154 * @user_setup: (scope async) (nullable): a #GSpawnChildSetupFunc, used once
20155 * for each process.
20156 * @user_setup_data: (closure user_setup) (nullable): User data for @user_setup
20157 * @pid_callback: (scope call) (nullable): Callback for child processes
20158 * @pid_callback_data: (closure pid_callback) (nullable): User data for @callback
20159 * @error: return location for a #GError, or %NULL
20161 * This function performs the equivalent of g_app_info_launch_uris(),
20162 * but is intended primarily for operating system components that
20163 * launch applications. Ordinary applications should use
20164 * g_app_info_launch_uris().
20166 * If the application is launched via GSpawn, then @spawn_flags, @user_setup
20167 * and @user_setup_data are used for the call to g_spawn_async().
20168 * Additionally, @pid_callback (with @pid_callback_data) will be called to
20169 * inform about the PID of the created process. See g_spawn_async_with_pipes()
20170 * for information on certain parameter conditions that can enable an
20171 * optimized posix_spawn() codepath to be used.
20173 * If application launching occurs via some other mechanism (eg: D-Bus
20174 * activation) then @spawn_flags, @user_setup, @user_setup_data,
20175 * @pid_callback and @pid_callback_data are ignored.
20177 * Returns: %TRUE on successful launch, %FALSE otherwise.
20182 * g_desktop_app_info_launch_uris_as_manager_with_fds:
20183 * @appinfo: a #GDesktopAppInfo
20184 * @uris: (element-type utf8): List of URIs
20185 * @launch_context: (nullable): a #GAppLaunchContext
20186 * @spawn_flags: #GSpawnFlags, used for each process
20187 * @user_setup: (scope async) (nullable): a #GSpawnChildSetupFunc, used once
20188 * for each process.
20189 * @user_setup_data: (closure user_setup) (nullable): User data for @user_setup
20190 * @pid_callback: (scope call) (nullable): Callback for child processes
20191 * @pid_callback_data: (closure pid_callback) (nullable): User data for @callback
20192 * @stdin_fd: file descriptor to use for child's stdin, or -1
20193 * @stdout_fd: file descriptor to use for child's stdout, or -1
20194 * @stderr_fd: file descriptor to use for child's stderr, or -1
20195 * @error: return location for a #GError, or %NULL
20197 * Equivalent to g_desktop_app_info_launch_uris_as_manager() but allows
20198 * you to pass in file descriptors for the stdin, stdout and stderr streams
20199 * of the launched process.
20201 * If application launching occurs via some non-spawn mechanism (e.g. D-Bus
20202 * activation) then @stdin_fd, @stdout_fd and @stderr_fd are ignored.
20204 * Returns: %TRUE on successful launch, %FALSE otherwise.
20210 * g_desktop_app_info_list_actions:
20211 * @info: a #GDesktopAppInfo
20213 * Returns the list of "additional application actions" supported on the
20214 * desktop file, as per the desktop file specification.
20216 * As per the specification, this is the list of actions that are
20217 * explicitly listed in the "Actions" key of the [Desktop Entry] group.
20219 * Returns: (array zero-terminated=1) (element-type utf8) (transfer none): a list of strings, always non-%NULL
20225 * g_desktop_app_info_lookup_get_default_for_uri_scheme:
20226 * @lookup: a #GDesktopAppInfoLookup
20227 * @uri_scheme: a string containing a URI scheme.
20229 * Gets the default application for launching applications
20230 * using this URI scheme for a particular #GDesktopAppInfoLookup
20233 * The #GDesktopAppInfoLookup interface and this function is used
20234 * to implement g_app_info_get_default_for_uri_scheme() backends
20235 * in a GIO module. There is no reason for applications to use it
20236 * directly. Applications should use g_app_info_get_default_for_uri_scheme().
20238 * Returns: (transfer full) (nullable): #GAppInfo for given @uri_scheme or
20240 * Deprecated: 2.28: The #GDesktopAppInfoLookup interface is deprecated and
20246 * g_desktop_app_info_new:
20247 * @desktop_id: the desktop file id
20249 * Creates a new #GDesktopAppInfo based on a desktop file id.
20251 * A desktop file id is the basename of the desktop file, including the
20252 * .desktop extension. GIO is looking for a desktop file with this name
20253 * in the `applications` subdirectories of the XDG
20254 * data directories (i.e. the directories specified in the `XDG_DATA_HOME`
20255 * and `XDG_DATA_DIRS` environment variables). GIO also supports the
20256 * prefix-to-subdirectory mapping that is described in the
20257 * [Menu Spec](http://standards.freedesktop.org/menu-spec/latest/)
20258 * (i.e. a desktop id of kde-foo.desktop will match
20259 * `/usr/share/applications/kde/foo.desktop`).
20261 * Returns: (nullable): a new #GDesktopAppInfo, or %NULL if no desktop
20262 * file with that id exists.
20267 * g_desktop_app_info_new_from_filename:
20268 * @filename: (type filename): the path of a desktop file, in the GLib
20269 * filename encoding
20271 * Creates a new #GDesktopAppInfo.
20273 * Returns: (nullable): a new #GDesktopAppInfo or %NULL on error.
20278 * g_desktop_app_info_new_from_keyfile:
20279 * @key_file: an opened #GKeyFile
20281 * Creates a new #GDesktopAppInfo.
20283 * Returns: (nullable): a new #GDesktopAppInfo or %NULL on error.
20289 * g_desktop_app_info_search:
20290 * @search_string: the search string to use
20292 * Searches desktop files for ones that match @search_string.
20294 * The return value is an array of strvs. Each strv contains a list of
20295 * applications that matched @search_string with an equal score. The
20296 * outer list is sorted by score so that the first strv contains the
20297 * best-matching applications, and so on.
20298 * The algorithm for determining matches is undefined and may change at
20301 * None of the search results are subjected to the normal validation
20302 * checks performed by g_desktop_app_info_new() (for example, checking that
20303 * the executable referenced by a result exists), and so it is possible for
20304 * g_desktop_app_info_new() to return %NULL when passed an app ID returned by
20305 * this function. It is expected that calling code will do this when
20306 * subsequently creating a #GDesktopAppInfo for each result.
20308 * Returns: (array zero-terminated=1) (element-type GStrv) (transfer full): a
20309 * list of strvs. Free each item with g_strfreev() and free the outer
20310 * list with g_free().
20315 * g_desktop_app_info_set_desktop_env:
20316 * @desktop_env: a string specifying what desktop this is
20318 * Sets the name of the desktop that the application is running in.
20319 * This is used by g_app_info_should_show() and
20320 * g_desktop_app_info_get_show_in() to evaluate the
20321 * `OnlyShowIn` and `NotShowIn`
20322 * desktop entry fields.
20324 * Should be called only once; subsequent calls are ignored.
20326 * Deprecated: 2.42: do not use this API. Since 2.42 the value of the
20327 * `XDG_CURRENT_DESKTOP` environment variable will be used.
20332 * g_drive_can_eject:
20333 * @drive: a #GDrive.
20335 * Checks if a drive can be ejected.
20337 * Returns: %TRUE if the @drive can be ejected, %FALSE otherwise.
20342 * g_drive_can_poll_for_media:
20343 * @drive: a #GDrive.
20345 * Checks if a drive can be polled for media changes.
20347 * Returns: %TRUE if the @drive can be polled for media changes,
20348 * %FALSE otherwise.
20353 * g_drive_can_start:
20354 * @drive: a #GDrive.
20356 * Checks if a drive can be started.
20358 * Returns: %TRUE if the @drive can be started, %FALSE otherwise.
20364 * g_drive_can_start_degraded:
20365 * @drive: a #GDrive.
20367 * Checks if a drive can be started degraded.
20369 * Returns: %TRUE if the @drive can be started degraded, %FALSE otherwise.
20375 * g_drive_can_stop:
20376 * @drive: a #GDrive.
20378 * Checks if a drive can be stopped.
20380 * Returns: %TRUE if the @drive can be stopped, %FALSE otherwise.
20387 * @drive: a #GDrive.
20388 * @flags: flags affecting the unmount if required for eject
20389 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
20390 * @callback: (nullable): a #GAsyncReadyCallback, or %NULL.
20391 * @user_data: user data to pass to @callback
20393 * Asynchronously ejects a drive.
20395 * When the operation is finished, @callback will be called.
20396 * You can then call g_drive_eject_finish() to obtain the
20397 * result of the operation.
20399 * Deprecated: 2.22: Use g_drive_eject_with_operation() instead.
20404 * g_drive_eject_finish:
20405 * @drive: a #GDrive.
20406 * @result: a #GAsyncResult.
20407 * @error: a #GError, or %NULL
20409 * Finishes ejecting a drive.
20411 * Returns: %TRUE if the drive has been ejected successfully,
20412 * %FALSE otherwise.
20413 * Deprecated: 2.22: Use g_drive_eject_with_operation_finish() instead.
20418 * g_drive_eject_with_operation:
20419 * @drive: a #GDrive.
20420 * @flags: flags affecting the unmount if required for eject
20421 * @mount_operation: (nullable): a #GMountOperation or %NULL to avoid
20422 * user interaction.
20423 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
20424 * @callback: (nullable): a #GAsyncReadyCallback, or %NULL.
20425 * @user_data: user data passed to @callback.
20427 * Ejects a drive. This is an asynchronous operation, and is
20428 * finished by calling g_drive_eject_with_operation_finish() with the @drive
20429 * and #GAsyncResult data returned in the @callback.
20436 * g_drive_eject_with_operation_finish:
20437 * @drive: a #GDrive.
20438 * @result: a #GAsyncResult.
20439 * @error: a #GError location to store the error occurring, or %NULL to
20442 * Finishes ejecting a drive. If any errors occurred during the operation,
20443 * @error will be set to contain the errors and %FALSE will be returned.
20445 * Returns: %TRUE if the drive was successfully ejected. %FALSE otherwise.
20451 * g_drive_enumerate_identifiers:
20452 * @drive: a #GDrive
20454 * Gets the kinds of identifiers that @drive has.
20455 * Use g_drive_get_identifier() to obtain the identifiers
20458 * Returns: (transfer full) (array zero-terminated=1): a %NULL-terminated
20459 * array of strings containing kinds of identifiers. Use g_strfreev()
20465 * g_drive_get_icon:
20466 * @drive: a #GDrive.
20468 * Gets the icon for @drive.
20470 * Returns: (transfer full): #GIcon for the @drive.
20471 * Free the returned object with g_object_unref().
20476 * g_drive_get_identifier:
20477 * @drive: a #GDrive
20478 * @kind: the kind of identifier to return
20480 * Gets the identifier of the given kind for @drive. The only
20481 * identifier currently available is
20482 * #G_DRIVE_IDENTIFIER_KIND_UNIX_DEVICE.
20484 * Returns: (nullable) (transfer full): a newly allocated string containing the
20485 * requested identifier, or %NULL if the #GDrive
20486 * doesn't have this kind of identifier.
20491 * g_drive_get_name:
20492 * @drive: a #GDrive.
20494 * Gets the name of @drive.
20496 * Returns: a string containing @drive's name. The returned
20497 * string should be freed when no longer needed.
20502 * g_drive_get_sort_key:
20503 * @drive: A #GDrive.
20505 * Gets the sort key for @drive, if any.
20507 * Returns: (nullable): Sorting key for @drive or %NULL if no such key is available.
20513 * g_drive_get_start_stop_type:
20514 * @drive: a #GDrive.
20516 * Gets a hint about how a drive can be started/stopped.
20518 * Returns: A value from the #GDriveStartStopType enumeration.
20524 * g_drive_get_symbolic_icon:
20525 * @drive: a #GDrive.
20527 * Gets the icon for @drive.
20529 * Returns: (transfer full): symbolic #GIcon for the @drive.
20530 * Free the returned object with g_object_unref().
20536 * g_drive_get_volumes:
20537 * @drive: a #GDrive.
20539 * Get a list of mountable volumes for @drive.
20541 * The returned list should be freed with g_list_free(), after
20542 * its elements have been unreffed with g_object_unref().
20544 * Returns: (element-type GVolume) (transfer full): #GList containing any #GVolume objects on the given @drive.
20549 * g_drive_has_media:
20550 * @drive: a #GDrive.
20552 * Checks if the @drive has media. Note that the OS may not be polling
20553 * the drive for media changes; see g_drive_is_media_check_automatic()
20554 * for more details.
20556 * Returns: %TRUE if @drive has media, %FALSE otherwise.
20561 * g_drive_has_volumes:
20562 * @drive: a #GDrive.
20564 * Check if @drive has any mountable volumes.
20566 * Returns: %TRUE if the @drive contains volumes, %FALSE otherwise.
20571 * g_drive_is_media_check_automatic:
20572 * @drive: a #GDrive.
20574 * Checks if @drive is capable of automatically detecting media changes.
20576 * Returns: %TRUE if the @drive is capable of automatically detecting
20577 * media changes, %FALSE otherwise.
20582 * g_drive_is_media_removable:
20583 * @drive: a #GDrive.
20585 * Checks if the @drive supports removable media.
20587 * Returns: %TRUE if @drive supports removable media, %FALSE otherwise.
20592 * g_drive_is_removable:
20593 * @drive: a #GDrive.
20595 * Checks if the #GDrive and/or its media is considered removable by the user.
20596 * See g_drive_is_media_removable().
20598 * Returns: %TRUE if @drive and/or its media is considered removable, %FALSE otherwise.
20604 * g_drive_poll_for_media:
20605 * @drive: a #GDrive.
20606 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
20607 * @callback: (nullable): a #GAsyncReadyCallback, or %NULL.
20608 * @user_data: user data to pass to @callback
20610 * Asynchronously polls @drive to see if media has been inserted or removed.
20612 * When the operation is finished, @callback will be called.
20613 * You can then call g_drive_poll_for_media_finish() to obtain the
20614 * result of the operation.
20619 * g_drive_poll_for_media_finish:
20620 * @drive: a #GDrive.
20621 * @result: a #GAsyncResult.
20622 * @error: a #GError, or %NULL
20624 * Finishes an operation started with g_drive_poll_for_media() on a drive.
20626 * Returns: %TRUE if the drive has been poll_for_mediaed successfully,
20627 * %FALSE otherwise.
20633 * @drive: a #GDrive.
20634 * @flags: flags affecting the start operation.
20635 * @mount_operation: (nullable): a #GMountOperation or %NULL to avoid
20636 * user interaction.
20637 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
20638 * @callback: (nullable): a #GAsyncReadyCallback, or %NULL.
20639 * @user_data: user data to pass to @callback
20641 * Asynchronously starts a drive.
20643 * When the operation is finished, @callback will be called.
20644 * You can then call g_drive_start_finish() to obtain the
20645 * result of the operation.
20652 * g_drive_start_finish:
20653 * @drive: a #GDrive.
20654 * @result: a #GAsyncResult.
20655 * @error: a #GError, or %NULL
20657 * Finishes starting a drive.
20659 * Returns: %TRUE if the drive has been started successfully,
20660 * %FALSE otherwise.
20667 * @drive: a #GDrive.
20668 * @flags: flags affecting the unmount if required for stopping.
20669 * @mount_operation: (nullable): a #GMountOperation or %NULL to avoid
20670 * user interaction.
20671 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
20672 * @callback: (nullable): a #GAsyncReadyCallback, or %NULL.
20673 * @user_data: user data to pass to @callback
20675 * Asynchronously stops a drive.
20677 * When the operation is finished, @callback will be called.
20678 * You can then call g_drive_stop_finish() to obtain the
20679 * result of the operation.
20686 * g_drive_stop_finish:
20687 * @drive: a #GDrive.
20688 * @result: a #GAsyncResult.
20689 * @error: a #GError, or %NULL
20691 * Finishes stopping a drive.
20693 * Returns: %TRUE if the drive has been stopped successfully,
20694 * %FALSE otherwise.
20700 * g_dtls_client_connection_get_accepted_cas:
20701 * @conn: the #GDtlsClientConnection
20703 * Gets the list of distinguished names of the Certificate Authorities
20704 * that the server will accept certificates from. This will be set
20705 * during the TLS handshake if the server requests a certificate.
20706 * Otherwise, it will be %NULL.
20708 * Each item in the list is a #GByteArray which contains the complete
20709 * subject DN of the certificate authority.
20711 * Returns: (element-type GByteArray) (transfer full): the list of
20712 * CA DNs. You should unref each element with g_byte_array_unref() and then
20713 * the free the list with g_list_free().
20719 * g_dtls_client_connection_get_server_identity:
20720 * @conn: the #GDtlsClientConnection
20722 * Gets @conn's expected server identity
20724 * Returns: (transfer none): a #GSocketConnectable describing the
20725 * expected server identity, or %NULL if the expected identity is not
20732 * g_dtls_client_connection_get_validation_flags:
20733 * @conn: the #GDtlsClientConnection
20735 * Gets @conn's validation flags
20737 * Returns: the validation flags
20743 * g_dtls_client_connection_new:
20744 * @base_socket: the #GDatagramBased to wrap
20745 * @server_identity: (nullable): the expected identity of the server
20746 * @error: #GError for error reporting, or %NULL to ignore.
20748 * Creates a new #GDtlsClientConnection wrapping @base_socket which is
20749 * assumed to communicate with the server identified by @server_identity.
20751 * Returns: (transfer full) (type GDtlsClientConnection): the new
20752 * #GDtlsClientConnection, or %NULL on error
20758 * g_dtls_client_connection_set_server_identity:
20759 * @conn: the #GDtlsClientConnection
20760 * @identity: a #GSocketConnectable describing the expected server identity
20762 * Sets @conn's expected server identity, which is used both to tell
20763 * servers on virtual hosts which certificate to present, and also
20764 * to let @conn know what name to look for in the certificate when
20765 * performing %G_TLS_CERTIFICATE_BAD_IDENTITY validation, if enabled.
20772 * g_dtls_client_connection_set_validation_flags:
20773 * @conn: the #GDtlsClientConnection
20774 * @flags: the #GTlsCertificateFlags to use
20776 * Sets @conn's validation flags, to override the default set of
20777 * checks performed when validating a server certificate. By default,
20778 * %G_TLS_CERTIFICATE_VALIDATE_ALL is used.
20785 * g_dtls_connection_close:
20786 * @conn: a #GDtlsConnection
20787 * @cancellable: (nullable): a #GCancellable, or %NULL
20788 * @error: a #GError, or %NULL
20790 * Close the DTLS connection. This is equivalent to calling
20791 * g_dtls_connection_shutdown() to shut down both sides of the connection.
20793 * Closing a #GDtlsConnection waits for all buffered but untransmitted data to
20794 * be sent before it completes. It then sends a `close_notify` DTLS alert to the
20795 * peer and may wait for a `close_notify` to be received from the peer. It does
20796 * not close the underlying #GDtlsConnection:base-socket; that must be closed
20799 * Once @conn is closed, all other operations will return %G_IO_ERROR_CLOSED.
20800 * Closing a #GDtlsConnection multiple times will not return an error.
20802 * #GDtlsConnections will be automatically closed when the last reference is
20803 * dropped, but you might want to call this function to make sure resources are
20804 * released as early as possible.
20806 * If @cancellable is cancelled, the #GDtlsConnection may be left
20807 * partially-closed and any pending untransmitted data may be lost. Call
20808 * g_dtls_connection_close() again to complete closing the #GDtlsConnection.
20810 * Returns: %TRUE on success, %FALSE otherwise
20816 * g_dtls_connection_close_async:
20817 * @conn: a #GDtlsConnection
20818 * @io_priority: the [I/O priority][io-priority] of the request
20819 * @cancellable: (nullable): a #GCancellable, or %NULL
20820 * @callback: callback to call when the close operation is complete
20821 * @user_data: the data to pass to the callback function
20823 * Asynchronously close the DTLS connection. See g_dtls_connection_close() for
20824 * more information.
20831 * g_dtls_connection_close_finish:
20832 * @conn: a #GDtlsConnection
20833 * @result: a #GAsyncResult
20834 * @error: a #GError pointer, or %NULL
20836 * Finish an asynchronous TLS close operation. See g_dtls_connection_close()
20837 * for more information.
20839 * Returns: %TRUE on success, %FALSE on failure, in which
20840 * case @error will be set
20846 * g_dtls_connection_emit_accept_certificate:
20847 * @conn: a #GDtlsConnection
20848 * @peer_cert: the peer's #GTlsCertificate
20849 * @errors: the problems with @peer_cert
20851 * Used by #GDtlsConnection implementations to emit the
20852 * #GDtlsConnection::accept-certificate signal.
20854 * Returns: %TRUE if one of the signal handlers has returned
20855 * %TRUE to accept @peer_cert
20861 * g_dtls_connection_get_certificate:
20862 * @conn: a #GDtlsConnection
20864 * Gets @conn's certificate, as set by
20865 * g_dtls_connection_set_certificate().
20867 * Returns: (transfer none) (nullable): @conn's certificate, or %NULL
20873 * g_dtls_connection_get_channel_binding_data:
20874 * @conn: a #GDtlsConnection
20875 * @type: #GTlsChannelBindingType type of data to fetch
20876 * @data: (out callee-allocates) (optional) (transfer none): #GByteArray is
20877 * filled with the binding data, or %NULL
20878 * @error: a #GError pointer, or %NULL
20880 * Query the TLS backend for TLS channel binding data of @type for @conn.
20882 * This call retrieves TLS channel binding data as specified in RFC
20883 * [5056](https://tools.ietf.org/html/rfc5056), RFC
20884 * [5929](https://tools.ietf.org/html/rfc5929), and related RFCs. The
20885 * binding data is returned in @data. The @data is resized by the callee
20886 * using #GByteArray buffer management and will be freed when the @data
20887 * is destroyed by g_byte_array_unref(). If @data is %NULL, it will only
20888 * check whether TLS backend is able to fetch the data (e.g. whether @type
20889 * is supported by the TLS backend). It does not guarantee that the data
20890 * will be available though. That could happen if TLS connection does not
20891 * support @type or the binding data is not available yet due to additional
20892 * negotiation or input required.
20894 * Returns: %TRUE on success, %FALSE otherwise
20900 * g_dtls_connection_get_ciphersuite_name:
20901 * @conn: a #GDTlsConnection
20903 * Returns the name of the current DTLS ciphersuite, or %NULL if the
20904 * connection has not handshaked or has been closed. Beware that the TLS
20905 * backend may use any of multiple different naming conventions, because
20906 * OpenSSL and GnuTLS have their own ciphersuite naming conventions that
20907 * are different from each other and different from the standard, IANA-
20908 * registered ciphersuite names. The ciphersuite name is intended to be
20909 * displayed to the user for informative purposes only, and parsing it
20910 * is not recommended.
20912 * Returns: (nullable): The name of the current DTLS ciphersuite, or %NULL
20918 * g_dtls_connection_get_database:
20919 * @conn: a #GDtlsConnection
20921 * Gets the certificate database that @conn uses to verify
20922 * peer certificates. See g_dtls_connection_set_database().
20924 * Returns: (transfer none) (nullable): the certificate database that @conn uses or %NULL
20930 * g_dtls_connection_get_interaction:
20931 * @conn: a connection
20933 * Get the object that will be used to interact with the user. It will be used
20934 * for things like prompting the user for passwords. If %NULL is returned, then
20935 * no user interaction will occur for this connection.
20937 * Returns: (transfer none) (nullable): The interaction object.
20943 * g_dtls_connection_get_negotiated_protocol:
20944 * @conn: a #GDtlsConnection
20946 * Gets the name of the application-layer protocol negotiated during
20949 * If the peer did not use the ALPN extension, or did not advertise a
20950 * protocol that matched one of @conn's protocols, or the TLS backend
20951 * does not support ALPN, then this will be %NULL. See
20952 * g_dtls_connection_set_advertised_protocols().
20954 * Returns: (nullable): the negotiated protocol, or %NULL
20960 * g_dtls_connection_get_peer_certificate:
20961 * @conn: a #GDtlsConnection
20963 * Gets @conn's peer's certificate after the handshake has completed
20964 * or failed. (It is not set during the emission of
20965 * #GDtlsConnection::accept-certificate.)
20967 * Returns: (transfer none) (nullable): @conn's peer's certificate, or %NULL
20973 * g_dtls_connection_get_peer_certificate_errors:
20974 * @conn: a #GDtlsConnection
20976 * Gets the errors associated with validating @conn's peer's
20977 * certificate, after the handshake has completed or failed. (It is
20978 * not set during the emission of #GDtlsConnection::accept-certificate.)
20980 * Returns: @conn's peer's certificate errors
20986 * g_dtls_connection_get_protocol_version:
20987 * @conn: a #GDTlsConnection
20989 * Returns the current DTLS protocol version, which may be
20990 * %G_TLS_PROTOCOL_VERSION_UNKNOWN if the connection has not handshaked, or
20991 * has been closed, or if the TLS backend has implemented a protocol version
20992 * that is not a recognized #GTlsProtocolVersion.
20994 * Returns: The current DTLS protocol version
21000 * g_dtls_connection_get_rehandshake_mode:
21001 * @conn: a #GDtlsConnection
21003 * Gets @conn rehandshaking mode. See
21004 * g_dtls_connection_set_rehandshake_mode() for details.
21006 * Returns: %G_TLS_REHANDSHAKE_SAFELY
21008 * Deprecated: 2.64.: Changing the rehandshake mode is no longer
21009 * required for compatibility. Also, rehandshaking has been removed
21010 * from the TLS protocol in TLS 1.3.
21015 * g_dtls_connection_get_require_close_notify:
21016 * @conn: a #GDtlsConnection
21018 * Tests whether or not @conn expects a proper TLS close notification
21019 * when the connection is closed. See
21020 * g_dtls_connection_set_require_close_notify() for details.
21022 * Returns: %TRUE if @conn requires a proper TLS close notification.
21028 * g_dtls_connection_handshake:
21029 * @conn: a #GDtlsConnection
21030 * @cancellable: (nullable): a #GCancellable, or %NULL
21031 * @error: a #GError, or %NULL
21033 * Attempts a TLS handshake on @conn.
21035 * On the client side, it is never necessary to call this method;
21036 * although the connection needs to perform a handshake after
21037 * connecting, #GDtlsConnection will handle this for you automatically
21038 * when you try to send or receive data on the connection. You can call
21039 * g_dtls_connection_handshake() manually if you want to know whether
21040 * the initial handshake succeeded or failed (as opposed to just
21041 * immediately trying to use @conn to read or write, in which case,
21042 * if it fails, it may not be possible to tell if it failed before
21043 * or after completing the handshake), but beware that servers may reject
21044 * client authentication after the handshake has completed, so a
21045 * successful handshake does not indicate the connection will be usable.
21047 * Likewise, on the server side, although a handshake is necessary at
21048 * the beginning of the communication, you do not need to call this
21049 * function explicitly unless you want clearer error reporting.
21051 * Previously, calling g_dtls_connection_handshake() after the initial
21052 * handshake would trigger a rehandshake; however, this usage was
21053 * deprecated in GLib 2.60 because rehandshaking was removed from the
21054 * TLS protocol in TLS 1.3. Since GLib 2.64, calling this function after
21055 * the initial handshake will no longer do anything.
21057 * #GDtlsConnection::accept_certificate may be emitted during the
21060 * Returns: success or failure
21066 * g_dtls_connection_handshake_async:
21067 * @conn: a #GDtlsConnection
21068 * @io_priority: the [I/O priority][io-priority] of the request
21069 * @cancellable: (nullable): a #GCancellable, or %NULL
21070 * @callback: callback to call when the handshake is complete
21071 * @user_data: the data to pass to the callback function
21073 * Asynchronously performs a TLS handshake on @conn. See
21074 * g_dtls_connection_handshake() for more information.
21081 * g_dtls_connection_handshake_finish:
21082 * @conn: a #GDtlsConnection
21083 * @result: a #GAsyncResult.
21084 * @error: a #GError pointer, or %NULL
21086 * Finish an asynchronous TLS handshake operation. See
21087 * g_dtls_connection_handshake() for more information.
21089 * Returns: %TRUE on success, %FALSE on failure, in which
21090 * case @error will be set.
21096 * g_dtls_connection_set_advertised_protocols:
21097 * @conn: a #GDtlsConnection
21098 * @protocols: (array zero-terminated=1) (nullable): a %NULL-terminated
21099 * array of ALPN protocol names (eg, "http/1.1", "h2"), or %NULL
21101 * Sets the list of application-layer protocols to advertise that the
21102 * caller is willing to speak on this connection. The
21103 * Application-Layer Protocol Negotiation (ALPN) extension will be
21104 * used to negotiate a compatible protocol with the peer; use
21105 * g_dtls_connection_get_negotiated_protocol() to find the negotiated
21106 * protocol after the handshake. Specifying %NULL for the the value
21107 * of @protocols will disable ALPN negotiation.
21109 * See [IANA TLS ALPN Protocol IDs](https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids)
21110 * for a list of registered protocol IDs.
21117 * g_dtls_connection_set_certificate:
21118 * @conn: a #GDtlsConnection
21119 * @certificate: the certificate to use for @conn
21121 * This sets the certificate that @conn will present to its peer
21122 * during the TLS handshake. For a #GDtlsServerConnection, it is
21123 * mandatory to set this, and that will normally be done at construct
21126 * For a #GDtlsClientConnection, this is optional. If a handshake fails
21127 * with %G_TLS_ERROR_CERTIFICATE_REQUIRED, that means that the server
21128 * requires a certificate, and if you try connecting again, you should
21129 * call this method first. You can call
21130 * g_dtls_client_connection_get_accepted_cas() on the failed connection
21131 * to get a list of Certificate Authorities that the server will
21132 * accept certificates from.
21134 * (It is also possible that a server will allow the connection with
21135 * or without a certificate; in that case, if you don't provide a
21136 * certificate, you can tell that the server requested one by the fact
21137 * that g_dtls_client_connection_get_accepted_cas() will return
21145 * g_dtls_connection_set_database:
21146 * @conn: a #GDtlsConnection
21147 * @database: (nullable): a #GTlsDatabase
21149 * Sets the certificate database that is used to verify peer certificates.
21150 * This is set to the default database by default. See
21151 * g_tls_backend_get_default_database(). If set to %NULL, then
21152 * peer certificate validation will always set the
21153 * %G_TLS_CERTIFICATE_UNKNOWN_CA error (meaning
21154 * #GDtlsConnection::accept-certificate will always be emitted on
21155 * client-side connections, unless that bit is not set in
21156 * #GDtlsClientConnection:validation-flags).
21163 * g_dtls_connection_set_interaction:
21164 * @conn: a connection
21165 * @interaction: (nullable): an interaction object, or %NULL
21167 * Set the object that will be used to interact with the user. It will be used
21168 * for things like prompting the user for passwords.
21170 * The @interaction argument will normally be a derived subclass of
21171 * #GTlsInteraction. %NULL can also be provided if no user interaction
21172 * should occur for this connection.
21179 * g_dtls_connection_set_rehandshake_mode:
21180 * @conn: a #GDtlsConnection
21181 * @mode: the rehandshaking mode
21183 * Since GLib 2.64, changing the rehandshake mode is no longer supported
21184 * and will have no effect. With TLS 1.3, rehandshaking has been removed from
21185 * the TLS protocol, replaced by separate post-handshake authentication and
21186 * rekey operations.
21189 * Deprecated: 2.60.: Changing the rehandshake mode is no longer
21190 * required for compatibility. Also, rehandshaking has been removed
21191 * from the TLS protocol in TLS 1.3.
21196 * g_dtls_connection_set_require_close_notify:
21197 * @conn: a #GDtlsConnection
21198 * @require_close_notify: whether or not to require close notification
21200 * Sets whether or not @conn expects a proper TLS close notification
21201 * before the connection is closed. If this is %TRUE (the default),
21202 * then @conn will expect to receive a TLS close notification from its
21203 * peer before the connection is closed, and will return a
21204 * %G_TLS_ERROR_EOF error if the connection is closed without proper
21205 * notification (since this may indicate a network error, or
21206 * man-in-the-middle attack).
21208 * In some protocols, the application will know whether or not the
21209 * connection was closed cleanly based on application-level data
21210 * (because the application-level data includes a length field, or is
21211 * somehow self-delimiting); in this case, the close notify is
21212 * redundant and may be omitted. You
21213 * can use g_dtls_connection_set_require_close_notify() to tell @conn
21214 * to allow an "unannounced" connection close, in which case the close
21215 * will show up as a 0-length read, as in a non-TLS
21216 * #GDatagramBased, and it is up to the application to check that
21217 * the data has been fully received.
21219 * Note that this only affects the behavior when the peer closes the
21220 * connection; when the application calls g_dtls_connection_close_async() on
21221 * @conn itself, this will send a close notification regardless of the
21222 * setting of this property. If you explicitly want to do an unclean
21223 * close, you can close @conn's #GDtlsConnection:base-socket rather
21224 * than closing @conn itself.
21231 * g_dtls_connection_shutdown:
21232 * @conn: a #GDtlsConnection
21233 * @shutdown_read: %TRUE to stop reception of incoming datagrams
21234 * @shutdown_write: %TRUE to stop sending outgoing datagrams
21235 * @cancellable: (nullable): a #GCancellable, or %NULL
21236 * @error: a #GError, or %NULL
21238 * Shut down part or all of a DTLS connection.
21240 * If @shutdown_read is %TRUE then the receiving side of the connection is shut
21241 * down, and further reading is disallowed. Subsequent calls to
21242 * g_datagram_based_receive_messages() will return %G_IO_ERROR_CLOSED.
21244 * If @shutdown_write is %TRUE then the sending side of the connection is shut
21245 * down, and further writing is disallowed. Subsequent calls to
21246 * g_datagram_based_send_messages() will return %G_IO_ERROR_CLOSED.
21248 * It is allowed for both @shutdown_read and @shutdown_write to be TRUE — this
21249 * is equivalent to calling g_dtls_connection_close().
21251 * If @cancellable is cancelled, the #GDtlsConnection may be left
21252 * partially-closed and any pending untransmitted data may be lost. Call
21253 * g_dtls_connection_shutdown() again to complete closing the #GDtlsConnection.
21255 * Returns: %TRUE on success, %FALSE otherwise
21261 * g_dtls_connection_shutdown_async:
21262 * @conn: a #GDtlsConnection
21263 * @shutdown_read: %TRUE to stop reception of incoming datagrams
21264 * @shutdown_write: %TRUE to stop sending outgoing datagrams
21265 * @io_priority: the [I/O priority][io-priority] of the request
21266 * @cancellable: (nullable): a #GCancellable, or %NULL
21267 * @callback: callback to call when the shutdown operation is complete
21268 * @user_data: the data to pass to the callback function
21270 * Asynchronously shut down part or all of the DTLS connection. See
21271 * g_dtls_connection_shutdown() for more information.
21278 * g_dtls_connection_shutdown_finish:
21279 * @conn: a #GDtlsConnection
21280 * @result: a #GAsyncResult
21281 * @error: a #GError pointer, or %NULL
21283 * Finish an asynchronous TLS shutdown operation. See
21284 * g_dtls_connection_shutdown() for more information.
21286 * Returns: %TRUE on success, %FALSE on failure, in which
21287 * case @error will be set
21293 * g_dtls_server_connection_new:
21294 * @base_socket: the #GDatagramBased to wrap
21295 * @certificate: (nullable): the default server certificate, or %NULL
21296 * @error: #GError for error reporting, or %NULL to ignore
21298 * Creates a new #GDtlsServerConnection wrapping @base_socket.
21300 * Returns: (transfer full) (type GDtlsServerConnection): the new
21301 * #GDtlsServerConnection, or %NULL on error
21307 * g_emblem_get_icon:
21308 * @emblem: a #GEmblem from which the icon should be extracted.
21310 * Gives back the icon from @emblem.
21312 * Returns: (transfer none): a #GIcon. The returned object belongs to
21313 * the emblem and should not be modified or freed.
21319 * g_emblem_get_origin:
21320 * @emblem: a #GEmblem
21322 * Gets the origin of the emblem.
21324 * Returns: (transfer none): the origin of the emblem
21331 * @icon: a GIcon containing the icon.
21333 * Creates a new emblem for @icon.
21335 * Returns: a new #GEmblem.
21341 * g_emblem_new_with_origin:
21342 * @icon: a GIcon containing the icon.
21343 * @origin: a GEmblemOrigin enum defining the emblem's origin
21345 * Creates a new emblem for @icon.
21347 * Returns: a new #GEmblem.
21353 * g_emblemed_icon_add_emblem:
21354 * @emblemed: a #GEmblemedIcon
21355 * @emblem: a #GEmblem
21357 * Adds @emblem to the #GList of #GEmblems.
21364 * g_emblemed_icon_clear_emblems:
21365 * @emblemed: a #GEmblemedIcon
21367 * Removes all the emblems from @icon.
21374 * g_emblemed_icon_get_emblems:
21375 * @emblemed: a #GEmblemedIcon
21377 * Gets the list of emblems for the @icon.
21379 * Returns: (element-type Gio.Emblem) (transfer none): a #GList of
21380 * #GEmblems that is owned by @emblemed
21386 * g_emblemed_icon_get_icon:
21387 * @emblemed: a #GEmblemedIcon
21389 * Gets the main icon for @emblemed.
21391 * Returns: (transfer none): a #GIcon that is owned by @emblemed
21397 * g_emblemed_icon_new:
21399 * @emblem: (nullable): a #GEmblem, or %NULL
21401 * Creates a new emblemed icon for @icon with the emblem @emblem.
21403 * Returns: (transfer full) (type GEmblemedIcon): a new #GIcon
21409 * g_file_append_to:
21410 * @file: input #GFile
21411 * @flags: a set of #GFileCreateFlags
21412 * @cancellable: (nullable): optional #GCancellable object,
21414 * @error: a #GError, or %NULL
21416 * Gets an output stream for appending data to the file.
21417 * If the file doesn't already exist it is created.
21419 * By default files created are generally readable by everyone,
21420 * but if you pass #G_FILE_CREATE_PRIVATE in @flags the file
21421 * will be made readable only to the current user, to the level that
21422 * is supported on the target filesystem.
21424 * If @cancellable is not %NULL, then the operation can be cancelled
21425 * by triggering the cancellable object from another thread. If the
21426 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
21429 * Some file systems don't allow all file names, and may return an
21430 * %G_IO_ERROR_INVALID_FILENAME error. If the file is a directory the
21431 * %G_IO_ERROR_IS_DIRECTORY error will be returned. Other errors are
21432 * possible too, and depend on what kind of filesystem the file is on.
21434 * Returns: (transfer full): a #GFileOutputStream, or %NULL on error.
21435 * Free the returned object with g_object_unref().
21440 * g_file_append_to_async:
21441 * @file: input #GFile
21442 * @flags: a set of #GFileCreateFlags
21443 * @io_priority: the [I/O priority][io-priority] of the request
21444 * @cancellable: (nullable): optional #GCancellable object,
21446 * @callback: (scope async): a #GAsyncReadyCallback to call
21447 * when the request is satisfied
21448 * @user_data: (closure): the data to pass to callback function
21450 * Asynchronously opens @file for appending.
21452 * For more details, see g_file_append_to() which is
21453 * the synchronous version of this call.
21455 * When the operation is finished, @callback will be called.
21456 * You can then call g_file_append_to_finish() to get the result
21457 * of the operation.
21462 * g_file_append_to_finish:
21463 * @file: input #GFile
21464 * @res: #GAsyncResult
21465 * @error: a #GError, or %NULL
21467 * Finishes an asynchronous file append operation started with
21468 * g_file_append_to_async().
21470 * Returns: (transfer full): a valid #GFileOutputStream
21471 * or %NULL on error.
21472 * Free the returned object with g_object_unref().
21477 * g_file_attribute_info_list_add:
21478 * @list: a #GFileAttributeInfoList.
21479 * @name: the name of the attribute to add.
21480 * @type: the #GFileAttributeType for the attribute.
21481 * @flags: #GFileAttributeInfoFlags for the attribute.
21483 * Adds a new attribute with @name to the @list, setting
21484 * its @type and @flags.
21489 * g_file_attribute_info_list_dup:
21490 * @list: a #GFileAttributeInfoList to duplicate.
21492 * Makes a duplicate of a file attribute info list.
21494 * Returns: a copy of the given @list.
21499 * g_file_attribute_info_list_lookup:
21500 * @list: a #GFileAttributeInfoList.
21501 * @name: the name of the attribute to look up.
21503 * Gets the file attribute with the name @name from @list.
21505 * Returns: a #GFileAttributeInfo for the @name, or %NULL if an
21506 * attribute isn't found.
21511 * g_file_attribute_info_list_new:
21513 * Creates a new file attribute info list.
21515 * Returns: a #GFileAttributeInfoList.
21520 * g_file_attribute_info_list_ref:
21521 * @list: a #GFileAttributeInfoList to reference.
21523 * References a file attribute info list.
21525 * Returns: #GFileAttributeInfoList or %NULL on error.
21530 * g_file_attribute_info_list_unref:
21531 * @list: The #GFileAttributeInfoList to unreference.
21533 * Removes a reference from the given @list. If the reference count
21534 * falls to zero, the @list is deleted.
21539 * g_file_attribute_matcher_enumerate_namespace:
21540 * @matcher: a #GFileAttributeMatcher.
21541 * @ns: a string containing a file attribute namespace.
21543 * Checks if the matcher will match all of the keys in a given namespace.
21544 * This will always return %TRUE if a wildcard character is in use (e.g. if
21545 * matcher was created with "standard::*" and @ns is "standard", or if matcher was created
21546 * using "*" and namespace is anything.)
21548 * TODO: this is awkwardly worded.
21550 * Returns: %TRUE if the matcher matches all of the entries
21551 * in the given @ns, %FALSE otherwise.
21556 * g_file_attribute_matcher_enumerate_next:
21557 * @matcher: a #GFileAttributeMatcher.
21559 * Gets the next matched attribute from a #GFileAttributeMatcher.
21561 * Returns: (nullable): a string containing the next attribute or, %NULL if
21562 * no more attribute exist.
21567 * g_file_attribute_matcher_matches:
21568 * @matcher: a #GFileAttributeMatcher.
21569 * @attribute: a file attribute key.
21571 * Checks if an attribute will be matched by an attribute matcher. If
21572 * the matcher was created with the "*" matching string, this function
21573 * will always return %TRUE.
21575 * Returns: %TRUE if @attribute matches @matcher. %FALSE otherwise.
21580 * g_file_attribute_matcher_matches_only:
21581 * @matcher: a #GFileAttributeMatcher.
21582 * @attribute: a file attribute key.
21584 * Checks if a attribute matcher only matches a given attribute. Always
21585 * returns %FALSE if "*" was used when creating the matcher.
21587 * Returns: %TRUE if the matcher only matches @attribute. %FALSE otherwise.
21592 * g_file_attribute_matcher_new:
21593 * @attributes: an attribute string to match.
21595 * Creates a new file attribute matcher, which matches attributes
21596 * against a given string. #GFileAttributeMatchers are reference
21597 * counted structures, and are created with a reference count of 1. If
21598 * the number of references falls to 0, the #GFileAttributeMatcher is
21599 * automatically destroyed.
21601 * The @attributes string should be formatted with specific keys separated
21602 * from namespaces with a double colon. Several "namespace::key" strings may be
21603 * concatenated with a single comma (e.g. "standard::type,standard::is-hidden").
21604 * The wildcard "*" may be used to match all keys and namespaces, or
21605 * "namespace::*" will match all keys in a given namespace.
21607 * ## Examples of file attribute matcher strings and results
21609 * - `"*"`: matches all attributes.
21610 * - `"standard::is-hidden"`: matches only the key is-hidden in the
21611 * standard namespace.
21612 * - `"standard::type,unix::*"`: matches the type key in the standard
21613 * namespace and all keys in the unix namespace.
21615 * Returns: a #GFileAttributeMatcher
21620 * g_file_attribute_matcher_ref:
21621 * @matcher: a #GFileAttributeMatcher.
21623 * References a file attribute matcher.
21625 * Returns: a #GFileAttributeMatcher.
21630 * g_file_attribute_matcher_subtract:
21631 * @matcher: (nullable): Matcher to subtract from
21632 * @subtract: (nullable): The matcher to subtract
21634 * Subtracts all attributes of @subtract from @matcher and returns
21635 * a matcher that supports those attributes.
21637 * Note that currently it is not possible to remove a single
21638 * attribute when the @matcher matches the whole namespace - or remove
21639 * a namespace or attribute when the matcher matches everything. This
21640 * is a limitation of the current implementation, but may be fixed
21643 * Returns: (nullable): A file attribute matcher matching all attributes of
21644 * @matcher that are not matched by @subtract
21649 * g_file_attribute_matcher_to_string:
21650 * @matcher: (nullable): a #GFileAttributeMatcher.
21652 * Prints what the matcher is matching against. The format will be
21653 * equal to the format passed to g_file_attribute_matcher_new().
21654 * The output however, might not be identical, as the matcher may
21655 * decide to use a different order or omit needless parts.
21657 * Returns: a string describing the attributes the matcher matches
21658 * against or %NULL if @matcher was %NULL.
21664 * g_file_attribute_matcher_unref:
21665 * @matcher: a #GFileAttributeMatcher.
21667 * Unreferences @matcher. If the reference count falls below 1,
21668 * the @matcher is automatically freed.
21673 * g_file_attribute_value_dup:
21674 * @other: a #GFileAttributeValue to duplicate.
21676 * Duplicates a file attribute.
21678 * Returns: a duplicate of the @other.
21683 * g_file_attribute_value_set:
21684 * @attr: a #GFileAttributeValue to set the value in.
21685 * @new_value: a #GFileAttributeValue to get the value from.
21687 * Sets an attribute's value from another attribute.
21692 * g_file_build_attribute_list_for_copy:
21693 * @file: a #GFile to copy attributes to
21694 * @flags: a set of #GFileCopyFlags
21695 * @cancellable: (nullable): optional #GCancellable object,
21697 * @error: a #GError, %NULL to ignore
21699 * Prepares the file attribute query string for copying to @file.
21701 * This function prepares an attribute query string to be
21702 * passed to g_file_query_info() to get a list of attributes
21703 * normally copied with the file (see g_file_copy_attributes()
21704 * for the detailed description). This function is used by the
21705 * implementation of g_file_copy_attributes() and is useful
21706 * when one needs to query and set the attributes in two
21707 * stages (e.g., for recursive move of a directory).
21709 * Returns: an attribute query string for g_file_query_info(),
21710 * or %NULL if an error occurs.
21717 * @source: input #GFile
21718 * @destination: destination #GFile
21719 * @flags: set of #GFileCopyFlags
21720 * @cancellable: (nullable): optional #GCancellable object,
21722 * @progress_callback: (nullable) (scope call): function to callback with
21723 * progress information, or %NULL if progress information is not needed
21724 * @progress_callback_data: (closure): user data to pass to @progress_callback
21725 * @error: #GError to set on error, or %NULL
21727 * Copies the file @source to the location specified by @destination.
21728 * Can not handle recursive copies of directories.
21730 * If the flag #G_FILE_COPY_OVERWRITE is specified an already
21731 * existing @destination file is overwritten.
21733 * If the flag #G_FILE_COPY_NOFOLLOW_SYMLINKS is specified then symlinks
21734 * will be copied as symlinks, otherwise the target of the
21735 * @source symlink will be copied.
21737 * If the flag #G_FILE_COPY_ALL_METADATA is specified then all the metadata
21738 * that is possible to copy is copied, not just the default subset (which,
21739 * for instance, does not include the owner, see #GFileInfo).
21741 * If @cancellable is not %NULL, then the operation can be cancelled by
21742 * triggering the cancellable object from another thread. If the operation
21743 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
21745 * If @progress_callback is not %NULL, then the operation can be monitored
21746 * by setting this to a #GFileProgressCallback function.
21747 * @progress_callback_data will be passed to this function. It is guaranteed
21748 * that this callback will be called after all data has been transferred with
21749 * the total number of bytes copied during the operation.
21751 * If the @source file does not exist, then the %G_IO_ERROR_NOT_FOUND error
21752 * is returned, independent on the status of the @destination.
21754 * If #G_FILE_COPY_OVERWRITE is not specified and the target exists, then
21755 * the error %G_IO_ERROR_EXISTS is returned.
21757 * If trying to overwrite a file over a directory, the %G_IO_ERROR_IS_DIRECTORY
21758 * error is returned. If trying to overwrite a directory with a directory the
21759 * %G_IO_ERROR_WOULD_MERGE error is returned.
21761 * If the source is a directory and the target does not exist, or
21762 * #G_FILE_COPY_OVERWRITE is specified and the target is a file, then the
21763 * %G_IO_ERROR_WOULD_RECURSE error is returned.
21765 * If you are interested in copying the #GFile object itself (not the on-disk
21766 * file), see g_file_dup().
21768 * Returns: %TRUE on success, %FALSE otherwise.
21773 * g_file_copy_async:
21774 * @source: input #GFile
21775 * @destination: destination #GFile
21776 * @flags: set of #GFileCopyFlags
21777 * @io_priority: the [I/O priority][io-priority] of the request
21778 * @cancellable: (nullable): optional #GCancellable object,
21780 * @progress_callback: (nullable) (scope notified): function to callback with progress
21781 * information, or %NULL if progress information is not needed
21782 * @progress_callback_data: (closure progress_callback) (nullable): user data to pass to @progress_callback
21783 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
21784 * @user_data: (closure callback): the data to pass to callback function
21786 * Copies the file @source to the location specified by @destination
21787 * asynchronously. For details of the behaviour, see g_file_copy().
21789 * If @progress_callback is not %NULL, then that function that will be called
21790 * just like in g_file_copy(). The callback will run in the default main context
21791 * of the thread calling g_file_copy_async() — the same context as @callback is
21794 * When the operation is finished, @callback will be called. You can then call
21795 * g_file_copy_finish() to get the result of the operation.
21800 * g_file_copy_attributes:
21801 * @source: a #GFile with attributes
21802 * @destination: a #GFile to copy attributes to
21803 * @flags: a set of #GFileCopyFlags
21804 * @cancellable: (nullable): optional #GCancellable object,
21806 * @error: a #GError, %NULL to ignore
21808 * Copies the file attributes from @source to @destination.
21810 * Normally only a subset of the file attributes are copied,
21811 * those that are copies in a normal file copy operation
21812 * (which for instance does not include e.g. owner). However
21813 * if #G_FILE_COPY_ALL_METADATA is specified in @flags, then
21814 * all the metadata that is possible to copy is copied. This
21815 * is useful when implementing move by copy + delete source.
21817 * Returns: %TRUE if the attributes were copied successfully,
21818 * %FALSE otherwise.
21823 * g_file_copy_finish:
21824 * @file: input #GFile
21825 * @res: a #GAsyncResult
21826 * @error: a #GError, or %NULL
21828 * Finishes copying the file started with g_file_copy_async().
21830 * Returns: a %TRUE on success, %FALSE on error.
21836 * @file: input #GFile
21837 * @flags: a set of #GFileCreateFlags
21838 * @cancellable: (nullable): optional #GCancellable object,
21840 * @error: a #GError, or %NULL
21842 * Creates a new file and returns an output stream for writing to it.
21843 * The file must not already exist.
21845 * By default files created are generally readable by everyone,
21846 * but if you pass #G_FILE_CREATE_PRIVATE in @flags the file
21847 * will be made readable only to the current user, to the level
21848 * that is supported on the target filesystem.
21850 * If @cancellable is not %NULL, then the operation can be cancelled
21851 * by triggering the cancellable object from another thread. If the
21852 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
21855 * If a file or directory with this name already exists the
21856 * %G_IO_ERROR_EXISTS error will be returned. Some file systems don't
21857 * allow all file names, and may return an %G_IO_ERROR_INVALID_FILENAME
21858 * error, and if the name is to long %G_IO_ERROR_FILENAME_TOO_LONG will
21859 * be returned. Other errors are possible too, and depend on what kind
21860 * of filesystem the file is on.
21862 * Returns: (transfer full): a #GFileOutputStream for the newly created
21863 * file, or %NULL on error.
21864 * Free the returned object with g_object_unref().
21869 * g_file_create_async:
21870 * @file: input #GFile
21871 * @flags: a set of #GFileCreateFlags
21872 * @io_priority: the [I/O priority][io-priority] of the request
21873 * @cancellable: (nullable): optional #GCancellable object,
21875 * @callback: (scope async): a #GAsyncReadyCallback to call
21876 * when the request is satisfied
21877 * @user_data: (closure): the data to pass to callback function
21879 * Asynchronously creates a new file and returns an output stream
21880 * for writing to it. The file must not already exist.
21882 * For more details, see g_file_create() which is
21883 * the synchronous version of this call.
21885 * When the operation is finished, @callback will be called.
21886 * You can then call g_file_create_finish() to get the result
21887 * of the operation.
21892 * g_file_create_finish:
21893 * @file: input #GFile
21894 * @res: a #GAsyncResult
21895 * @error: a #GError, or %NULL
21897 * Finishes an asynchronous file create operation started with
21898 * g_file_create_async().
21900 * Returns: (transfer full): a #GFileOutputStream or %NULL on error.
21901 * Free the returned object with g_object_unref().
21906 * g_file_create_readwrite:
21908 * @flags: a set of #GFileCreateFlags
21909 * @cancellable: (nullable): optional #GCancellable object,
21911 * @error: return location for a #GError, or %NULL
21913 * Creates a new file and returns a stream for reading and
21914 * writing to it. The file must not already exist.
21916 * By default files created are generally readable by everyone,
21917 * but if you pass #G_FILE_CREATE_PRIVATE in @flags the file
21918 * will be made readable only to the current user, to the level
21919 * that is supported on the target filesystem.
21921 * If @cancellable is not %NULL, then the operation can be cancelled
21922 * by triggering the cancellable object from another thread. If the
21923 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
21926 * If a file or directory with this name already exists, the
21927 * %G_IO_ERROR_EXISTS error will be returned. Some file systems don't
21928 * allow all file names, and may return an %G_IO_ERROR_INVALID_FILENAME
21929 * error, and if the name is too long, %G_IO_ERROR_FILENAME_TOO_LONG
21930 * will be returned. Other errors are possible too, and depend on what
21931 * kind of filesystem the file is on.
21933 * Note that in many non-local file cases read and write streams are
21934 * not supported, so make sure you really need to do read and write
21935 * streaming, rather than just opening for reading or writing.
21937 * Returns: (transfer full): a #GFileIOStream for the newly created
21938 * file, or %NULL on error.
21939 * Free the returned object with g_object_unref().
21945 * g_file_create_readwrite_async:
21946 * @file: input #GFile
21947 * @flags: a set of #GFileCreateFlags
21948 * @io_priority: the [I/O priority][io-priority] of the request
21949 * @cancellable: (nullable): optional #GCancellable object,
21951 * @callback: (scope async): a #GAsyncReadyCallback to call
21952 * when the request is satisfied
21953 * @user_data: (closure): the data to pass to callback function
21955 * Asynchronously creates a new file and returns a stream
21956 * for reading and writing to it. The file must not already exist.
21958 * For more details, see g_file_create_readwrite() which is
21959 * the synchronous version of this call.
21961 * When the operation is finished, @callback will be called.
21962 * You can then call g_file_create_readwrite_finish() to get
21963 * the result of the operation.
21970 * g_file_create_readwrite_finish:
21971 * @file: input #GFile
21972 * @res: a #GAsyncResult
21973 * @error: a #GError, or %NULL
21975 * Finishes an asynchronous file create operation started with
21976 * g_file_create_readwrite_async().
21978 * Returns: (transfer full): a #GFileIOStream or %NULL on error.
21979 * Free the returned object with g_object_unref().
21985 * g_file_delete: (virtual delete_file)
21986 * @file: input #GFile
21987 * @cancellable: (nullable): optional #GCancellable object,
21989 * @error: a #GError, or %NULL
21991 * Deletes a file. If the @file is a directory, it will only be
21992 * deleted if it is empty. This has the same semantics as g_unlink().
21994 * If @file doesn’t exist, %G_IO_ERROR_NOT_FOUND will be returned. This allows
21995 * for deletion to be implemented avoiding
21996 * [time-of-check to time-of-use races](https://en.wikipedia.org/wiki/Time-of-check_to_time-of-use):
21998 * g_autoptr(GError) local_error = NULL;
21999 * if (!g_file_delete (my_file, my_cancellable, &local_error) &&
22000 * !g_error_matches (local_error, G_IO_ERROR, G_IO_ERROR_NOT_FOUND))
22002 * // deletion failed for some reason other than the file not existing:
22003 * // so report the error
22004 * g_warning ("Failed to delete %s: %s",
22005 * g_file_peek_path (my_file), local_error->message);
22009 * If @cancellable is not %NULL, then the operation can be cancelled by
22010 * triggering the cancellable object from another thread. If the operation
22011 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
22013 * Returns: %TRUE if the file was deleted. %FALSE otherwise.
22018 * g_file_delete_async: (virtual delete_file_async)
22019 * @file: input #GFile
22020 * @io_priority: the [I/O priority][io-priority] of the request
22021 * @cancellable: (nullable): optional #GCancellable object,
22023 * @callback: a #GAsyncReadyCallback to call
22024 * when the request is satisfied
22025 * @user_data: the data to pass to callback function
22027 * Asynchronously delete a file. If the @file is a directory, it will
22028 * only be deleted if it is empty. This has the same semantics as
22036 * g_file_delete_finish: (virtual delete_file_finish)
22037 * @file: input #GFile
22038 * @result: a #GAsyncResult
22039 * @error: a #GError, or %NULL
22041 * Finishes deleting a file started with g_file_delete_async().
22043 * Returns: %TRUE if the file was deleted. %FALSE otherwise.
22049 * g_file_descriptor_based_get_fd:
22050 * @fd_based: a #GFileDescriptorBased.
22052 * Gets the underlying file descriptor.
22054 * Returns: The file descriptor
22061 * @file: input #GFile
22063 * Duplicates a #GFile handle. This operation does not duplicate
22064 * the actual file or directory represented by the #GFile; see
22065 * g_file_copy() if attempting to copy a file.
22067 * g_file_dup() is useful when a second handle is needed to the same underlying
22068 * file, for use in a separate thread (#GFile is not thread-safe). For use
22069 * within the same thread, use g_object_ref() to increment the existing object’s
22072 * This call does no blocking I/O.
22074 * Returns: (transfer full): a new #GFile that is a duplicate
22075 * of the given #GFile.
22080 * g_file_eject_mountable:
22081 * @file: input #GFile
22082 * @flags: flags affecting the operation
22083 * @cancellable: (nullable): optional #GCancellable object,
22085 * @callback: (scope async) (nullable): a #GAsyncReadyCallback to call
22086 * when the request is satisfied, or %NULL
22087 * @user_data: (closure): the data to pass to callback function
22089 * Starts an asynchronous eject on a mountable.
22090 * When this operation has completed, @callback will be called with
22091 * @user_user data, and the operation can be finalized with
22092 * g_file_eject_mountable_finish().
22094 * If @cancellable is not %NULL, then the operation can be cancelled by
22095 * triggering the cancellable object from another thread. If the operation
22096 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
22098 * Deprecated: 2.22: Use g_file_eject_mountable_with_operation() instead.
22103 * g_file_eject_mountable_finish:
22104 * @file: input #GFile
22105 * @result: a #GAsyncResult
22106 * @error: a #GError, or %NULL
22108 * Finishes an asynchronous eject operation started by
22109 * g_file_eject_mountable().
22111 * Returns: %TRUE if the @file was ejected successfully.
22112 * %FALSE otherwise.
22113 * Deprecated: 2.22: Use g_file_eject_mountable_with_operation_finish()
22119 * g_file_eject_mountable_with_operation:
22120 * @file: input #GFile
22121 * @flags: flags affecting the operation
22122 * @mount_operation: (nullable): a #GMountOperation,
22123 * or %NULL to avoid user interaction
22124 * @cancellable: (nullable): optional #GCancellable object,
22126 * @callback: (scope async) (nullable): a #GAsyncReadyCallback to call
22127 * when the request is satisfied, or %NULL
22128 * @user_data: (closure): the data to pass to callback function
22130 * Starts an asynchronous eject on a mountable.
22131 * When this operation has completed, @callback will be called with
22132 * @user_user data, and the operation can be finalized with
22133 * g_file_eject_mountable_with_operation_finish().
22135 * If @cancellable is not %NULL, then the operation can be cancelled by
22136 * triggering the cancellable object from another thread. If the operation
22137 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
22144 * g_file_eject_mountable_with_operation_finish:
22145 * @file: input #GFile
22146 * @result: a #GAsyncResult
22147 * @error: a #GError, or %NULL
22149 * Finishes an asynchronous eject operation started by
22150 * g_file_eject_mountable_with_operation().
22152 * Returns: %TRUE if the @file was ejected successfully.
22153 * %FALSE otherwise.
22159 * g_file_enumerate_children:
22160 * @file: input #GFile
22161 * @attributes: an attribute query string
22162 * @flags: a set of #GFileQueryInfoFlags
22163 * @cancellable: (nullable): optional #GCancellable object,
22165 * @error: #GError for error reporting
22167 * Gets the requested information about the files in a directory.
22168 * The result is a #GFileEnumerator object that will give out
22169 * #GFileInfo objects for all the files in the directory.
22171 * The @attributes value is a string that specifies the file
22172 * attributes that should be gathered. It is not an error if
22173 * it's not possible to read a particular requested attribute
22174 * from a file - it just won't be set. @attributes should
22175 * be a comma-separated list of attributes or attribute wildcards.
22176 * The wildcard "*" means all attributes, and a wildcard like
22177 * "standard::*" means all attributes in the standard namespace.
22178 * An example attribute query be "standard::*,owner::user".
22179 * The standard attributes are available as defines, like
22180 * #G_FILE_ATTRIBUTE_STANDARD_NAME.
22182 * If @cancellable is not %NULL, then the operation can be cancelled
22183 * by triggering the cancellable object from another thread. If the
22184 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
22187 * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will
22188 * be returned. If the file is not a directory, the %G_IO_ERROR_NOT_DIRECTORY
22189 * error will be returned. Other errors are possible too.
22191 * Returns: (transfer full): A #GFileEnumerator if successful,
22192 * %NULL on error. Free the returned object with g_object_unref().
22197 * g_file_enumerate_children_async:
22198 * @file: input #GFile
22199 * @attributes: an attribute query string
22200 * @flags: a set of #GFileQueryInfoFlags
22201 * @io_priority: the [I/O priority][io-priority] of the request
22202 * @cancellable: (nullable): optional #GCancellable object,
22204 * @callback: (scope async): a #GAsyncReadyCallback to call when the
22205 * request is satisfied
22206 * @user_data: (closure): the data to pass to callback function
22208 * Asynchronously gets the requested information about the files
22209 * in a directory. The result is a #GFileEnumerator object that will
22210 * give out #GFileInfo objects for all the files in the directory.
22212 * For more details, see g_file_enumerate_children() which is
22213 * the synchronous version of this call.
22215 * When the operation is finished, @callback will be called. You can
22216 * then call g_file_enumerate_children_finish() to get the result of
22222 * g_file_enumerate_children_finish:
22223 * @file: input #GFile
22224 * @res: a #GAsyncResult
22225 * @error: a #GError
22227 * Finishes an async enumerate children operation.
22228 * See g_file_enumerate_children_async().
22230 * Returns: (transfer full): a #GFileEnumerator or %NULL
22231 * if an error occurred.
22232 * Free the returned object with g_object_unref().
22237 * g_file_enumerator_close:
22238 * @enumerator: a #GFileEnumerator.
22239 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
22240 * @error: location to store the error occurring, or %NULL to ignore
22242 * Releases all resources used by this enumerator, making the
22243 * enumerator return %G_IO_ERROR_CLOSED on all calls.
22245 * This will be automatically called when the last reference
22246 * is dropped, but you might want to call this function to make
22247 * sure resources are released as early as possible.
22249 * Returns: #TRUE on success or #FALSE on error.
22254 * g_file_enumerator_close_async:
22255 * @enumerator: a #GFileEnumerator.
22256 * @io_priority: the [I/O priority][io-priority] of the request
22257 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
22258 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
22259 * @user_data: (closure): the data to pass to callback function
22261 * Asynchronously closes the file enumerator.
22263 * If @cancellable is not %NULL, then the operation can be cancelled by
22264 * triggering the cancellable object from another thread. If the operation
22265 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned in
22266 * g_file_enumerator_close_finish().
22271 * g_file_enumerator_close_finish:
22272 * @enumerator: a #GFileEnumerator.
22273 * @result: a #GAsyncResult.
22274 * @error: a #GError location to store the error occurring, or %NULL to
22277 * Finishes closing a file enumerator, started from g_file_enumerator_close_async().
22279 * If the file enumerator was already closed when g_file_enumerator_close_async()
22280 * was called, then this function will report %G_IO_ERROR_CLOSED in @error, and
22281 * return %FALSE. If the file enumerator had pending operation when the close
22282 * operation was started, then this function will report %G_IO_ERROR_PENDING, and
22283 * return %FALSE. If @cancellable was not %NULL, then the operation may have been
22284 * cancelled by triggering the cancellable object from another thread. If the operation
22285 * was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %FALSE will be
22288 * Returns: %TRUE if the close operation has finished successfully.
22293 * g_file_enumerator_get_child:
22294 * @enumerator: a #GFileEnumerator
22295 * @info: a #GFileInfo gotten from g_file_enumerator_next_file()
22296 * or the async equivalents.
22298 * Return a new #GFile which refers to the file named by @info in the source
22299 * directory of @enumerator. This function is primarily intended to be used
22300 * inside loops with g_file_enumerator_next_file().
22302 * This is a convenience method that's equivalent to:
22303 * |[<!-- language="C" -->
22304 * gchar *name = g_file_info_get_name (info);
22305 * GFile *child = g_file_get_child (g_file_enumerator_get_container (enumr),
22309 * Returns: (transfer full): a #GFile for the #GFileInfo passed it.
22315 * g_file_enumerator_get_container:
22316 * @enumerator: a #GFileEnumerator
22318 * Get the #GFile container which is being enumerated.
22320 * Returns: (transfer none): the #GFile which is being enumerated.
22326 * g_file_enumerator_has_pending:
22327 * @enumerator: a #GFileEnumerator.
22329 * Checks if the file enumerator has pending operations.
22331 * Returns: %TRUE if the @enumerator has pending operations.
22336 * g_file_enumerator_is_closed:
22337 * @enumerator: a #GFileEnumerator.
22339 * Checks if the file enumerator has been closed.
22341 * Returns: %TRUE if the @enumerator is closed.
22346 * g_file_enumerator_iterate:
22347 * @direnum: an open #GFileEnumerator
22348 * @out_info: (out) (transfer none) (optional): Output location for the next #GFileInfo, or %NULL
22349 * @out_child: (out) (transfer none) (optional): Output location for the next #GFile, or %NULL
22350 * @cancellable: a #GCancellable
22351 * @error: a #GError
22353 * This is a version of g_file_enumerator_next_file() that's easier to
22354 * use correctly from C programs. With g_file_enumerator_next_file(),
22355 * the gboolean return value signifies "end of iteration or error", which
22356 * requires allocation of a temporary #GError.
22358 * In contrast, with this function, a %FALSE return from
22359 * g_file_enumerator_iterate() *always* means
22360 * "error". End of iteration is signaled by @out_info or @out_child being %NULL.
22362 * Another crucial difference is that the references for @out_info and
22363 * @out_child are owned by @direnum (they are cached as hidden
22364 * properties). You must not unref them in your own code. This makes
22365 * memory management significantly easier for C code in combination
22368 * Finally, this function optionally allows retrieving a #GFile as
22371 * You must specify at least one of @out_info or @out_child.
22373 * The code pattern for correctly using g_file_enumerator_iterate() from C
22377 * direnum = g_file_enumerate_children (file, ...);
22381 * if (!g_file_enumerator_iterate (direnum, &info, NULL, cancellable, error))
22385 * ... do stuff with "info"; do not unref it! ...
22389 * g_object_unref (direnum); // Note: frees the last @info
22397 * g_file_enumerator_next_file:
22398 * @enumerator: a #GFileEnumerator.
22399 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
22400 * @error: location to store the error occurring, or %NULL to ignore
22402 * Returns information for the next file in the enumerated object.
22403 * Will block until the information is available. The #GFileInfo
22404 * returned from this function will contain attributes that match the
22405 * attribute string that was passed when the #GFileEnumerator was created.
22407 * See the documentation of #GFileEnumerator for information about the
22408 * order of returned files.
22410 * On error, returns %NULL and sets @error to the error. If the
22411 * enumerator is at the end, %NULL will be returned and @error will
22414 * Returns: (nullable) (transfer full): A #GFileInfo or %NULL on error
22415 * or end of enumerator. Free the returned object with
22416 * g_object_unref() when no longer needed.
22421 * g_file_enumerator_next_files_async:
22422 * @enumerator: a #GFileEnumerator.
22423 * @num_files: the number of file info objects to request
22424 * @io_priority: the [I/O priority][io-priority] of the request
22425 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
22426 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
22427 * @user_data: (closure): the data to pass to callback function
22429 * Request information for a number of files from the enumerator asynchronously.
22430 * When all i/o for the operation is finished the @callback will be called with
22431 * the requested information.
22433 * See the documentation of #GFileEnumerator for information about the
22434 * order of returned files.
22436 * The callback can be called with less than @num_files files in case of error
22437 * or at the end of the enumerator. In case of a partial error the callback will
22438 * be called with any succeeding items and no error, and on the next request the
22439 * error will be reported. If a request is cancelled the callback will be called
22440 * with %G_IO_ERROR_CANCELLED.
22442 * During an async request no other sync and async calls are allowed, and will
22443 * result in %G_IO_ERROR_PENDING errors.
22445 * Any outstanding i/o request with higher priority (lower numerical value) will
22446 * be executed before an outstanding request with lower priority. Default
22447 * priority is %G_PRIORITY_DEFAULT.
22452 * g_file_enumerator_next_files_finish:
22453 * @enumerator: a #GFileEnumerator.
22454 * @result: a #GAsyncResult.
22455 * @error: a #GError location to store the error occurring, or %NULL to
22458 * Finishes the asynchronous operation started with g_file_enumerator_next_files_async().
22460 * Returns: (transfer full) (element-type Gio.FileInfo): a #GList of #GFileInfos. You must free the list with
22461 * g_list_free() and unref the infos with g_object_unref() when you're
22467 * g_file_enumerator_set_pending:
22468 * @enumerator: a #GFileEnumerator.
22469 * @pending: a boolean value.
22471 * Sets the file enumerator as having pending operations.
22477 * @file1: the first #GFile
22478 * @file2: the second #GFile
22480 * Checks if the two given #GFiles refer to the same file.
22482 * Note that two #GFiles that differ can still refer to the same
22483 * file on the filesystem due to various forms of filename
22486 * This call does no blocking I/O.
22488 * Returns: %TRUE if @file1 and @file2 are equal.
22493 * g_file_find_enclosing_mount:
22494 * @file: input #GFile
22495 * @cancellable: (nullable): optional #GCancellable object,
22497 * @error: a #GError
22499 * Gets a #GMount for the #GFile.
22501 * #GMount is returned only for user interesting locations, see
22502 * #GVolumeMonitor. If the #GFileIface for @file does not have a #mount,
22503 * @error will be set to %G_IO_ERROR_NOT_FOUND and %NULL #will be returned.
22505 * If @cancellable is not %NULL, then the operation can be cancelled by
22506 * triggering the cancellable object from another thread. If the operation
22507 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
22509 * Returns: (transfer full): a #GMount where the @file is located
22510 * or %NULL on error.
22511 * Free the returned object with g_object_unref().
22516 * g_file_find_enclosing_mount_async:
22518 * @io_priority: the [I/O priority][io-priority] of the request
22519 * @cancellable: (nullable): optional #GCancellable object,
22521 * @callback: (scope async): a #GAsyncReadyCallback to call
22522 * when the request is satisfied
22523 * @user_data: (closure): the data to pass to callback function
22525 * Asynchronously gets the mount for the file.
22527 * For more details, see g_file_find_enclosing_mount() which is
22528 * the synchronous version of this call.
22530 * When the operation is finished, @callback will be called.
22531 * You can then call g_file_find_enclosing_mount_finish() to
22532 * get the result of the operation.
22537 * g_file_find_enclosing_mount_finish:
22539 * @res: a #GAsyncResult
22540 * @error: a #GError
22542 * Finishes an asynchronous find mount request.
22543 * See g_file_find_enclosing_mount_async().
22545 * Returns: (transfer full): #GMount for given @file or %NULL on error.
22546 * Free the returned object with g_object_unref().
22551 * g_file_get_basename: (virtual get_basename)
22552 * @file: input #GFile
22554 * Gets the base name (the last component of the path) for a given #GFile.
22556 * If called for the top level of a system (such as the filesystem root
22557 * or a uri like sftp://host/) it will return a single directory separator
22558 * (and on Windows, possibly a drive letter).
22560 * The base name is a byte string (not UTF-8). It has no defined encoding
22561 * or rules other than it may not contain zero bytes. If you want to use
22562 * filenames in a user interface you should use the display name that you
22563 * can get by requesting the %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME
22564 * attribute with g_file_query_info().
22566 * This call does no blocking I/O.
22568 * Returns: (type filename) (nullable): string containing the #GFile's
22569 * base name, or %NULL if given #GFile is invalid. The returned string
22570 * should be freed with g_free() when no longer needed.
22575 * g_file_get_child:
22576 * @file: input #GFile
22577 * @name: (type filename): string containing the child's basename
22579 * Gets a child of @file with basename equal to @name.
22581 * Note that the file with that specific name might not exist, but
22582 * you can still have a #GFile that points to it. You can use this
22583 * for instance to create that file.
22585 * This call does no blocking I/O.
22587 * Returns: (transfer full): a #GFile to a child specified by @name.
22588 * Free the returned object with g_object_unref().
22593 * g_file_get_child_for_display_name:
22594 * @file: input #GFile
22595 * @display_name: string to a possible child
22596 * @error: return location for an error
22598 * Gets the child of @file for a given @display_name (i.e. a UTF-8
22599 * version of the name). If this function fails, it returns %NULL
22600 * and @error will be set. This is very useful when constructing a
22601 * #GFile for a new file and the user entered the filename in the
22602 * user interface, for instance when you select a directory and
22603 * type a filename in the file selector.
22605 * This call does no blocking I/O.
22607 * Returns: (transfer full): a #GFile to the specified child, or
22608 * %NULL if the display name couldn't be converted.
22609 * Free the returned object with g_object_unref().
22614 * g_file_get_parent:
22615 * @file: input #GFile
22617 * Gets the parent directory for the @file.
22618 * If the @file represents the root directory of the
22619 * file system, then %NULL will be returned.
22621 * This call does no blocking I/O.
22623 * Returns: (nullable) (transfer full): a #GFile structure to the
22624 * parent of the given #GFile or %NULL if there is no parent. Free
22625 * the returned object with g_object_unref().
22630 * g_file_get_parse_name:
22631 * @file: input #GFile
22633 * Gets the parse name of the @file.
22634 * A parse name is a UTF-8 string that describes the
22635 * file such that one can get the #GFile back using
22636 * g_file_parse_name().
22638 * This is generally used to show the #GFile as a nice
22639 * full-pathname kind of string in a user interface,
22640 * like in a location entry.
22642 * For local files with names that can safely be converted
22643 * to UTF-8 the pathname is used, otherwise the IRI is used
22644 * (a form of URI that allows UTF-8 characters unescaped).
22646 * This call does no blocking I/O.
22648 * Returns: a string containing the #GFile's parse name.
22649 * The returned string should be freed with g_free()
22650 * when no longer needed.
22655 * g_file_get_path: (virtual get_path)
22656 * @file: input #GFile
22658 * Gets the local pathname for #GFile, if one exists. If non-%NULL, this is
22659 * guaranteed to be an absolute, canonical path. It might contain symlinks.
22661 * This call does no blocking I/O.
22663 * Returns: (type filename) (nullable): string containing the #GFile's path,
22664 * or %NULL if no such path exists. The returned string should be freed
22665 * with g_free() when no longer needed.
22670 * g_file_get_relative_path: (virtual get_relative_path)
22671 * @parent: input #GFile
22672 * @descendant: input #GFile
22674 * Gets the path for @descendant relative to @parent.
22676 * This call does no blocking I/O.
22678 * Returns: (type filename) (nullable): string with the relative path from
22679 * @descendant to @parent, or %NULL if @descendant doesn't have @parent as
22680 * prefix. The returned string should be freed with g_free() when
22681 * no longer needed.
22687 * @file: input #GFile
22689 * Gets the URI for the @file.
22691 * This call does no blocking I/O.
22693 * Returns: a string containing the #GFile's URI. If the #GFile was constructed
22694 * with an invalid URI, an invalid URI is returned.
22695 * The returned string should be freed with g_free()
22696 * when no longer needed.
22701 * g_file_get_uri_scheme:
22702 * @file: input #GFile
22704 * Gets the URI scheme for a #GFile.
22705 * RFC 3986 decodes the scheme as:
22707 * URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
22709 * Common schemes include "file", "http", "ftp", etc.
22711 * The scheme can be different from the one used to construct the #GFile,
22712 * in that it might be replaced with one that is logically equivalent to the #GFile.
22714 * This call does no blocking I/O.
22716 * Returns: (nullable): a string containing the URI scheme for the given
22717 * #GFile or %NULL if the #GFile was constructed with an invalid URI. The
22718 * returned string should be freed with g_free() when no longer needed.
22723 * g_file_has_parent:
22724 * @file: input #GFile
22725 * @parent: (nullable): the parent to check for, or %NULL
22727 * Checks if @file has a parent, and optionally, if it is @parent.
22729 * If @parent is %NULL then this function returns %TRUE if @file has any
22730 * parent at all. If @parent is non-%NULL then %TRUE is only returned
22731 * if @file is an immediate child of @parent.
22733 * Returns: %TRUE if @file is an immediate child of @parent (or any parent in
22734 * the case that @parent is %NULL).
22740 * g_file_has_prefix: (virtual prefix_matches)
22741 * @file: input #GFile
22742 * @prefix: input #GFile
22744 * Checks whether @file has the prefix specified by @prefix.
22746 * In other words, if the names of initial elements of @file's
22747 * pathname match @prefix. Only full pathname elements are matched,
22748 * so a path like /foo is not considered a prefix of /foobar, only
22751 * A #GFile is not a prefix of itself. If you want to check for
22752 * equality, use g_file_equal().
22754 * This call does no I/O, as it works purely on names. As such it can
22755 * sometimes return %FALSE even if @file is inside a @prefix (from a
22756 * filesystem point of view), because the prefix of @file is an alias
22759 * Returns: %TRUE if the @file's parent, grandparent, etc is @prefix,
22760 * %FALSE otherwise.
22765 * g_file_has_uri_scheme:
22766 * @file: input #GFile
22767 * @uri_scheme: a string containing a URI scheme
22769 * Checks to see if a #GFile has a given URI scheme.
22771 * This call does no blocking I/O.
22773 * Returns: %TRUE if #GFile's backend supports the
22774 * given URI scheme, %FALSE if URI scheme is %NULL,
22775 * not supported, or #GFile is invalid.
22780 * g_file_hash: (virtual hash)
22781 * @file: (type GFile): #gconstpointer to a #GFile
22783 * Creates a hash value for a #GFile.
22785 * This call does no blocking I/O.
22787 * Returns: 0 if @file is not a valid #GFile, otherwise an
22788 * integer that can be used as hash value for the #GFile.
22789 * This function is intended for easily hashing a #GFile to
22790 * add to a #GHashTable or similar data structure.
22795 * g_file_icon_get_file:
22798 * Gets the #GFile associated with the given @icon.
22800 * Returns: (transfer none): a #GFile.
22808 * Creates a new icon for a file.
22810 * Returns: (transfer full) (type GFileIcon): a #GIcon for the given
22811 * @file, or %NULL on error.
22816 * g_file_info_clear_status:
22817 * @info: a #GFileInfo.
22819 * Clears the status information from @info.
22824 * g_file_info_copy_into:
22825 * @src_info: source to copy attributes from.
22826 * @dest_info: destination to copy attributes to.
22828 * First clears all of the [GFileAttribute][gio-GFileAttribute] of @dest_info,
22829 * and then copies all of the file attributes from @src_info to @dest_info.
22835 * @other: a #GFileInfo.
22837 * Duplicates a file info structure.
22839 * Returns: (transfer full): a duplicate #GFileInfo of @other.
22844 * g_file_info_get_access_date_time:
22845 * @info: a #GFileInfo.
22847 * Gets the access time of the current @info and returns it as a
22850 * This requires the %G_FILE_ATTRIBUTE_TIME_ACCESS attribute. If
22851 * %G_FILE_ATTRIBUTE_TIME_ACCESS_USEC is provided, the resulting #GDateTime
22852 * will have microsecond precision.
22854 * Returns: (transfer full) (nullable): access time, or %NULL if unknown
22860 * g_file_info_get_attribute_as_string:
22861 * @info: a #GFileInfo.
22862 * @attribute: a file attribute key.
22864 * Gets the value of a attribute, formatted as a string.
22865 * This escapes things as needed to make the string valid
22868 * Returns: (nullable): a UTF-8 string associated with the given @attribute, or
22869 * %NULL if the attribute wasn’t set.
22870 * When you're done with the string it must be freed with g_free().
22875 * g_file_info_get_attribute_boolean:
22876 * @info: a #GFileInfo.
22877 * @attribute: a file attribute key.
22879 * Gets the value of a boolean attribute. If the attribute does not
22880 * contain a boolean value, %FALSE will be returned.
22882 * Returns: the boolean value contained within the attribute.
22887 * g_file_info_get_attribute_byte_string:
22888 * @info: a #GFileInfo.
22889 * @attribute: a file attribute key.
22891 * Gets the value of a byte string attribute. If the attribute does
22892 * not contain a byte string, %NULL will be returned.
22894 * Returns: (nullable): the contents of the @attribute value as a byte string, or
22900 * g_file_info_get_attribute_data:
22901 * @info: a #GFileInfo
22902 * @attribute: a file attribute key
22903 * @type: (out) (optional): return location for the attribute type, or %NULL
22904 * @value_pp: (out) (optional) (not nullable): return location for the
22905 * attribute value, or %NULL; the attribute value will not be %NULL
22906 * @status: (out) (optional): return location for the attribute status, or %NULL
22908 * Gets the attribute type, value and status for an attribute key.
22910 * Returns: (transfer none): %TRUE if @info has an attribute named @attribute,
22911 * %FALSE otherwise.
22916 * g_file_info_get_attribute_int32:
22917 * @info: a #GFileInfo.
22918 * @attribute: a file attribute key.
22920 * Gets a signed 32-bit integer contained within the attribute. If the
22921 * attribute does not contain a signed 32-bit integer, or is invalid,
22922 * 0 will be returned.
22924 * Returns: a signed 32-bit integer from the attribute.
22929 * g_file_info_get_attribute_int64:
22930 * @info: a #GFileInfo.
22931 * @attribute: a file attribute key.
22933 * Gets a signed 64-bit integer contained within the attribute. If the
22934 * attribute does not contain a signed 64-bit integer, or is invalid,
22935 * 0 will be returned.
22937 * Returns: a signed 64-bit integer from the attribute.
22942 * g_file_info_get_attribute_object:
22943 * @info: a #GFileInfo.
22944 * @attribute: a file attribute key.
22946 * Gets the value of a #GObject attribute. If the attribute does
22947 * not contain a #GObject, %NULL will be returned.
22949 * Returns: (transfer none) (nullable): a #GObject associated with the given @attribute,
22950 * or %NULL otherwise.
22955 * g_file_info_get_attribute_status:
22956 * @info: a #GFileInfo
22957 * @attribute: a file attribute key
22959 * Gets the attribute status for an attribute key.
22961 * Returns: a #GFileAttributeStatus for the given @attribute, or
22962 * %G_FILE_ATTRIBUTE_STATUS_UNSET if the key is invalid.
22967 * g_file_info_get_attribute_string:
22968 * @info: a #GFileInfo.
22969 * @attribute: a file attribute key.
22971 * Gets the value of a string attribute. If the attribute does
22972 * not contain a string, %NULL will be returned.
22974 * Returns: (nullable): the contents of the @attribute value as a UTF-8 string,
22975 * or %NULL otherwise.
22980 * g_file_info_get_attribute_stringv:
22981 * @info: a #GFileInfo.
22982 * @attribute: a file attribute key.
22984 * Gets the value of a stringv attribute. If the attribute does
22985 * not contain a stringv, %NULL will be returned.
22987 * Returns: (transfer none) (nullable): the contents of the @attribute value as a stringv,
22988 * or %NULL otherwise. Do not free. These returned strings are UTF-8.
22994 * g_file_info_get_attribute_type:
22995 * @info: a #GFileInfo.
22996 * @attribute: a file attribute key.
22998 * Gets the attribute type for an attribute key.
23000 * Returns: a #GFileAttributeType for the given @attribute, or
23001 * %G_FILE_ATTRIBUTE_TYPE_INVALID if the key is not set.
23006 * g_file_info_get_attribute_uint32:
23007 * @info: a #GFileInfo.
23008 * @attribute: a file attribute key.
23010 * Gets an unsigned 32-bit integer contained within the attribute. If the
23011 * attribute does not contain an unsigned 32-bit integer, or is invalid,
23012 * 0 will be returned.
23014 * Returns: an unsigned 32-bit integer from the attribute.
23019 * g_file_info_get_attribute_uint64:
23020 * @info: a #GFileInfo.
23021 * @attribute: a file attribute key.
23023 * Gets a unsigned 64-bit integer contained within the attribute. If the
23024 * attribute does not contain an unsigned 64-bit integer, or is invalid,
23025 * 0 will be returned.
23027 * Returns: a unsigned 64-bit integer from the attribute.
23032 * g_file_info_get_content_type:
23033 * @info: a #GFileInfo.
23035 * Gets the file's content type.
23037 * Returns: (nullable): a string containing the file's content type,
23038 * or %NULL if unknown.
23043 * g_file_info_get_creation_date_time:
23044 * @info: a #GFileInfo.
23046 * Gets the creation time of the current @info and returns it as a
23049 * This requires the %G_FILE_ATTRIBUTE_TIME_CREATED attribute. If
23050 * %G_FILE_ATTRIBUTE_TIME_CREATED_USEC is provided, the resulting #GDateTime
23051 * will have microsecond precision.
23053 * Returns: (transfer full) (nullable): creation time, or %NULL if unknown
23059 * g_file_info_get_deletion_date:
23060 * @info: a #GFileInfo.
23062 * Returns the #GDateTime representing the deletion date of the file, as
23063 * available in G_FILE_ATTRIBUTE_TRASH_DELETION_DATE. If the
23064 * G_FILE_ATTRIBUTE_TRASH_DELETION_DATE attribute is unset, %NULL is returned.
23066 * Returns: (nullable): a #GDateTime, or %NULL.
23072 * g_file_info_get_display_name:
23073 * @info: a #GFileInfo.
23075 * Gets a display name for a file. This is guaranteed to always be set.
23077 * Returns: (not nullable): a string containing the display name.
23082 * g_file_info_get_edit_name:
23083 * @info: a #GFileInfo.
23085 * Gets the edit name for a file.
23087 * Returns: a string containing the edit name.
23092 * g_file_info_get_etag:
23093 * @info: a #GFileInfo.
23095 * Gets the [entity tag][gfile-etag] for a given
23096 * #GFileInfo. See %G_FILE_ATTRIBUTE_ETAG_VALUE.
23098 * Returns: (nullable): a string containing the value of the "etag:value" attribute.
23103 * g_file_info_get_file_type:
23104 * @info: a #GFileInfo.
23106 * Gets a file's type (whether it is a regular file, symlink, etc).
23107 * This is different from the file's content type, see g_file_info_get_content_type().
23109 * Returns: a #GFileType for the given file.
23114 * g_file_info_get_icon:
23115 * @info: a #GFileInfo.
23117 * Gets the icon for a file.
23119 * Returns: (nullable) (transfer none): #GIcon for the given @info.
23124 * g_file_info_get_is_backup:
23125 * @info: a #GFileInfo.
23127 * Checks if a file is a backup file.
23129 * Returns: %TRUE if file is a backup file, %FALSE otherwise.
23134 * g_file_info_get_is_hidden:
23135 * @info: a #GFileInfo.
23137 * Checks if a file is hidden.
23139 * Returns: %TRUE if the file is a hidden file, %FALSE otherwise.
23144 * g_file_info_get_is_symlink:
23145 * @info: a #GFileInfo.
23147 * Checks if a file is a symlink.
23149 * Returns: %TRUE if the given @info is a symlink.
23154 * g_file_info_get_modification_date_time:
23155 * @info: a #GFileInfo.
23157 * Gets the modification time of the current @info and returns it as a
23160 * This requires the %G_FILE_ATTRIBUTE_TIME_MODIFIED attribute. If
23161 * %G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC is provided, the resulting #GDateTime
23162 * will have microsecond precision.
23164 * Returns: (transfer full) (nullable): modification time, or %NULL if unknown
23170 * g_file_info_get_modification_time:
23171 * @info: a #GFileInfo.
23172 * @result: (out caller-allocates): a #GTimeVal.
23174 * Gets the modification time of the current @info and sets it
23177 * Deprecated: 2.62: Use g_file_info_get_modification_date_time() instead, as
23178 * #GTimeVal is deprecated due to the year 2038 problem.
23183 * g_file_info_get_name:
23184 * @info: a #GFileInfo.
23186 * Gets the name for a file. This is guaranteed to always be set.
23188 * Returns: (type filename) (not nullable): a string containing the file name.
23193 * g_file_info_get_size:
23194 * @info: a #GFileInfo.
23196 * Gets the file's size (in bytes). The size is retrieved through the value of
23197 * the %G_FILE_ATTRIBUTE_STANDARD_SIZE attribute and is converted
23198 * from #guint64 to #goffset before returning the result.
23200 * Returns: a #goffset containing the file's size (in bytes).
23205 * g_file_info_get_sort_order:
23206 * @info: a #GFileInfo.
23208 * Gets the value of the sort_order attribute from the #GFileInfo.
23209 * See %G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER.
23211 * Returns: a #gint32 containing the value of the "standard::sort_order" attribute.
23216 * g_file_info_get_symbolic_icon:
23217 * @info: a #GFileInfo.
23219 * Gets the symbolic icon for a file.
23221 * Returns: (nullable) (transfer none): #GIcon for the given @info.
23227 * g_file_info_get_symlink_target:
23228 * @info: a #GFileInfo.
23230 * Gets the symlink target for a given #GFileInfo.
23232 * Returns: (nullable): a string containing the symlink target.
23237 * g_file_info_has_attribute:
23238 * @info: a #GFileInfo.
23239 * @attribute: a file attribute key.
23241 * Checks if a file info structure has an attribute named @attribute.
23243 * Returns: %TRUE if @info has an attribute named @attribute,
23244 * %FALSE otherwise.
23249 * g_file_info_has_namespace:
23250 * @info: a #GFileInfo.
23251 * @name_space: a file attribute namespace.
23253 * Checks if a file info structure has an attribute in the
23254 * specified @name_space.
23256 * Returns: %TRUE if @info has an attribute in @name_space,
23257 * %FALSE otherwise.
23263 * g_file_info_list_attributes:
23264 * @info: a #GFileInfo.
23265 * @name_space: (nullable): a file attribute key's namespace, or %NULL to list
23268 * Lists the file info structure's attributes.
23270 * Returns: (nullable) (array zero-terminated=1) (transfer full): a
23271 * null-terminated array of strings of all of the possible attribute
23272 * types for the given @name_space, or %NULL on error.
23279 * Creates a new file info structure.
23281 * Returns: a #GFileInfo.
23286 * g_file_info_remove_attribute:
23287 * @info: a #GFileInfo.
23288 * @attribute: a file attribute key.
23290 * Removes all cases of @attribute from @info if it exists.
23295 * g_file_info_set_access_date_time:
23296 * @info: a #GFileInfo.
23297 * @atime: (not nullable): a #GDateTime.
23299 * Sets the %G_FILE_ATTRIBUTE_TIME_ACCESS and
23300 * %G_FILE_ATTRIBUTE_TIME_ACCESS_USEC attributes in the file info to the
23301 * given date/time value.
23308 * g_file_info_set_attribute:
23309 * @info: a #GFileInfo.
23310 * @attribute: a file attribute key.
23311 * @type: a #GFileAttributeType
23312 * @value_p: (not nullable): pointer to the value
23314 * Sets the @attribute to contain the given value, if possible. To unset the
23315 * attribute, use %G_FILE_ATTRIBUTE_TYPE_INVALID for @type.
23320 * g_file_info_set_attribute_boolean:
23321 * @info: a #GFileInfo.
23322 * @attribute: a file attribute key.
23323 * @attr_value: a boolean value.
23325 * Sets the @attribute to contain the given @attr_value,
23331 * g_file_info_set_attribute_byte_string:
23332 * @info: a #GFileInfo.
23333 * @attribute: a file attribute key.
23334 * @attr_value: a byte string.
23336 * Sets the @attribute to contain the given @attr_value,
23342 * g_file_info_set_attribute_int32:
23343 * @info: a #GFileInfo.
23344 * @attribute: a file attribute key.
23345 * @attr_value: a signed 32-bit integer
23347 * Sets the @attribute to contain the given @attr_value,
23353 * g_file_info_set_attribute_int64:
23354 * @info: a #GFileInfo.
23355 * @attribute: attribute name to set.
23356 * @attr_value: int64 value to set attribute to.
23358 * Sets the @attribute to contain the given @attr_value,
23364 * g_file_info_set_attribute_mask:
23365 * @info: a #GFileInfo.
23366 * @mask: a #GFileAttributeMatcher.
23368 * Sets @mask on @info to match specific attribute types.
23373 * g_file_info_set_attribute_object:
23374 * @info: a #GFileInfo.
23375 * @attribute: a file attribute key.
23376 * @attr_value: a #GObject.
23378 * Sets the @attribute to contain the given @attr_value,
23384 * g_file_info_set_attribute_status:
23385 * @info: a #GFileInfo
23386 * @attribute: a file attribute key
23387 * @status: a #GFileAttributeStatus
23389 * Sets the attribute status for an attribute key. This is only
23390 * needed by external code that implement g_file_set_attributes_from_info()
23391 * or similar functions.
23393 * The attribute must exist in @info for this to work. Otherwise %FALSE
23394 * is returned and @info is unchanged.
23396 * Returns: %TRUE if the status was changed, %FALSE if the key was not set.
23402 * g_file_info_set_attribute_string:
23403 * @info: a #GFileInfo.
23404 * @attribute: a file attribute key.
23405 * @attr_value: a UTF-8 string.
23407 * Sets the @attribute to contain the given @attr_value,
23413 * g_file_info_set_attribute_stringv:
23414 * @info: a #GFileInfo.
23415 * @attribute: a file attribute key
23416 * @attr_value: (array zero-terminated=1) (element-type utf8): a %NULL
23417 * terminated array of UTF-8 strings.
23419 * Sets the @attribute to contain the given @attr_value,
23427 * g_file_info_set_attribute_uint32:
23428 * @info: a #GFileInfo.
23429 * @attribute: a file attribute key.
23430 * @attr_value: an unsigned 32-bit integer.
23432 * Sets the @attribute to contain the given @attr_value,
23438 * g_file_info_set_attribute_uint64:
23439 * @info: a #GFileInfo.
23440 * @attribute: a file attribute key.
23441 * @attr_value: an unsigned 64-bit integer.
23443 * Sets the @attribute to contain the given @attr_value,
23449 * g_file_info_set_content_type:
23450 * @info: a #GFileInfo.
23451 * @content_type: a content type. See [GContentType][gio-GContentType]
23453 * Sets the content type attribute for a given #GFileInfo.
23454 * See %G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE.
23459 * g_file_info_set_creation_date_time:
23460 * @info: a #GFileInfo.
23461 * @creation_time: (not nullable): a #GDateTime.
23463 * Sets the %G_FILE_ATTRIBUTE_TIME_CREATED and
23464 * %G_FILE_ATTRIBUTE_TIME_CREATED_USEC attributes in the file info to the
23465 * given date/time value.
23472 * g_file_info_set_display_name:
23473 * @info: a #GFileInfo.
23474 * @display_name: a string containing a display name.
23476 * Sets the display name for the current #GFileInfo.
23477 * See %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME.
23482 * g_file_info_set_edit_name:
23483 * @info: a #GFileInfo.
23484 * @edit_name: a string containing an edit name.
23486 * Sets the edit name for the current file.
23487 * See %G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME.
23492 * g_file_info_set_file_type:
23493 * @info: a #GFileInfo.
23494 * @type: a #GFileType.
23496 * Sets the file type in a #GFileInfo to @type.
23497 * See %G_FILE_ATTRIBUTE_STANDARD_TYPE.
23502 * g_file_info_set_icon:
23503 * @info: a #GFileInfo.
23506 * Sets the icon for a given #GFileInfo.
23507 * See %G_FILE_ATTRIBUTE_STANDARD_ICON.
23512 * g_file_info_set_is_hidden:
23513 * @info: a #GFileInfo.
23514 * @is_hidden: a #gboolean.
23516 * Sets the "is_hidden" attribute in a #GFileInfo according to @is_hidden.
23517 * See %G_FILE_ATTRIBUTE_STANDARD_IS_HIDDEN.
23522 * g_file_info_set_is_symlink:
23523 * @info: a #GFileInfo.
23524 * @is_symlink: a #gboolean.
23526 * Sets the "is_symlink" attribute in a #GFileInfo according to @is_symlink.
23527 * See %G_FILE_ATTRIBUTE_STANDARD_IS_SYMLINK.
23532 * g_file_info_set_modification_date_time:
23533 * @info: a #GFileInfo.
23534 * @mtime: (not nullable): a #GDateTime.
23536 * Sets the %G_FILE_ATTRIBUTE_TIME_MODIFIED and
23537 * %G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC attributes in the file info to the
23538 * given date/time value.
23545 * g_file_info_set_modification_time:
23546 * @info: a #GFileInfo.
23547 * @mtime: a #GTimeVal.
23549 * Sets the %G_FILE_ATTRIBUTE_TIME_MODIFIED and
23550 * %G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC attributes in the file info to the
23551 * given time value.
23553 * Deprecated: 2.62: Use g_file_info_set_modification_date_time() instead, as
23554 * #GTimeVal is deprecated due to the year 2038 problem.
23559 * g_file_info_set_name:
23560 * @info: a #GFileInfo.
23561 * @name: (type filename): a string containing a name.
23563 * Sets the name attribute for the current #GFileInfo.
23564 * See %G_FILE_ATTRIBUTE_STANDARD_NAME.
23569 * g_file_info_set_size:
23570 * @info: a #GFileInfo.
23571 * @size: a #goffset containing the file's size.
23573 * Sets the %G_FILE_ATTRIBUTE_STANDARD_SIZE attribute in the file info
23574 * to the given size.
23579 * g_file_info_set_sort_order:
23580 * @info: a #GFileInfo.
23581 * @sort_order: a sort order integer.
23583 * Sets the sort order attribute in the file info structure. See
23584 * %G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER.
23589 * g_file_info_set_symbolic_icon:
23590 * @info: a #GFileInfo.
23593 * Sets the symbolic icon for a given #GFileInfo.
23594 * See %G_FILE_ATTRIBUTE_STANDARD_SYMBOLIC_ICON.
23601 * g_file_info_set_symlink_target:
23602 * @info: a #GFileInfo.
23603 * @symlink_target: a static string containing a path to a symlink target.
23605 * Sets the %G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET attribute in the file info
23606 * to the given symlink target.
23611 * g_file_info_unset_attribute_mask:
23612 * @info: #GFileInfo.
23614 * Unsets a mask set by g_file_info_set_attribute_mask(), if one
23620 * g_file_input_stream_query_info:
23621 * @stream: a #GFileInputStream.
23622 * @attributes: a file attribute query string.
23623 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
23624 * @error: a #GError location to store the error occurring, or %NULL to
23627 * Queries a file input stream the given @attributes. This function blocks
23628 * while querying the stream. For the asynchronous (non-blocking) version
23629 * of this function, see g_file_input_stream_query_info_async(). While the
23630 * stream is blocked, the stream will set the pending flag internally, and
23631 * any other operations on the stream will fail with %G_IO_ERROR_PENDING.
23633 * Returns: (transfer full): a #GFileInfo, or %NULL on error.
23638 * g_file_input_stream_query_info_async:
23639 * @stream: a #GFileInputStream.
23640 * @attributes: a file attribute query string.
23641 * @io_priority: the [I/O priority][io-priority] of the request
23642 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
23643 * @callback: (scope async): callback to call when the request is satisfied
23644 * @user_data: (closure): the data to pass to callback function
23646 * Queries the stream information asynchronously.
23647 * When the operation is finished @callback will be called.
23648 * You can then call g_file_input_stream_query_info_finish()
23649 * to get the result of the operation.
23651 * For the synchronous version of this function,
23652 * see g_file_input_stream_query_info().
23654 * If @cancellable is not %NULL, then the operation can be cancelled by
23655 * triggering the cancellable object from another thread. If the operation
23656 * was cancelled, the error %G_IO_ERROR_CANCELLED will be set
23661 * g_file_input_stream_query_info_finish:
23662 * @stream: a #GFileInputStream.
23663 * @result: a #GAsyncResult.
23664 * @error: a #GError location to store the error occurring,
23665 * or %NULL to ignore.
23667 * Finishes an asynchronous info query operation.
23669 * Returns: (transfer full): #GFileInfo.
23674 * g_file_io_stream_get_etag:
23675 * @stream: a #GFileIOStream.
23677 * Gets the entity tag for the file when it has been written.
23678 * This must be called after the stream has been written
23679 * and closed, as the etag can change while writing.
23681 * Returns: (nullable) (transfer full): the entity tag for the stream.
23687 * g_file_io_stream_query_info:
23688 * @stream: a #GFileIOStream.
23689 * @attributes: a file attribute query string.
23690 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
23691 * @error: a #GError, %NULL to ignore.
23693 * Queries a file io stream for the given @attributes.
23694 * This function blocks while querying the stream. For the asynchronous
23695 * version of this function, see g_file_io_stream_query_info_async().
23696 * While the stream is blocked, the stream will set the pending flag
23697 * internally, and any other operations on the stream will fail with
23698 * %G_IO_ERROR_PENDING.
23700 * Can fail if the stream was already closed (with @error being set to
23701 * %G_IO_ERROR_CLOSED), the stream has pending operations (with @error being
23702 * set to %G_IO_ERROR_PENDING), or if querying info is not supported for
23703 * the stream's interface (with @error being set to %G_IO_ERROR_NOT_SUPPORTED). I
23704 * all cases of failure, %NULL will be returned.
23706 * If @cancellable is not %NULL, then the operation can be cancelled by
23707 * triggering the cancellable object from another thread. If the operation
23708 * was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %NULL will
23711 * Returns: (transfer full): a #GFileInfo for the @stream, or %NULL on error.
23717 * g_file_io_stream_query_info_async:
23718 * @stream: a #GFileIOStream.
23719 * @attributes: a file attribute query string.
23720 * @io_priority: the [I/O priority][gio-GIOScheduler] of the request
23721 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
23722 * @callback: (scope async): callback to call when the request is satisfied
23723 * @user_data: (closure): the data to pass to callback function
23725 * Asynchronously queries the @stream for a #GFileInfo. When completed,
23726 * @callback will be called with a #GAsyncResult which can be used to
23727 * finish the operation with g_file_io_stream_query_info_finish().
23729 * For the synchronous version of this function, see
23730 * g_file_io_stream_query_info().
23737 * g_file_io_stream_query_info_finish:
23738 * @stream: a #GFileIOStream.
23739 * @result: a #GAsyncResult.
23740 * @error: a #GError, %NULL to ignore.
23742 * Finalizes the asynchronous query started
23743 * by g_file_io_stream_query_info_async().
23745 * Returns: (transfer full): A #GFileInfo for the finished query.
23751 * g_file_is_native:
23752 * @file: input #GFile
23754 * Checks to see if a file is native to the platform.
23756 * A native file is one expressed in the platform-native filename format,
23757 * e.g. "C:\Windows" or "/usr/bin/". This does not mean the file is local,
23758 * as it might be on a locally mounted remote filesystem.
23760 * On some systems non-native files may be available using the native
23761 * filesystem via a userspace filesystem (FUSE), in these cases this call
23762 * will return %FALSE, but g_file_get_path() will still return a native path.
23764 * This call does no blocking I/O.
23766 * Returns: %TRUE if @file is native
23771 * g_file_load_bytes:
23773 * @cancellable: (nullable): a #GCancellable or %NULL
23774 * @etag_out: (out) (nullable) (optional): a location to place the current
23775 * entity tag for the file, or %NULL if the entity tag is not needed
23776 * @error: a location for a #GError or %NULL
23778 * Loads the contents of @file and returns it as #GBytes.
23780 * If @file is a resource:// based URI, the resulting bytes will reference the
23781 * embedded resource instead of a copy. Otherwise, this is equivalent to calling
23782 * g_file_load_contents() and g_bytes_new_take().
23784 * For resources, @etag_out will be set to %NULL.
23786 * The data contained in the resulting #GBytes is always zero-terminated, but
23787 * this is not included in the #GBytes length. The resulting #GBytes should be
23788 * freed with g_bytes_unref() when no longer in use.
23790 * Returns: (transfer full): a #GBytes or %NULL and @error is set
23796 * g_file_load_bytes_async:
23798 * @cancellable: (nullable): a #GCancellable or %NULL
23799 * @callback: (scope async): a #GAsyncReadyCallback to call when the
23800 * request is satisfied
23801 * @user_data: (closure): the data to pass to callback function
23803 * Asynchronously loads the contents of @file as #GBytes.
23805 * If @file is a resource:// based URI, the resulting bytes will reference the
23806 * embedded resource instead of a copy. Otherwise, this is equivalent to calling
23807 * g_file_load_contents_async() and g_bytes_new_take().
23809 * @callback should call g_file_load_bytes_finish() to get the result of this
23810 * asynchronous operation.
23812 * See g_file_load_bytes() for more information.
23819 * g_file_load_bytes_finish:
23821 * @result: a #GAsyncResult provided to the callback
23822 * @etag_out: (out) (nullable) (optional): a location to place the current
23823 * entity tag for the file, or %NULL if the entity tag is not needed
23824 * @error: a location for a #GError, or %NULL
23826 * Completes an asynchronous request to g_file_load_bytes_async().
23828 * For resources, @etag_out will be set to %NULL.
23830 * The data contained in the resulting #GBytes is always zero-terminated, but
23831 * this is not included in the #GBytes length. The resulting #GBytes should be
23832 * freed with g_bytes_unref() when no longer in use.
23834 * See g_file_load_bytes() for more information.
23836 * Returns: (transfer full): a #GBytes or %NULL and @error is set
23842 * g_file_load_contents:
23843 * @file: input #GFile
23844 * @cancellable: optional #GCancellable object, %NULL to ignore
23845 * @contents: (out) (transfer full) (element-type guint8) (array length=length): a location to place the contents of the file
23846 * @length: (out) (optional): a location to place the length of the contents of the file,
23847 * or %NULL if the length is not needed
23848 * @etag_out: (out) (optional) (nullable): a location to place the current entity tag for the file,
23849 * or %NULL if the entity tag is not needed
23850 * @error: a #GError, or %NULL
23852 * Loads the content of the file into memory. The data is always
23853 * zero-terminated, but this is not included in the resultant @length.
23854 * The returned @contents should be freed with g_free() when no longer
23857 * If @cancellable is not %NULL, then the operation can be cancelled by
23858 * triggering the cancellable object from another thread. If the operation
23859 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
23861 * Returns: %TRUE if the @file's contents were successfully loaded.
23862 * %FALSE if there were errors.
23867 * g_file_load_contents_async:
23868 * @file: input #GFile
23869 * @cancellable: optional #GCancellable object, %NULL to ignore
23870 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
23871 * @user_data: the data to pass to callback function
23873 * Starts an asynchronous load of the @file's contents.
23875 * For more details, see g_file_load_contents() which is
23876 * the synchronous version of this call.
23878 * When the load operation has completed, @callback will be called
23879 * with @user data. To finish the operation, call
23880 * g_file_load_contents_finish() with the #GAsyncResult returned by
23883 * If @cancellable is not %NULL, then the operation can be cancelled by
23884 * triggering the cancellable object from another thread. If the operation
23885 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
23890 * g_file_load_contents_finish:
23891 * @file: input #GFile
23892 * @res: a #GAsyncResult
23893 * @contents: (out) (transfer full) (element-type guint8) (array length=length): a location to place the contents of the file
23894 * @length: (out) (optional): a location to place the length of the contents of the file,
23895 * or %NULL if the length is not needed
23896 * @etag_out: (out) (optional) (nullable): a location to place the current entity tag for the file,
23897 * or %NULL if the entity tag is not needed
23898 * @error: a #GError, or %NULL
23900 * Finishes an asynchronous load of the @file's contents.
23901 * The contents are placed in @contents, and @length is set to the
23902 * size of the @contents string. The @contents should be freed with
23903 * g_free() when no longer needed. If @etag_out is present, it will be
23904 * set to the new entity tag for the @file.
23906 * Returns: %TRUE if the load was successful. If %FALSE and @error is
23907 * present, it will be set appropriately.
23912 * g_file_load_partial_contents_async: (skip)
23913 * @file: input #GFile
23914 * @cancellable: optional #GCancellable object, %NULL to ignore
23915 * @read_more_callback: (scope call) (closure user_data): a
23916 * #GFileReadMoreCallback to receive partial data
23917 * and to specify whether further data should be read
23918 * @callback: (scope async) (closure user_data): a #GAsyncReadyCallback to call
23919 * when the request is satisfied
23920 * @user_data: the data to pass to the callback functions
23922 * Reads the partial contents of a file. A #GFileReadMoreCallback should
23923 * be used to stop reading from the file when appropriate, else this
23924 * function will behave exactly as g_file_load_contents_async(). This
23925 * operation can be finished by g_file_load_partial_contents_finish().
23927 * Users of this function should be aware that @user_data is passed to
23928 * both the @read_more_callback and the @callback.
23930 * If @cancellable is not %NULL, then the operation can be cancelled by
23931 * triggering the cancellable object from another thread. If the operation
23932 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
23937 * g_file_load_partial_contents_finish:
23938 * @file: input #GFile
23939 * @res: a #GAsyncResult
23940 * @contents: (out) (transfer full) (element-type guint8) (array length=length): a location to place the contents of the file
23941 * @length: (out) (optional): a location to place the length of the contents of the file,
23942 * or %NULL if the length is not needed
23943 * @etag_out: (out) (optional) (nullable): a location to place the current entity tag for the file,
23944 * or %NULL if the entity tag is not needed
23945 * @error: a #GError, or %NULL
23947 * Finishes an asynchronous partial load operation that was started
23948 * with g_file_load_partial_contents_async(). The data is always
23949 * zero-terminated, but this is not included in the resultant @length.
23950 * The returned @contents should be freed with g_free() when no longer
23953 * Returns: %TRUE if the load was successful. If %FALSE and @error is
23954 * present, it will be set appropriately.
23959 * g_file_make_directory:
23960 * @file: input #GFile
23961 * @cancellable: (nullable): optional #GCancellable object,
23963 * @error: a #GError, or %NULL
23965 * Creates a directory. Note that this will only create a child directory
23966 * of the immediate parent directory of the path or URI given by the #GFile.
23967 * To recursively create directories, see g_file_make_directory_with_parents().
23968 * This function will fail if the parent directory does not exist, setting
23969 * @error to %G_IO_ERROR_NOT_FOUND. If the file system doesn't support
23970 * creating directories, this function will fail, setting @error to
23971 * %G_IO_ERROR_NOT_SUPPORTED.
23973 * For a local #GFile the newly created directory will have the default
23974 * (current) ownership and permissions of the current process.
23976 * If @cancellable is not %NULL, then the operation can be cancelled by
23977 * triggering the cancellable object from another thread. If the operation
23978 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
23980 * Returns: %TRUE on successful creation, %FALSE otherwise.
23985 * g_file_make_directory_async: (virtual make_directory_async)
23986 * @file: input #GFile
23987 * @io_priority: the [I/O priority][io-priority] of the request
23988 * @cancellable: (nullable): optional #GCancellable object,
23990 * @callback: a #GAsyncReadyCallback to call
23991 * when the request is satisfied
23992 * @user_data: the data to pass to callback function
23994 * Asynchronously creates a directory.
24001 * g_file_make_directory_finish: (virtual make_directory_finish)
24002 * @file: input #GFile
24003 * @result: a #GAsyncResult
24004 * @error: a #GError, or %NULL
24006 * Finishes an asynchronous directory creation, started with
24007 * g_file_make_directory_async().
24009 * Returns: %TRUE on successful directory creation, %FALSE otherwise.
24015 * g_file_make_directory_with_parents:
24016 * @file: input #GFile
24017 * @cancellable: (nullable): optional #GCancellable object,
24019 * @error: a #GError, or %NULL
24021 * Creates a directory and any parent directories that may not
24022 * exist similar to 'mkdir -p'. If the file system does not support
24023 * creating directories, this function will fail, setting @error to
24024 * %G_IO_ERROR_NOT_SUPPORTED. If the directory itself already exists,
24025 * this function will fail setting @error to %G_IO_ERROR_EXISTS, unlike
24026 * the similar g_mkdir_with_parents().
24028 * For a local #GFile the newly created directories will have the default
24029 * (current) ownership and permissions of the current process.
24031 * If @cancellable is not %NULL, then the operation can be cancelled by
24032 * triggering the cancellable object from another thread. If the operation
24033 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
24035 * Returns: %TRUE if all directories have been successfully created, %FALSE
24042 * g_file_make_symbolic_link:
24043 * @file: a #GFile with the name of the symlink to create
24044 * @symlink_value: (type filename): a string with the path for the target
24045 * of the new symlink
24046 * @cancellable: (nullable): optional #GCancellable object,
24048 * @error: a #GError
24050 * Creates a symbolic link named @file which contains the string
24053 * If @cancellable is not %NULL, then the operation can be cancelled by
24054 * triggering the cancellable object from another thread. If the operation
24055 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
24057 * Returns: %TRUE on the creation of a new symlink, %FALSE otherwise.
24062 * g_file_measure_disk_usage:
24064 * @flags: #GFileMeasureFlags
24065 * @cancellable: (nullable): optional #GCancellable
24066 * @progress_callback: (nullable): a #GFileMeasureProgressCallback
24067 * @progress_data: user_data for @progress_callback
24068 * @disk_usage: (out) (optional): the number of bytes of disk space used
24069 * @num_dirs: (out) (optional): the number of directories encountered
24070 * @num_files: (out) (optional): the number of non-directories encountered
24071 * @error: (nullable): %NULL, or a pointer to a %NULL #GError pointer
24073 * Recursively measures the disk usage of @file.
24075 * This is essentially an analog of the 'du' command, but it also
24076 * reports the number of directories and non-directory files encountered
24077 * (including things like symbolic links).
24079 * By default, errors are only reported against the toplevel file
24080 * itself. Errors found while recursing are silently ignored, unless
24081 * %G_FILE_MEASURE_REPORT_ANY_ERROR is given in @flags.
24083 * The returned size, @disk_usage, is in bytes and should be formatted
24084 * with g_format_size() in order to get something reasonable for showing
24085 * in a user interface.
24087 * @progress_callback and @progress_data can be given to request
24088 * periodic progress updates while scanning. See the documentation for
24089 * #GFileMeasureProgressCallback for information about when and how the
24090 * callback will be invoked.
24092 * Returns: %TRUE if successful, with the out parameters set.
24093 * %FALSE otherwise, with @error set.
24099 * g_file_measure_disk_usage_async:
24101 * @flags: #GFileMeasureFlags
24102 * @io_priority: the [I/O priority][io-priority] of the request
24103 * @cancellable: (nullable): optional #GCancellable
24104 * @progress_callback: (nullable): a #GFileMeasureProgressCallback
24105 * @progress_data: user_data for @progress_callback
24106 * @callback: (nullable): a #GAsyncReadyCallback to call when complete
24107 * @user_data: the data to pass to callback function
24109 * Recursively measures the disk usage of @file.
24111 * This is the asynchronous version of g_file_measure_disk_usage(). See
24112 * there for more information.
24119 * g_file_measure_disk_usage_finish:
24121 * @result: the #GAsyncResult passed to your #GAsyncReadyCallback
24122 * @disk_usage: (out) (optional): the number of bytes of disk space used
24123 * @num_dirs: (out) (optional): the number of directories encountered
24124 * @num_files: (out) (optional): the number of non-directories encountered
24125 * @error: (nullable): %NULL, or a pointer to a %NULL #GError pointer
24127 * Collects the results from an earlier call to
24128 * g_file_measure_disk_usage_async(). See g_file_measure_disk_usage() for
24129 * more information.
24131 * Returns: %TRUE if successful, with the out parameters set.
24132 * %FALSE otherwise, with @error set.
24139 * @file: input #GFile
24140 * @flags: a set of #GFileMonitorFlags
24141 * @cancellable: (nullable): optional #GCancellable object,
24143 * @error: a #GError, or %NULL
24145 * Obtains a file or directory monitor for the given file,
24146 * depending on the type of the file.
24148 * If @cancellable is not %NULL, then the operation can be cancelled by
24149 * triggering the cancellable object from another thread. If the operation
24150 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
24152 * Returns: (transfer full): a #GFileMonitor for the given @file,
24153 * or %NULL on error.
24154 * Free the returned object with g_object_unref().
24160 * g_file_monitor_cancel:
24161 * @monitor: a #GFileMonitor.
24163 * Cancels a file monitor.
24165 * Returns: always %TRUE
24170 * g_file_monitor_directory: (virtual monitor_dir)
24171 * @file: input #GFile
24172 * @flags: a set of #GFileMonitorFlags
24173 * @cancellable: (nullable): optional #GCancellable object,
24175 * @error: a #GError, or %NULL
24177 * Obtains a directory monitor for the given file.
24178 * This may fail if directory monitoring is not supported.
24180 * If @cancellable is not %NULL, then the operation can be cancelled by
24181 * triggering the cancellable object from another thread. If the operation
24182 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
24184 * It does not make sense for @flags to contain
24185 * %G_FILE_MONITOR_WATCH_HARD_LINKS, since hard links can not be made to
24186 * directories. It is not possible to monitor all the files in a
24187 * directory for changes made via hard links; if you want to do this then
24188 * you must register individual watches with g_file_monitor().
24190 * Returns: (transfer full): a #GFileMonitor for the given @file,
24191 * or %NULL on error.
24192 * Free the returned object with g_object_unref().
24197 * g_file_monitor_emit_event:
24198 * @monitor: a #GFileMonitor.
24199 * @child: a #GFile.
24200 * @other_file: a #GFile.
24201 * @event_type: a set of #GFileMonitorEvent flags.
24203 * Emits the #GFileMonitor::changed signal if a change
24204 * has taken place. Should be called from file monitor
24205 * implementations only.
24207 * Implementations are responsible to call this method from the
24208 * [thread-default main context][g-main-context-push-thread-default] of the
24209 * thread that the monitor was created in.
24214 * g_file_monitor_file:
24215 * @file: input #GFile
24216 * @flags: a set of #GFileMonitorFlags
24217 * @cancellable: (nullable): optional #GCancellable object,
24219 * @error: a #GError, or %NULL
24221 * Obtains a file monitor for the given file. If no file notification
24222 * mechanism exists, then regular polling of the file is used.
24224 * If @cancellable is not %NULL, then the operation can be cancelled by
24225 * triggering the cancellable object from another thread. If the operation
24226 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
24228 * If @flags contains %G_FILE_MONITOR_WATCH_HARD_LINKS then the monitor
24229 * will also attempt to report changes made to the file via another
24230 * filename (ie, a hard link). Without this flag, you can only rely on
24231 * changes made through the filename contained in @file to be
24232 * reported. Using this flag may result in an increase in resource
24233 * usage, and may not have any effect depending on the #GFileMonitor
24234 * backend and/or filesystem type.
24236 * Returns: (transfer full): a #GFileMonitor for the given @file,
24237 * or %NULL on error.
24238 * Free the returned object with g_object_unref().
24243 * g_file_monitor_is_cancelled:
24244 * @monitor: a #GFileMonitor
24246 * Returns whether the monitor is canceled.
24248 * Returns: %TRUE if monitor is canceled. %FALSE otherwise.
24253 * g_file_monitor_set_rate_limit:
24254 * @monitor: a #GFileMonitor.
24255 * @limit_msecs: a non-negative integer with the limit in milliseconds
24256 * to poll for changes
24258 * Sets the rate limit to which the @monitor will report
24259 * consecutive change events to the same file.
24264 * g_file_mount_enclosing_volume:
24265 * @location: input #GFile
24266 * @flags: flags affecting the operation
24267 * @mount_operation: (nullable): a #GMountOperation
24268 * or %NULL to avoid user interaction
24269 * @cancellable: (nullable): optional #GCancellable object,
24271 * @callback: (nullable): a #GAsyncReadyCallback to call
24272 * when the request is satisfied, or %NULL
24273 * @user_data: the data to pass to callback function
24275 * Starts a @mount_operation, mounting the volume that contains
24276 * the file @location.
24278 * When this operation has completed, @callback will be called with
24279 * @user_user data, and the operation can be finalized with
24280 * g_file_mount_enclosing_volume_finish().
24282 * If @cancellable is not %NULL, then the operation can be cancelled by
24283 * triggering the cancellable object from another thread. If the operation
24284 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
24289 * g_file_mount_enclosing_volume_finish:
24290 * @location: input #GFile
24291 * @result: a #GAsyncResult
24292 * @error: a #GError, or %NULL
24294 * Finishes a mount operation started by g_file_mount_enclosing_volume().
24296 * Returns: %TRUE if successful. If an error has occurred,
24297 * this function will return %FALSE and set @error
24298 * appropriately if present.
24303 * g_file_mount_mountable:
24304 * @file: input #GFile
24305 * @flags: flags affecting the operation
24306 * @mount_operation: (nullable): a #GMountOperation,
24307 * or %NULL to avoid user interaction
24308 * @cancellable: (nullable): optional #GCancellable object,
24310 * @callback: (scope async) (nullable): a #GAsyncReadyCallback to call
24311 * when the request is satisfied, or %NULL
24312 * @user_data: (closure): the data to pass to callback function
24314 * Mounts a file of type G_FILE_TYPE_MOUNTABLE.
24315 * Using @mount_operation, you can request callbacks when, for instance,
24316 * passwords are needed during authentication.
24318 * If @cancellable is not %NULL, then the operation can be cancelled by
24319 * triggering the cancellable object from another thread. If the operation
24320 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
24322 * When the operation is finished, @callback will be called.
24323 * You can then call g_file_mount_mountable_finish() to get
24324 * the result of the operation.
24329 * g_file_mount_mountable_finish:
24330 * @file: input #GFile
24331 * @result: a #GAsyncResult
24332 * @error: a #GError, or %NULL
24334 * Finishes a mount operation. See g_file_mount_mountable() for details.
24336 * Finish an asynchronous mount operation that was started
24337 * with g_file_mount_mountable().
24339 * Returns: (transfer full): a #GFile or %NULL on error.
24340 * Free the returned object with g_object_unref().
24346 * @source: #GFile pointing to the source location
24347 * @destination: #GFile pointing to the destination location
24348 * @flags: set of #GFileCopyFlags
24349 * @cancellable: (nullable): optional #GCancellable object,
24351 * @progress_callback: (nullable) (scope call): #GFileProgressCallback
24352 * function for updates
24353 * @progress_callback_data: (closure): gpointer to user data for
24354 * the callback function
24355 * @error: #GError for returning error conditions, or %NULL
24357 * Tries to move the file or directory @source to the location specified
24358 * by @destination. If native move operations are supported then this is
24359 * used, otherwise a copy + delete fallback is used. The native
24360 * implementation may support moving directories (for instance on moves
24361 * inside the same filesystem), but the fallback code does not.
24363 * If the flag #G_FILE_COPY_OVERWRITE is specified an already
24364 * existing @destination file is overwritten.
24366 * If @cancellable is not %NULL, then the operation can be cancelled by
24367 * triggering the cancellable object from another thread. If the operation
24368 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
24370 * If @progress_callback is not %NULL, then the operation can be monitored
24371 * by setting this to a #GFileProgressCallback function.
24372 * @progress_callback_data will be passed to this function. It is
24373 * guaranteed that this callback will be called after all data has been
24374 * transferred with the total number of bytes copied during the operation.
24376 * If the @source file does not exist, then the %G_IO_ERROR_NOT_FOUND
24377 * error is returned, independent on the status of the @destination.
24379 * If #G_FILE_COPY_OVERWRITE is not specified and the target exists,
24380 * then the error %G_IO_ERROR_EXISTS is returned.
24382 * If trying to overwrite a file over a directory, the %G_IO_ERROR_IS_DIRECTORY
24383 * error is returned. If trying to overwrite a directory with a directory the
24384 * %G_IO_ERROR_WOULD_MERGE error is returned.
24386 * If the source is a directory and the target does not exist, or
24387 * #G_FILE_COPY_OVERWRITE is specified and the target is a file, then
24388 * the %G_IO_ERROR_WOULD_RECURSE error may be returned (if the native
24389 * move operation isn't available).
24391 * Returns: %TRUE on successful move, %FALSE otherwise.
24396 * g_file_new_build_filename:
24397 * @first_element: (type filename): the first element in the path
24398 * @...: remaining elements in path, terminated by %NULL
24400 * Constructs a #GFile from a series of elements using the correct
24401 * separator for filenames.
24403 * Using this function is equivalent to calling g_build_filename(),
24404 * followed by g_file_new_for_path() on the result.
24406 * Returns: (transfer full): a new #GFile
24412 * g_file_new_for_commandline_arg:
24413 * @arg: (type filename): a command line string
24415 * Creates a #GFile with the given argument from the command line.
24416 * The value of @arg can be either a URI, an absolute path or a
24417 * relative path resolved relative to the current working directory.
24418 * This operation never fails, but the returned object might not
24419 * support any I/O operation if @arg points to a malformed path.
24421 * Note that on Windows, this function expects its argument to be in
24422 * UTF-8 -- not the system code page. This means that you
24423 * should not use this function with string from argv as it is passed
24424 * to main(). g_win32_get_command_line() will return a UTF-8 version of
24425 * the commandline. #GApplication also uses UTF-8 but
24426 * g_application_command_line_create_file_for_arg() may be more useful
24427 * for you there. It is also always possible to use this function with
24428 * #GOptionContext arguments of type %G_OPTION_ARG_FILENAME.
24430 * Returns: (transfer full): a new #GFile.
24431 * Free the returned object with g_object_unref().
24436 * g_file_new_for_commandline_arg_and_cwd:
24437 * @arg: (type filename): a command line string
24438 * @cwd: (type filename): the current working directory of the commandline
24440 * Creates a #GFile with the given argument from the command line.
24442 * This function is similar to g_file_new_for_commandline_arg() except
24443 * that it allows for passing the current working directory as an
24444 * argument instead of using the current working directory of the
24447 * This is useful if the commandline argument was given in a context
24448 * other than the invocation of the current process.
24450 * See also g_application_command_line_create_file_for_arg().
24452 * Returns: (transfer full): a new #GFile
24458 * g_file_new_for_path:
24459 * @path: (type filename): a string containing a relative or absolute path.
24460 * The string must be encoded in the glib filename encoding.
24462 * Constructs a #GFile for a given path. This operation never
24463 * fails, but the returned object might not support any I/O
24464 * operation if @path is malformed.
24466 * Returns: (transfer full): a new #GFile for the given @path.
24467 * Free the returned object with g_object_unref().
24472 * g_file_new_for_uri:
24473 * @uri: a UTF-8 string containing a URI
24475 * Constructs a #GFile for a given URI. This operation never
24476 * fails, but the returned object might not support any I/O
24477 * operation if @uri is malformed or if the uri type is
24480 * Returns: (transfer full): a new #GFile for the given @uri.
24481 * Free the returned object with g_object_unref().
24487 * @tmpl: (type filename) (nullable): Template for the file
24488 * name, as in g_file_open_tmp(), or %NULL for a default template
24489 * @iostream: (out): on return, a #GFileIOStream for the created file
24490 * @error: a #GError, or %NULL
24492 * Opens a file in the preferred directory for temporary files (as
24493 * returned by g_get_tmp_dir()) and returns a #GFile and
24494 * #GFileIOStream pointing to it.
24496 * @tmpl should be a string in the GLib file name encoding
24497 * containing a sequence of six 'X' characters, and containing no
24498 * directory components. If it is %NULL, a default template is used.
24500 * Unlike the other #GFile constructors, this will return %NULL if
24501 * a temporary file could not be created.
24503 * Returns: (transfer full): a new #GFile.
24504 * Free the returned object with g_object_unref().
24510 * g_file_open_readwrite:
24511 * @file: #GFile to open
24512 * @cancellable: (nullable): a #GCancellable
24513 * @error: a #GError, or %NULL
24515 * Opens an existing file for reading and writing. The result is
24516 * a #GFileIOStream that can be used to read and write the contents
24519 * If @cancellable is not %NULL, then the operation can be cancelled
24520 * by triggering the cancellable object from another thread. If the
24521 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
24524 * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will
24525 * be returned. If the file is a directory, the %G_IO_ERROR_IS_DIRECTORY
24526 * error will be returned. Other errors are possible too, and depend on
24527 * what kind of filesystem the file is on. Note that in many non-local
24528 * file cases read and write streams are not supported, so make sure you
24529 * really need to do read and write streaming, rather than just opening
24530 * for reading or writing.
24532 * Returns: (transfer full): #GFileIOStream or %NULL on error.
24533 * Free the returned object with g_object_unref().
24539 * g_file_open_readwrite_async:
24540 * @file: input #GFile
24541 * @io_priority: the [I/O priority][io-priority] of the request
24542 * @cancellable: (nullable): optional #GCancellable object,
24544 * @callback: (scope async): a #GAsyncReadyCallback to call
24545 * when the request is satisfied
24546 * @user_data: (closure): the data to pass to callback function
24548 * Asynchronously opens @file for reading and writing.
24550 * For more details, see g_file_open_readwrite() which is
24551 * the synchronous version of this call.
24553 * When the operation is finished, @callback will be called.
24554 * You can then call g_file_open_readwrite_finish() to get
24555 * the result of the operation.
24562 * g_file_open_readwrite_finish:
24563 * @file: input #GFile
24564 * @res: a #GAsyncResult
24565 * @error: a #GError, or %NULL
24567 * Finishes an asynchronous file read operation started with
24568 * g_file_open_readwrite_async().
24570 * Returns: (transfer full): a #GFileIOStream or %NULL on error.
24571 * Free the returned object with g_object_unref().
24577 * g_file_output_stream_get_etag:
24578 * @stream: a #GFileOutputStream.
24580 * Gets the entity tag for the file when it has been written.
24581 * This must be called after the stream has been written
24582 * and closed, as the etag can change while writing.
24584 * Returns: (nullable) (transfer full): the entity tag for the stream.
24589 * g_file_output_stream_query_info:
24590 * @stream: a #GFileOutputStream.
24591 * @attributes: a file attribute query string.
24592 * @cancellable: optional #GCancellable object, %NULL to ignore.
24593 * @error: a #GError, %NULL to ignore.
24595 * Queries a file output stream for the given @attributes.
24596 * This function blocks while querying the stream. For the asynchronous
24597 * version of this function, see g_file_output_stream_query_info_async().
24598 * While the stream is blocked, the stream will set the pending flag
24599 * internally, and any other operations on the stream will fail with
24600 * %G_IO_ERROR_PENDING.
24602 * Can fail if the stream was already closed (with @error being set to
24603 * %G_IO_ERROR_CLOSED), the stream has pending operations (with @error being
24604 * set to %G_IO_ERROR_PENDING), or if querying info is not supported for
24605 * the stream's interface (with @error being set to %G_IO_ERROR_NOT_SUPPORTED). In
24606 * all cases of failure, %NULL will be returned.
24608 * If @cancellable is not %NULL, then the operation can be cancelled by
24609 * triggering the cancellable object from another thread. If the operation
24610 * was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %NULL will
24613 * Returns: (transfer full): a #GFileInfo for the @stream, or %NULL on error.
24618 * g_file_output_stream_query_info_async:
24619 * @stream: a #GFileOutputStream.
24620 * @attributes: a file attribute query string.
24621 * @io_priority: the [I/O priority][gio-GIOScheduler] of the request
24622 * @cancellable: optional #GCancellable object, %NULL to ignore.
24623 * @callback: callback to call when the request is satisfied
24624 * @user_data: the data to pass to callback function
24626 * Asynchronously queries the @stream for a #GFileInfo. When completed,
24627 * @callback will be called with a #GAsyncResult which can be used to
24628 * finish the operation with g_file_output_stream_query_info_finish().
24630 * For the synchronous version of this function, see
24631 * g_file_output_stream_query_info().
24636 * g_file_output_stream_query_info_finish:
24637 * @stream: a #GFileOutputStream.
24638 * @result: a #GAsyncResult.
24639 * @error: a #GError, %NULL to ignore.
24641 * Finalizes the asynchronous query started
24642 * by g_file_output_stream_query_info_async().
24644 * Returns: (transfer full): A #GFileInfo for the finished query.
24649 * g_file_parse_name:
24650 * @parse_name: a file name or path to be parsed
24652 * Constructs a #GFile with the given @parse_name (i.e. something
24653 * given by g_file_get_parse_name()). This operation never fails,
24654 * but the returned object might not support any I/O operation if
24655 * the @parse_name cannot be parsed.
24657 * Returns: (transfer full): a new #GFile.
24662 * g_file_peek_path:
24663 * @file: input #GFile
24665 * Exactly like g_file_get_path(), but caches the result via
24666 * g_object_set_qdata_full(). This is useful for example in C
24667 * applications which mix `g_file_*` APIs with native ones. It
24668 * also avoids an extra duplicated string when possible, so will be
24669 * generally more efficient.
24671 * This call does no blocking I/O.
24673 * Returns: (type filename) (nullable): string containing the #GFile's path,
24674 * or %NULL if no such path exists. The returned string is owned by @file.
24680 * g_file_poll_mountable:
24681 * @file: input #GFile
24682 * @cancellable: optional #GCancellable object, %NULL to ignore
24683 * @callback: (nullable): a #GAsyncReadyCallback to call
24684 * when the request is satisfied, or %NULL
24685 * @user_data: the data to pass to callback function
24687 * Polls a file of type #G_FILE_TYPE_MOUNTABLE.
24689 * If @cancellable is not %NULL, then the operation can be cancelled by
24690 * triggering the cancellable object from another thread. If the operation
24691 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
24693 * When the operation is finished, @callback will be called.
24694 * You can then call g_file_mount_mountable_finish() to get
24695 * the result of the operation.
24702 * g_file_poll_mountable_finish:
24703 * @file: input #GFile
24704 * @result: a #GAsyncResult
24705 * @error: a #GError, or %NULL
24707 * Finishes a poll operation. See g_file_poll_mountable() for details.
24709 * Finish an asynchronous poll operation that was polled
24710 * with g_file_poll_mountable().
24712 * Returns: %TRUE if the operation finished successfully. %FALSE
24719 * g_file_query_default_handler:
24720 * @file: a #GFile to open
24721 * @cancellable: optional #GCancellable object, %NULL to ignore
24722 * @error: a #GError, or %NULL
24724 * Returns the #GAppInfo that is registered as the default
24725 * application to handle the file specified by @file.
24727 * If @cancellable is not %NULL, then the operation can be cancelled by
24728 * triggering the cancellable object from another thread. If the operation
24729 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
24731 * Returns: (transfer full): a #GAppInfo if the handle was found,
24732 * %NULL if there were errors.
24733 * When you are done with it, release it with g_object_unref()
24738 * g_file_query_default_handler_async:
24739 * @file: a #GFile to open
24740 * @io_priority: the [I/O priority][io-priority] of the request
24741 * @cancellable: optional #GCancellable object, %NULL to ignore
24742 * @callback: (nullable): a #GAsyncReadyCallback to call when the request is done
24743 * @user_data: (nullable): data to pass to @callback
24745 * Async version of g_file_query_default_handler().
24752 * g_file_query_default_handler_finish:
24753 * @file: a #GFile to open
24754 * @result: a #GAsyncResult
24755 * @error: (nullable): a #GError
24757 * Finishes a g_file_query_default_handler_async() operation.
24759 * Returns: (transfer full): a #GAppInfo if the handle was found,
24760 * %NULL if there were errors.
24761 * When you are done with it, release it with g_object_unref()
24767 * g_file_query_exists:
24768 * @file: input #GFile
24769 * @cancellable: (nullable): optional #GCancellable object,
24772 * Utility function to check if a particular file exists. This is
24773 * implemented using g_file_query_info() and as such does blocking I/O.
24775 * Note that in many cases it is [racy to first check for file existence](https://en.wikipedia.org/wiki/Time_of_check_to_time_of_use)
24776 * and then execute something based on the outcome of that, because the
24777 * file might have been created or removed in between the operations. The
24778 * general approach to handling that is to not check, but just do the
24779 * operation and handle the errors as they come.
24781 * As an example of race-free checking, take the case of reading a file,
24782 * and if it doesn't exist, creating it. There are two racy versions: read
24783 * it, and on error create it; and: check if it exists, if not create it.
24784 * These can both result in two processes creating the file (with perhaps
24785 * a partially written file as the result). The correct approach is to
24786 * always try to create the file with g_file_create() which will either
24787 * atomically create the file or fail with a %G_IO_ERROR_EXISTS error.
24789 * However, in many cases an existence check is useful in a user interface,
24790 * for instance to make a menu item sensitive/insensitive, so that you don't
24791 * have to fool users that something is possible and then just show an error
24792 * dialog. If you do this, you should make sure to also handle the errors
24793 * that can happen due to races when you execute the operation.
24795 * Returns: %TRUE if the file exists (and can be detected without error),
24796 * %FALSE otherwise (or if cancelled).
24801 * g_file_query_file_type:
24802 * @file: input #GFile
24803 * @flags: a set of #GFileQueryInfoFlags passed to g_file_query_info()
24804 * @cancellable: (nullable): optional #GCancellable object,
24807 * Utility function to inspect the #GFileType of a file. This is
24808 * implemented using g_file_query_info() and as such does blocking I/O.
24810 * The primary use case of this method is to check if a file is
24811 * a regular file, directory, or symlink.
24813 * Returns: The #GFileType of the file and #G_FILE_TYPE_UNKNOWN
24814 * if the file does not exist
24820 * g_file_query_filesystem_info:
24821 * @file: input #GFile
24822 * @attributes: an attribute query string
24823 * @cancellable: (nullable): optional #GCancellable object,
24825 * @error: a #GError
24827 * Similar to g_file_query_info(), but obtains information
24828 * about the filesystem the @file is on, rather than the file itself.
24829 * For instance the amount of space available and the type of
24832 * The @attributes value is a string that specifies the attributes
24833 * that should be gathered. It is not an error if it's not possible
24834 * to read a particular requested attribute from a file - it just
24835 * won't be set. @attributes should be a comma-separated list of
24836 * attributes or attribute wildcards. The wildcard "*" means all
24837 * attributes, and a wildcard like "filesystem::*" means all attributes
24838 * in the filesystem namespace. The standard namespace for filesystem
24839 * attributes is "filesystem". Common attributes of interest are
24840 * #G_FILE_ATTRIBUTE_FILESYSTEM_SIZE (the total size of the filesystem
24841 * in bytes), #G_FILE_ATTRIBUTE_FILESYSTEM_FREE (number of bytes available),
24842 * and #G_FILE_ATTRIBUTE_FILESYSTEM_TYPE (type of the filesystem).
24844 * If @cancellable is not %NULL, then the operation can be cancelled
24845 * by triggering the cancellable object from another thread. If the
24846 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
24849 * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will
24850 * be returned. Other errors are possible too, and depend on what
24851 * kind of filesystem the file is on.
24853 * Returns: (transfer full): a #GFileInfo or %NULL if there was an error.
24854 * Free the returned object with g_object_unref().
24859 * g_file_query_filesystem_info_async:
24860 * @file: input #GFile
24861 * @attributes: an attribute query string
24862 * @io_priority: the [I/O priority][io-priority] of the request
24863 * @cancellable: (nullable): optional #GCancellable object,
24865 * @callback: (scope async): a #GAsyncReadyCallback to call
24866 * when the request is satisfied
24867 * @user_data: (closure): the data to pass to callback function
24869 * Asynchronously gets the requested information about the filesystem
24870 * that the specified @file is on. The result is a #GFileInfo object
24871 * that contains key-value attributes (such as type or size for the
24874 * For more details, see g_file_query_filesystem_info() which is the
24875 * synchronous version of this call.
24877 * When the operation is finished, @callback will be called. You can
24878 * then call g_file_query_info_finish() to get the result of the
24884 * g_file_query_filesystem_info_finish:
24885 * @file: input #GFile
24886 * @res: a #GAsyncResult
24887 * @error: a #GError
24889 * Finishes an asynchronous filesystem info query.
24890 * See g_file_query_filesystem_info_async().
24892 * Returns: (transfer full): #GFileInfo for given @file
24893 * or %NULL on error.
24894 * Free the returned object with g_object_unref().
24899 * g_file_query_info:
24900 * @file: input #GFile
24901 * @attributes: an attribute query string
24902 * @flags: a set of #GFileQueryInfoFlags
24903 * @cancellable: (nullable): optional #GCancellable object,
24905 * @error: a #GError
24907 * Gets the requested information about specified @file.
24908 * The result is a #GFileInfo object that contains key-value
24909 * attributes (such as the type or size of the file).
24911 * The @attributes value is a string that specifies the file
24912 * attributes that should be gathered. It is not an error if
24913 * it's not possible to read a particular requested attribute
24914 * from a file - it just won't be set. @attributes should be a
24915 * comma-separated list of attributes or attribute wildcards.
24916 * The wildcard "*" means all attributes, and a wildcard like
24917 * "standard::*" means all attributes in the standard namespace.
24918 * An example attribute query be "standard::*,owner::user".
24919 * The standard attributes are available as defines, like
24920 * #G_FILE_ATTRIBUTE_STANDARD_NAME.
24922 * If @cancellable is not %NULL, then the operation can be cancelled
24923 * by triggering the cancellable object from another thread. If the
24924 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
24927 * For symlinks, normally the information about the target of the
24928 * symlink is returned, rather than information about the symlink
24929 * itself. However if you pass #G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS
24930 * in @flags the information about the symlink itself will be returned.
24931 * Also, for symlinks that point to non-existing files the information
24932 * about the symlink itself will be returned.
24934 * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will be
24935 * returned. Other errors are possible too, and depend on what kind of
24936 * filesystem the file is on.
24938 * Returns: (transfer full): a #GFileInfo for the given @file, or %NULL
24939 * on error. Free the returned object with g_object_unref().
24944 * g_file_query_info_async:
24945 * @file: input #GFile
24946 * @attributes: an attribute query string
24947 * @flags: a set of #GFileQueryInfoFlags
24948 * @io_priority: the [I/O priority][io-priority] of the request
24949 * @cancellable: (nullable): optional #GCancellable object,
24951 * @callback: (scope async): a #GAsyncReadyCallback to call when the
24952 * request is satisfied
24953 * @user_data: (closure): the data to pass to callback function
24955 * Asynchronously gets the requested information about specified @file.
24956 * The result is a #GFileInfo object that contains key-value attributes
24957 * (such as type or size for the file).
24959 * For more details, see g_file_query_info() which is the synchronous
24960 * version of this call.
24962 * When the operation is finished, @callback will be called. You can
24963 * then call g_file_query_info_finish() to get the result of the operation.
24968 * g_file_query_info_finish:
24969 * @file: input #GFile
24970 * @res: a #GAsyncResult
24971 * @error: a #GError
24973 * Finishes an asynchronous file info query.
24974 * See g_file_query_info_async().
24976 * Returns: (transfer full): #GFileInfo for given @file
24977 * or %NULL on error. Free the returned object with
24978 * g_object_unref().
24983 * g_file_query_settable_attributes:
24984 * @file: input #GFile
24985 * @cancellable: (nullable): optional #GCancellable object,
24987 * @error: a #GError, or %NULL
24989 * Obtain the list of settable attributes for the file.
24991 * Returns the type and full attribute name of all the attributes
24992 * that can be set on this file. This doesn't mean setting it will
24993 * always succeed though, you might get an access failure, or some
24994 * specific file may not support a specific attribute.
24996 * If @cancellable is not %NULL, then the operation can be cancelled by
24997 * triggering the cancellable object from another thread. If the operation
24998 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
25000 * Returns: a #GFileAttributeInfoList describing the settable attributes.
25001 * When you are done with it, release it with
25002 * g_file_attribute_info_list_unref()
25007 * g_file_query_writable_namespaces:
25008 * @file: input #GFile
25009 * @cancellable: (nullable): optional #GCancellable object,
25011 * @error: a #GError, or %NULL
25013 * Obtain the list of attribute namespaces where new attributes
25014 * can be created by a user. An example of this is extended
25015 * attributes (in the "xattr" namespace).
25017 * If @cancellable is not %NULL, then the operation can be cancelled by
25018 * triggering the cancellable object from another thread. If the operation
25019 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
25021 * Returns: a #GFileAttributeInfoList describing the writable namespaces.
25022 * When you are done with it, release it with
25023 * g_file_attribute_info_list_unref()
25028 * g_file_read: (virtual read_fn)
25029 * @file: #GFile to read
25030 * @cancellable: (nullable): a #GCancellable
25031 * @error: a #GError, or %NULL
25033 * Opens a file for reading. The result is a #GFileInputStream that
25034 * can be used to read the contents of the file.
25036 * If @cancellable is not %NULL, then the operation can be cancelled by
25037 * triggering the cancellable object from another thread. If the operation
25038 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
25040 * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will be
25041 * returned. If the file is a directory, the %G_IO_ERROR_IS_DIRECTORY
25042 * error will be returned. Other errors are possible too, and depend
25043 * on what kind of filesystem the file is on.
25045 * Returns: (transfer full): #GFileInputStream or %NULL on error.
25046 * Free the returned object with g_object_unref().
25051 * g_file_read_async:
25052 * @file: input #GFile
25053 * @io_priority: the [I/O priority][io-priority] of the request
25054 * @cancellable: (nullable): optional #GCancellable object,
25056 * @callback: (scope async): a #GAsyncReadyCallback to call
25057 * when the request is satisfied
25058 * @user_data: (closure): the data to pass to callback function
25060 * Asynchronously opens @file for reading.
25062 * For more details, see g_file_read() which is
25063 * the synchronous version of this call.
25065 * When the operation is finished, @callback will be called.
25066 * You can then call g_file_read_finish() to get the result
25067 * of the operation.
25072 * g_file_read_finish:
25073 * @file: input #GFile
25074 * @res: a #GAsyncResult
25075 * @error: a #GError, or %NULL
25077 * Finishes an asynchronous file read operation started with
25078 * g_file_read_async().
25080 * Returns: (transfer full): a #GFileInputStream or %NULL on error.
25081 * Free the returned object with g_object_unref().
25087 * @file: input #GFile
25088 * @etag: (nullable): an optional [entity tag][gfile-etag]
25089 * for the current #GFile, or #NULL to ignore
25090 * @make_backup: %TRUE if a backup should be created
25091 * @flags: a set of #GFileCreateFlags
25092 * @cancellable: (nullable): optional #GCancellable object,
25094 * @error: a #GError, or %NULL
25096 * Returns an output stream for overwriting the file, possibly
25097 * creating a backup copy of the file first. If the file doesn't exist,
25098 * it will be created.
25100 * This will try to replace the file in the safest way possible so
25101 * that any errors during the writing will not affect an already
25102 * existing copy of the file. For instance, for local files it
25103 * may write to a temporary file and then atomically rename over
25104 * the destination when the stream is closed.
25106 * By default files created are generally readable by everyone,
25107 * but if you pass #G_FILE_CREATE_PRIVATE in @flags the file
25108 * will be made readable only to the current user, to the level that
25109 * is supported on the target filesystem.
25111 * If @cancellable is not %NULL, then the operation can be cancelled
25112 * by triggering the cancellable object from another thread. If the
25113 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
25116 * If you pass in a non-%NULL @etag value and @file already exists, then
25117 * this value is compared to the current entity tag of the file, and if
25118 * they differ an %G_IO_ERROR_WRONG_ETAG error is returned. This
25119 * generally means that the file has been changed since you last read
25120 * it. You can get the new etag from g_file_output_stream_get_etag()
25121 * after you've finished writing and closed the #GFileOutputStream. When
25122 * you load a new file you can use g_file_input_stream_query_info() to
25123 * get the etag of the file.
25125 * If @make_backup is %TRUE, this function will attempt to make a
25126 * backup of the current file before overwriting it. If this fails
25127 * a %G_IO_ERROR_CANT_CREATE_BACKUP error will be returned. If you
25128 * want to replace anyway, try again with @make_backup set to %FALSE.
25130 * If the file is a directory the %G_IO_ERROR_IS_DIRECTORY error will
25131 * be returned, and if the file is some other form of non-regular file
25132 * then a %G_IO_ERROR_NOT_REGULAR_FILE error will be returned. Some
25133 * file systems don't allow all file names, and may return an
25134 * %G_IO_ERROR_INVALID_FILENAME error, and if the name is to long
25135 * %G_IO_ERROR_FILENAME_TOO_LONG will be returned. Other errors are
25136 * possible too, and depend on what kind of filesystem the file is on.
25138 * Returns: (transfer full): a #GFileOutputStream or %NULL on error.
25139 * Free the returned object with g_object_unref().
25144 * g_file_replace_async:
25145 * @file: input #GFile
25146 * @etag: (nullable): an [entity tag][gfile-etag] for the current #GFile,
25147 * or %NULL to ignore
25148 * @make_backup: %TRUE if a backup should be created
25149 * @flags: a set of #GFileCreateFlags
25150 * @io_priority: the [I/O priority][io-priority] of the request
25151 * @cancellable: (nullable): optional #GCancellable object,
25153 * @callback: (scope async): a #GAsyncReadyCallback to call
25154 * when the request is satisfied
25155 * @user_data: (closure): the data to pass to callback function
25157 * Asynchronously overwrites the file, replacing the contents,
25158 * possibly creating a backup copy of the file first.
25160 * For more details, see g_file_replace() which is
25161 * the synchronous version of this call.
25163 * When the operation is finished, @callback will be called.
25164 * You can then call g_file_replace_finish() to get the result
25165 * of the operation.
25170 * g_file_replace_contents:
25171 * @file: input #GFile
25172 * @contents: (element-type guint8) (array length=length): a string containing the new contents for @file
25173 * @length: the length of @contents in bytes
25174 * @etag: (nullable): the old [entity-tag][gfile-etag] for the document,
25176 * @make_backup: %TRUE if a backup should be created
25177 * @flags: a set of #GFileCreateFlags
25178 * @new_etag: (out) (optional) (nullable): a location to a new [entity tag][gfile-etag]
25179 * for the document. This should be freed with g_free() when no longer
25181 * @cancellable: optional #GCancellable object, %NULL to ignore
25182 * @error: a #GError, or %NULL
25184 * Replaces the contents of @file with @contents of @length bytes.
25186 * If @etag is specified (not %NULL), any existing file must have that etag,
25187 * or the error %G_IO_ERROR_WRONG_ETAG will be returned.
25189 * If @make_backup is %TRUE, this function will attempt to make a backup
25190 * of @file. Internally, it uses g_file_replace(), so will try to replace the
25191 * file contents in the safest way possible. For example, atomic renames are
25192 * used when replacing local files’ contents.
25194 * If @cancellable is not %NULL, then the operation can be cancelled by
25195 * triggering the cancellable object from another thread. If the operation
25196 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
25198 * The returned @new_etag can be used to verify that the file hasn't
25199 * changed the next time it is saved over.
25201 * Returns: %TRUE if successful. If an error has occurred, this function
25202 * will return %FALSE and set @error appropriately if present.
25207 * g_file_replace_contents_async:
25208 * @file: input #GFile
25209 * @contents: (element-type guint8) (array length=length): string of contents to replace the file with
25210 * @length: the length of @contents in bytes
25211 * @etag: (nullable): a new [entity tag][gfile-etag] for the @file, or %NULL
25212 * @make_backup: %TRUE if a backup should be created
25213 * @flags: a set of #GFileCreateFlags
25214 * @cancellable: optional #GCancellable object, %NULL to ignore
25215 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
25216 * @user_data: the data to pass to callback function
25218 * Starts an asynchronous replacement of @file with the given
25219 * @contents of @length bytes. @etag will replace the document's
25220 * current entity tag.
25222 * When this operation has completed, @callback will be called with
25223 * @user_user data, and the operation can be finalized with
25224 * g_file_replace_contents_finish().
25226 * If @cancellable is not %NULL, then the operation can be cancelled by
25227 * triggering the cancellable object from another thread. If the operation
25228 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
25230 * If @make_backup is %TRUE, this function will attempt to
25231 * make a backup of @file.
25233 * Note that no copy of @contents will be made, so it must stay valid
25234 * until @callback is called. See g_file_replace_contents_bytes_async()
25235 * for a #GBytes version that will automatically hold a reference to the
25236 * contents (without copying) for the duration of the call.
25241 * g_file_replace_contents_bytes_async:
25242 * @file: input #GFile
25243 * @contents: a #GBytes
25244 * @etag: (nullable): a new [entity tag][gfile-etag] for the @file, or %NULL
25245 * @make_backup: %TRUE if a backup should be created
25246 * @flags: a set of #GFileCreateFlags
25247 * @cancellable: optional #GCancellable object, %NULL to ignore
25248 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
25249 * @user_data: the data to pass to callback function
25251 * Same as g_file_replace_contents_async() but takes a #GBytes input instead.
25252 * This function will keep a ref on @contents until the operation is done.
25253 * Unlike g_file_replace_contents_async() this allows forgetting about the
25254 * content without waiting for the callback.
25256 * When this operation has completed, @callback will be called with
25257 * @user_user data, and the operation can be finalized with
25258 * g_file_replace_contents_finish().
25265 * g_file_replace_contents_finish:
25266 * @file: input #GFile
25267 * @res: a #GAsyncResult
25268 * @new_etag: (out) (optional) (nullable): a location of a new [entity tag][gfile-etag]
25269 * for the document. This should be freed with g_free() when it is no
25270 * longer needed, or %NULL
25271 * @error: a #GError, or %NULL
25273 * Finishes an asynchronous replace of the given @file. See
25274 * g_file_replace_contents_async(). Sets @new_etag to the new entity
25275 * tag for the document, if present.
25277 * Returns: %TRUE on success, %FALSE on failure.
25282 * g_file_replace_finish:
25283 * @file: input #GFile
25284 * @res: a #GAsyncResult
25285 * @error: a #GError, or %NULL
25287 * Finishes an asynchronous file replace operation started with
25288 * g_file_replace_async().
25290 * Returns: (transfer full): a #GFileOutputStream, or %NULL on error.
25291 * Free the returned object with g_object_unref().
25296 * g_file_replace_readwrite:
25298 * @etag: (nullable): an optional [entity tag][gfile-etag]
25299 * for the current #GFile, or #NULL to ignore
25300 * @make_backup: %TRUE if a backup should be created
25301 * @flags: a set of #GFileCreateFlags
25302 * @cancellable: (nullable): optional #GCancellable object,
25304 * @error: return location for a #GError, or %NULL
25306 * Returns an output stream for overwriting the file in readwrite mode,
25307 * possibly creating a backup copy of the file first. If the file doesn't
25308 * exist, it will be created.
25310 * For details about the behaviour, see g_file_replace() which does the
25311 * same thing but returns an output stream only.
25313 * Note that in many non-local file cases read and write streams are not
25314 * supported, so make sure you really need to do read and write streaming,
25315 * rather than just opening for reading or writing.
25317 * Returns: (transfer full): a #GFileIOStream or %NULL on error.
25318 * Free the returned object with g_object_unref().
25324 * g_file_replace_readwrite_async:
25325 * @file: input #GFile
25326 * @etag: (nullable): an [entity tag][gfile-etag] for the current #GFile,
25327 * or %NULL to ignore
25328 * @make_backup: %TRUE if a backup should be created
25329 * @flags: a set of #GFileCreateFlags
25330 * @io_priority: the [I/O priority][io-priority] of the request
25331 * @cancellable: (nullable): optional #GCancellable object,
25333 * @callback: (scope async): a #GAsyncReadyCallback to call
25334 * when the request is satisfied
25335 * @user_data: (closure): the data to pass to callback function
25337 * Asynchronously overwrites the file in read-write mode,
25338 * replacing the contents, possibly creating a backup copy
25339 * of the file first.
25341 * For more details, see g_file_replace_readwrite() which is
25342 * the synchronous version of this call.
25344 * When the operation is finished, @callback will be called.
25345 * You can then call g_file_replace_readwrite_finish() to get
25346 * the result of the operation.
25353 * g_file_replace_readwrite_finish:
25354 * @file: input #GFile
25355 * @res: a #GAsyncResult
25356 * @error: a #GError, or %NULL
25358 * Finishes an asynchronous file replace operation started with
25359 * g_file_replace_readwrite_async().
25361 * Returns: (transfer full): a #GFileIOStream, or %NULL on error.
25362 * Free the returned object with g_object_unref().
25368 * g_file_resolve_relative_path:
25369 * @file: input #GFile
25370 * @relative_path: (type filename): a given relative path string
25372 * Resolves a relative path for @file to an absolute path.
25374 * This call does no blocking I/O.
25376 * Returns: (transfer full): #GFile to the resolved path.
25377 * %NULL if @relative_path is %NULL or if @file is invalid.
25378 * Free the returned object with g_object_unref().
25383 * g_file_set_attribute:
25384 * @file: input #GFile
25385 * @attribute: a string containing the attribute's name
25386 * @type: The type of the attribute
25387 * @value_p: (nullable): a pointer to the value (or the pointer
25388 * itself if the type is a pointer type)
25389 * @flags: a set of #GFileQueryInfoFlags
25390 * @cancellable: (nullable): optional #GCancellable object,
25392 * @error: a #GError, or %NULL
25394 * Sets an attribute in the file with attribute name @attribute to @value_p.
25396 * Some attributes can be unset by setting @type to
25397 * %G_FILE_ATTRIBUTE_TYPE_INVALID and @value_p to %NULL.
25399 * If @cancellable is not %NULL, then the operation can be cancelled by
25400 * triggering the cancellable object from another thread. If the operation
25401 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
25403 * Returns: %TRUE if the attribute was set, %FALSE otherwise.
25408 * g_file_set_attribute_byte_string:
25409 * @file: input #GFile
25410 * @attribute: a string containing the attribute's name
25411 * @value: a string containing the attribute's new value
25412 * @flags: a #GFileQueryInfoFlags
25413 * @cancellable: (nullable): optional #GCancellable object,
25415 * @error: a #GError, or %NULL
25417 * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING to @value.
25418 * If @attribute is of a different type, this operation will fail,
25419 * returning %FALSE.
25421 * If @cancellable is not %NULL, then the operation can be cancelled by
25422 * triggering the cancellable object from another thread. If the operation
25423 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
25425 * Returns: %TRUE if the @attribute was successfully set to @value
25426 * in the @file, %FALSE otherwise.
25431 * g_file_set_attribute_int32:
25432 * @file: input #GFile
25433 * @attribute: a string containing the attribute's name
25434 * @value: a #gint32 containing the attribute's new value
25435 * @flags: a #GFileQueryInfoFlags
25436 * @cancellable: (nullable): optional #GCancellable object,
25438 * @error: a #GError, or %NULL
25440 * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT32 to @value.
25441 * If @attribute is of a different type, this operation will fail.
25443 * If @cancellable is not %NULL, then the operation can be cancelled by
25444 * triggering the cancellable object from another thread. If the operation
25445 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
25447 * Returns: %TRUE if the @attribute was successfully set to @value
25448 * in the @file, %FALSE otherwise.
25453 * g_file_set_attribute_int64:
25454 * @file: input #GFile
25455 * @attribute: a string containing the attribute's name
25456 * @value: a #guint64 containing the attribute's new value
25457 * @flags: a #GFileQueryInfoFlags
25458 * @cancellable: (nullable): optional #GCancellable object,
25460 * @error: a #GError, or %NULL
25462 * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT64 to @value.
25463 * If @attribute is of a different type, this operation will fail.
25465 * If @cancellable is not %NULL, then the operation can be cancelled by
25466 * triggering the cancellable object from another thread. If the operation
25467 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
25469 * Returns: %TRUE if the @attribute was successfully set, %FALSE otherwise.
25474 * g_file_set_attribute_string:
25475 * @file: input #GFile
25476 * @attribute: a string containing the attribute's name
25477 * @value: a string containing the attribute's value
25478 * @flags: #GFileQueryInfoFlags
25479 * @cancellable: (nullable): optional #GCancellable object,
25481 * @error: a #GError, or %NULL
25483 * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_STRING to @value.
25484 * If @attribute is of a different type, this operation will fail.
25486 * If @cancellable is not %NULL, then the operation can be cancelled by
25487 * triggering the cancellable object from another thread. If the operation
25488 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
25490 * Returns: %TRUE if the @attribute was successfully set, %FALSE otherwise.
25495 * g_file_set_attribute_uint32:
25496 * @file: input #GFile
25497 * @attribute: a string containing the attribute's name
25498 * @value: a #guint32 containing the attribute's new value
25499 * @flags: a #GFileQueryInfoFlags
25500 * @cancellable: (nullable): optional #GCancellable object,
25502 * @error: a #GError, or %NULL
25504 * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT32 to @value.
25505 * If @attribute is of a different type, this operation will fail.
25507 * If @cancellable is not %NULL, then the operation can be cancelled by
25508 * triggering the cancellable object from another thread. If the operation
25509 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
25511 * Returns: %TRUE if the @attribute was successfully set to @value
25512 * in the @file, %FALSE otherwise.
25517 * g_file_set_attribute_uint64:
25518 * @file: input #GFile
25519 * @attribute: a string containing the attribute's name
25520 * @value: a #guint64 containing the attribute's new value
25521 * @flags: a #GFileQueryInfoFlags
25522 * @cancellable: (nullable): optional #GCancellable object,
25524 * @error: a #GError, or %NULL
25526 * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT64 to @value.
25527 * If @attribute is of a different type, this operation will fail.
25529 * If @cancellable is not %NULL, then the operation can be cancelled by
25530 * triggering the cancellable object from another thread. If the operation
25531 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
25533 * Returns: %TRUE if the @attribute was successfully set to @value
25534 * in the @file, %FALSE otherwise.
25539 * g_file_set_attributes_async:
25540 * @file: input #GFile
25541 * @info: a #GFileInfo
25542 * @flags: a #GFileQueryInfoFlags
25543 * @io_priority: the [I/O priority][io-priority] of the request
25544 * @cancellable: (nullable): optional #GCancellable object,
25546 * @callback: (scope async): a #GAsyncReadyCallback
25547 * @user_data: (closure): a #gpointer
25549 * Asynchronously sets the attributes of @file with @info.
25551 * For more details, see g_file_set_attributes_from_info(),
25552 * which is the synchronous version of this call.
25554 * When the operation is finished, @callback will be called.
25555 * You can then call g_file_set_attributes_finish() to get
25556 * the result of the operation.
25561 * g_file_set_attributes_finish:
25562 * @file: input #GFile
25563 * @result: a #GAsyncResult
25564 * @info: (out) (transfer full): a #GFileInfo
25565 * @error: a #GError, or %NULL
25567 * Finishes setting an attribute started in g_file_set_attributes_async().
25569 * Returns: %TRUE if the attributes were set correctly, %FALSE otherwise.
25574 * g_file_set_attributes_from_info:
25575 * @file: input #GFile
25576 * @info: a #GFileInfo
25577 * @flags: #GFileQueryInfoFlags
25578 * @cancellable: (nullable): optional #GCancellable object,
25580 * @error: a #GError, or %NULL
25582 * Tries to set all attributes in the #GFileInfo on the target
25583 * values, not stopping on the first error.
25585 * If there is any error during this operation then @error will
25586 * be set to the first error. Error on particular fields are flagged
25587 * by setting the "status" field in the attribute value to
25588 * %G_FILE_ATTRIBUTE_STATUS_ERROR_SETTING, which means you can
25589 * also detect further errors.
25591 * If @cancellable is not %NULL, then the operation can be cancelled by
25592 * triggering the cancellable object from another thread. If the operation
25593 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
25595 * Returns: %FALSE if there was any error, %TRUE otherwise.
25600 * g_file_set_display_name:
25601 * @file: input #GFile
25602 * @display_name: a string
25603 * @cancellable: (nullable): optional #GCancellable object,
25605 * @error: a #GError, or %NULL
25607 * Renames @file to the specified display name.
25609 * The display name is converted from UTF-8 to the correct encoding
25610 * for the target filesystem if possible and the @file is renamed to this.
25612 * If you want to implement a rename operation in the user interface the
25613 * edit name (#G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME) should be used as the
25614 * initial value in the rename widget, and then the result after editing
25615 * should be passed to g_file_set_display_name().
25617 * On success the resulting converted filename is returned.
25619 * If @cancellable is not %NULL, then the operation can be cancelled by
25620 * triggering the cancellable object from another thread. If the operation
25621 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
25623 * Returns: (transfer full): a #GFile specifying what @file was renamed to,
25624 * or %NULL if there was an error.
25625 * Free the returned object with g_object_unref().
25630 * g_file_set_display_name_async:
25631 * @file: input #GFile
25632 * @display_name: a string
25633 * @io_priority: the [I/O priority][io-priority] of the request
25634 * @cancellable: (nullable): optional #GCancellable object,
25636 * @callback: (scope async): a #GAsyncReadyCallback to call
25637 * when the request is satisfied
25638 * @user_data: (closure): the data to pass to callback function
25640 * Asynchronously sets the display name for a given #GFile.
25642 * For more details, see g_file_set_display_name() which is
25643 * the synchronous version of this call.
25645 * When the operation is finished, @callback will be called.
25646 * You can then call g_file_set_display_name_finish() to get
25647 * the result of the operation.
25652 * g_file_set_display_name_finish:
25653 * @file: input #GFile
25654 * @res: a #GAsyncResult
25655 * @error: a #GError, or %NULL
25657 * Finishes setting a display name started with
25658 * g_file_set_display_name_async().
25660 * Returns: (transfer full): a #GFile or %NULL on error.
25661 * Free the returned object with g_object_unref().
25666 * g_file_start_mountable:
25667 * @file: input #GFile
25668 * @flags: flags affecting the operation
25669 * @start_operation: (nullable): a #GMountOperation, or %NULL to avoid user interaction
25670 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore
25671 * @callback: (nullable): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL
25672 * @user_data: the data to pass to callback function
25674 * Starts a file of type #G_FILE_TYPE_MOUNTABLE.
25675 * Using @start_operation, you can request callbacks when, for instance,
25676 * passwords are needed during authentication.
25678 * If @cancellable is not %NULL, then the operation can be cancelled by
25679 * triggering the cancellable object from another thread. If the operation
25680 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
25682 * When the operation is finished, @callback will be called.
25683 * You can then call g_file_mount_mountable_finish() to get
25684 * the result of the operation.
25691 * g_file_start_mountable_finish:
25692 * @file: input #GFile
25693 * @result: a #GAsyncResult
25694 * @error: a #GError, or %NULL
25696 * Finishes a start operation. See g_file_start_mountable() for details.
25698 * Finish an asynchronous start operation that was started
25699 * with g_file_start_mountable().
25701 * Returns: %TRUE if the operation finished successfully. %FALSE
25708 * g_file_stop_mountable:
25709 * @file: input #GFile
25710 * @flags: flags affecting the operation
25711 * @mount_operation: (nullable): a #GMountOperation,
25712 * or %NULL to avoid user interaction.
25713 * @cancellable: (nullable): optional #GCancellable object,
25715 * @callback: (nullable): a #GAsyncReadyCallback to call
25716 * when the request is satisfied, or %NULL
25717 * @user_data: the data to pass to callback function
25719 * Stops a file of type #G_FILE_TYPE_MOUNTABLE.
25721 * If @cancellable is not %NULL, then the operation can be cancelled by
25722 * triggering the cancellable object from another thread. If the operation
25723 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
25725 * When the operation is finished, @callback will be called.
25726 * You can then call g_file_stop_mountable_finish() to get
25727 * the result of the operation.
25734 * g_file_stop_mountable_finish:
25735 * @file: input #GFile
25736 * @result: a #GAsyncResult
25737 * @error: a #GError, or %NULL
25739 * Finishes a stop operation, see g_file_stop_mountable() for details.
25741 * Finish an asynchronous stop operation that was started
25742 * with g_file_stop_mountable().
25744 * Returns: %TRUE if the operation finished successfully.
25745 * %FALSE otherwise.
25751 * g_file_supports_thread_contexts:
25754 * Checks if @file supports
25755 * [thread-default contexts][g-main-context-push-thread-default-context].
25756 * If this returns %FALSE, you cannot perform asynchronous operations on
25757 * @file in a thread that has a thread-default context.
25759 * Returns: Whether or not @file supports thread-default contexts.
25765 * g_file_trash: (virtual trash)
25766 * @file: #GFile to send to trash
25767 * @cancellable: (nullable): optional #GCancellable object,
25769 * @error: a #GError, or %NULL
25771 * Sends @file to the "Trashcan", if possible. This is similar to
25772 * deleting it, but the user can recover it before emptying the trashcan.
25773 * Not all file systems support trashing, so this call can return the
25774 * %G_IO_ERROR_NOT_SUPPORTED error. Since GLib 2.66, the `x-gvfs-notrash` unix
25775 * mount option can be used to disable g_file_trash() support for certain
25776 * mounts, the %G_IO_ERROR_NOT_SUPPORTED error will be returned in that case.
25778 * If @cancellable is not %NULL, then the operation can be cancelled by
25779 * triggering the cancellable object from another thread. If the operation
25780 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
25782 * Returns: %TRUE on successful trash, %FALSE otherwise.
25787 * g_file_trash_async: (virtual trash_async)
25788 * @file: input #GFile
25789 * @io_priority: the [I/O priority][io-priority] of the request
25790 * @cancellable: (nullable): optional #GCancellable object,
25792 * @callback: a #GAsyncReadyCallback to call
25793 * when the request is satisfied
25794 * @user_data: the data to pass to callback function
25796 * Asynchronously sends @file to the Trash location, if possible.
25803 * g_file_trash_finish: (virtual trash_finish)
25804 * @file: input #GFile
25805 * @result: a #GAsyncResult
25806 * @error: a #GError, or %NULL
25808 * Finishes an asynchronous file trashing operation, started with
25809 * g_file_trash_async().
25811 * Returns: %TRUE on successful trash, %FALSE otherwise.
25817 * g_file_unmount_mountable:
25818 * @file: input #GFile
25819 * @flags: flags affecting the operation
25820 * @cancellable: (nullable): optional #GCancellable object,
25822 * @callback: (scope async) (nullable): a #GAsyncReadyCallback to call
25823 * when the request is satisfied, or %NULL
25824 * @user_data: (closure): the data to pass to callback function
25826 * Unmounts a file of type G_FILE_TYPE_MOUNTABLE.
25828 * If @cancellable is not %NULL, then the operation can be cancelled by
25829 * triggering the cancellable object from another thread. If the operation
25830 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
25832 * When the operation is finished, @callback will be called.
25833 * You can then call g_file_unmount_mountable_finish() to get
25834 * the result of the operation.
25836 * Deprecated: 2.22: Use g_file_unmount_mountable_with_operation() instead.
25841 * g_file_unmount_mountable_finish:
25842 * @file: input #GFile
25843 * @result: a #GAsyncResult
25844 * @error: a #GError, or %NULL
25846 * Finishes an unmount operation, see g_file_unmount_mountable() for details.
25848 * Finish an asynchronous unmount operation that was started
25849 * with g_file_unmount_mountable().
25851 * Returns: %TRUE if the operation finished successfully.
25852 * %FALSE otherwise.
25853 * Deprecated: 2.22: Use g_file_unmount_mountable_with_operation_finish()
25859 * g_file_unmount_mountable_with_operation:
25860 * @file: input #GFile
25861 * @flags: flags affecting the operation
25862 * @mount_operation: (nullable): a #GMountOperation,
25863 * or %NULL to avoid user interaction
25864 * @cancellable: (nullable): optional #GCancellable object,
25866 * @callback: (scope async) (nullable): a #GAsyncReadyCallback to call
25867 * when the request is satisfied, or %NULL
25868 * @user_data: (closure): the data to pass to callback function
25870 * Unmounts a file of type #G_FILE_TYPE_MOUNTABLE.
25872 * If @cancellable is not %NULL, then the operation can be cancelled by
25873 * triggering the cancellable object from another thread. If the operation
25874 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
25876 * When the operation is finished, @callback will be called.
25877 * You can then call g_file_unmount_mountable_finish() to get
25878 * the result of the operation.
25885 * g_file_unmount_mountable_with_operation_finish:
25886 * @file: input #GFile
25887 * @result: a #GAsyncResult
25888 * @error: a #GError, or %NULL
25890 * Finishes an unmount operation,
25891 * see g_file_unmount_mountable_with_operation() for details.
25893 * Finish an asynchronous unmount operation that was started
25894 * with g_file_unmount_mountable_with_operation().
25896 * Returns: %TRUE if the operation finished successfully.
25897 * %FALSE otherwise.
25903 * g_filename_completer_get_completion_suffix:
25904 * @completer: the filename completer.
25905 * @initial_text: text to be completed.
25907 * Obtains a completion for @initial_text from @completer.
25909 * Returns: (nullable) (transfer full): a completed string, or %NULL if no
25910 * completion exists. This string is not owned by GIO, so remember to g_free()
25911 * it when finished.
25916 * g_filename_completer_get_completions:
25917 * @completer: the filename completer.
25918 * @initial_text: text to be completed.
25920 * Gets an array of completion strings for a given initial text.
25922 * Returns: (array zero-terminated=1) (transfer full): array of strings with possible completions for @initial_text.
25923 * This array must be freed by g_strfreev() when finished.
25928 * g_filename_completer_new:
25930 * Creates a new filename completer.
25932 * Returns: a #GFilenameCompleter.
25937 * g_filename_completer_set_dirs_only:
25938 * @completer: the filename completer.
25939 * @dirs_only: a #gboolean.
25941 * If @dirs_only is %TRUE, @completer will only
25942 * complete directory names, and not file names.
25947 * g_filter_input_stream_get_base_stream:
25948 * @stream: a #GFilterInputStream.
25950 * Gets the base stream for the filter stream.
25952 * Returns: (transfer none): a #GInputStream.
25957 * g_filter_input_stream_get_close_base_stream:
25958 * @stream: a #GFilterInputStream.
25960 * Returns whether the base stream will be closed when @stream is
25963 * Returns: %TRUE if the base stream will be closed.
25968 * g_filter_input_stream_set_close_base_stream:
25969 * @stream: a #GFilterInputStream.
25970 * @close_base: %TRUE to close the base stream.
25972 * Sets whether the base stream will be closed when @stream is closed.
25977 * g_filter_output_stream_get_base_stream:
25978 * @stream: a #GFilterOutputStream.
25980 * Gets the base stream for the filter stream.
25982 * Returns: (transfer none): a #GOutputStream.
25987 * g_filter_output_stream_get_close_base_stream:
25988 * @stream: a #GFilterOutputStream.
25990 * Returns whether the base stream will be closed when @stream is
25993 * Returns: %TRUE if the base stream will be closed.
25998 * g_filter_output_stream_set_close_base_stream:
25999 * @stream: a #GFilterOutputStream.
26000 * @close_base: %TRUE to close the base stream.
26002 * Sets whether the base stream will be closed when @stream is closed.
26007 * g_icon_deserialize:
26008 * @value: (transfer none): a #GVariant created with g_icon_serialize()
26010 * Deserializes a #GIcon previously serialized using g_icon_serialize().
26012 * Returns: (nullable) (transfer full): a #GIcon, or %NULL when deserialization fails.
26019 * @icon1: (nullable): pointer to the first #GIcon.
26020 * @icon2: (nullable): pointer to the second #GIcon.
26022 * Checks if two icons are equal.
26024 * Returns: %TRUE if @icon1 is equal to @icon2. %FALSE otherwise.
26029 * g_icon_hash: (virtual hash)
26030 * @icon: (not nullable): #gconstpointer to an icon object.
26032 * Gets a hash for an icon.
26034 * Returns: a #guint containing a hash for the @icon, suitable for
26035 * use in a #GHashTable or similar data structure.
26040 * g_icon_new_for_string:
26041 * @str: A string obtained via g_icon_to_string().
26042 * @error: Return location for error.
26044 * Generate a #GIcon instance from @str. This function can fail if
26045 * @str is not valid - see g_icon_to_string() for discussion.
26047 * If your application or library provides one or more #GIcon
26048 * implementations you need to ensure that each #GType is registered
26049 * with the type system prior to calling g_icon_new_for_string().
26051 * Returns: (transfer full): An object implementing the #GIcon
26052 * interface or %NULL if @error is set.
26058 * g_icon_serialize:
26061 * Serializes a #GIcon into a #GVariant. An equivalent #GIcon can be retrieved
26062 * back by calling g_icon_deserialize() on the returned value.
26063 * As serialization will avoid using raw icon data when possible, it only
26064 * makes sense to transfer the #GVariant between processes on the same machine,
26065 * (as opposed to over the network), and within the same file system namespace.
26067 * Returns: (nullable) (transfer full): a #GVariant, or %NULL when serialization fails. The #GVariant will not be floating.
26073 * g_icon_to_string: (virtual to_tokens)
26076 * Generates a textual representation of @icon that can be used for
26077 * serialization such as when passing @icon to a different process or
26078 * saving it to persistent storage. Use g_icon_new_for_string() to
26079 * get @icon back from the returned string.
26081 * The encoding of the returned string is proprietary to #GIcon except
26082 * in the following two cases
26084 * - If @icon is a #GFileIcon, the returned string is a native path
26085 * (such as `/path/to/my icon.png`) without escaping
26086 * if the #GFile for @icon is a native file. If the file is not
26087 * native, the returned string is the result of g_file_get_uri()
26088 * (such as `sftp://path/to/my%20icon.png`).
26090 * - If @icon is a #GThemedIcon with exactly one name and no fallbacks,
26091 * the encoding is simply the name (such as `network-server`).
26093 * Returns: (nullable): An allocated NUL-terminated UTF8 string or
26094 * %NULL if @icon can't be serialized. Use g_free() to free.
26100 * g_inet_address_equal:
26101 * @address: A #GInetAddress.
26102 * @other_address: Another #GInetAddress.
26104 * Checks if two #GInetAddress instances are equal, e.g. the same address.
26106 * Returns: %TRUE if @address and @other_address are equal, %FALSE otherwise.
26112 * g_inet_address_get_family:
26113 * @address: a #GInetAddress
26115 * Gets @address's family
26117 * Returns: @address's family
26123 * g_inet_address_get_is_any:
26124 * @address: a #GInetAddress
26126 * Tests whether @address is the "any" address for its family.
26128 * Returns: %TRUE if @address is the "any" address for its family.
26134 * g_inet_address_get_is_link_local:
26135 * @address: a #GInetAddress
26137 * Tests whether @address is a link-local address (that is, if it
26138 * identifies a host on a local network that is not connected to the
26141 * Returns: %TRUE if @address is a link-local address.
26147 * g_inet_address_get_is_loopback:
26148 * @address: a #GInetAddress
26150 * Tests whether @address is the loopback address for its family.
26152 * Returns: %TRUE if @address is the loopback address for its family.
26158 * g_inet_address_get_is_mc_global:
26159 * @address: a #GInetAddress
26161 * Tests whether @address is a global multicast address.
26163 * Returns: %TRUE if @address is a global multicast address.
26169 * g_inet_address_get_is_mc_link_local:
26170 * @address: a #GInetAddress
26172 * Tests whether @address is a link-local multicast address.
26174 * Returns: %TRUE if @address is a link-local multicast address.
26180 * g_inet_address_get_is_mc_node_local:
26181 * @address: a #GInetAddress
26183 * Tests whether @address is a node-local multicast address.
26185 * Returns: %TRUE if @address is a node-local multicast address.
26191 * g_inet_address_get_is_mc_org_local:
26192 * @address: a #GInetAddress
26194 * Tests whether @address is an organization-local multicast address.
26196 * Returns: %TRUE if @address is an organization-local multicast address.
26202 * g_inet_address_get_is_mc_site_local:
26203 * @address: a #GInetAddress
26205 * Tests whether @address is a site-local multicast address.
26207 * Returns: %TRUE if @address is a site-local multicast address.
26213 * g_inet_address_get_is_multicast:
26214 * @address: a #GInetAddress
26216 * Tests whether @address is a multicast address.
26218 * Returns: %TRUE if @address is a multicast address.
26224 * g_inet_address_get_is_site_local:
26225 * @address: a #GInetAddress
26227 * Tests whether @address is a site-local address such as 10.0.0.1
26228 * (that is, the address identifies a host on a local network that can
26229 * not be reached directly from the Internet, but which may have
26230 * outgoing Internet connectivity via a NAT or firewall).
26232 * Returns: %TRUE if @address is a site-local address.
26238 * g_inet_address_get_native_size:
26239 * @address: a #GInetAddress
26241 * Gets the size of the native raw binary address for @address. This
26242 * is the size of the data that you get from g_inet_address_to_bytes().
26244 * Returns: the number of bytes used for the native version of @address.
26250 * g_inet_address_mask_equal:
26251 * @mask: a #GInetAddressMask
26252 * @mask2: another #GInetAddressMask
26254 * Tests if @mask and @mask2 are the same mask.
26256 * Returns: whether @mask and @mask2 are the same mask
26262 * g_inet_address_mask_get_address:
26263 * @mask: a #GInetAddressMask
26265 * Gets @mask's base address
26267 * Returns: (transfer none): @mask's base address
26273 * g_inet_address_mask_get_family:
26274 * @mask: a #GInetAddressMask
26276 * Gets the #GSocketFamily of @mask's address
26278 * Returns: the #GSocketFamily of @mask's address
26284 * g_inet_address_mask_get_length:
26285 * @mask: a #GInetAddressMask
26287 * Gets @mask's length
26289 * Returns: @mask's length
26295 * g_inet_address_mask_matches:
26296 * @mask: a #GInetAddressMask
26297 * @address: a #GInetAddress
26299 * Tests if @address falls within the range described by @mask.
26301 * Returns: whether @address falls within the range described by
26308 * g_inet_address_mask_new:
26309 * @addr: a #GInetAddress
26310 * @length: number of bits of @addr to use
26311 * @error: return location for #GError, or %NULL
26313 * Creates a new #GInetAddressMask representing all addresses whose
26314 * first @length bits match @addr.
26316 * Returns: a new #GInetAddressMask, or %NULL on error
26322 * g_inet_address_mask_new_from_string:
26323 * @mask_string: an IP address or address/length string
26324 * @error: return location for #GError, or %NULL
26326 * Parses @mask_string as an IP address and (optional) length, and
26327 * creates a new #GInetAddressMask. The length, if present, is
26328 * delimited by a "/". If it is not present, then the length is
26329 * assumed to be the full length of the address.
26331 * Returns: a new #GInetAddressMask corresponding to @string, or %NULL
26338 * g_inet_address_mask_to_string:
26339 * @mask: a #GInetAddressMask
26341 * Converts @mask back to its corresponding string form.
26343 * Returns: a string corresponding to @mask.
26349 * g_inet_address_new_any:
26350 * @family: the address family
26352 * Creates a #GInetAddress for the "any" address (unassigned/"don't
26353 * care") for @family.
26355 * Returns: a new #GInetAddress corresponding to the "any" address
26357 * Free the returned object with g_object_unref().
26363 * g_inet_address_new_from_bytes:
26364 * @bytes: (array) (element-type guint8): raw address data
26365 * @family: the address family of @bytes
26367 * Creates a new #GInetAddress from the given @family and @bytes.
26368 * @bytes should be 4 bytes for %G_SOCKET_FAMILY_IPV4 and 16 bytes for
26369 * %G_SOCKET_FAMILY_IPV6.
26371 * Returns: a new #GInetAddress corresponding to @family and @bytes.
26372 * Free the returned object with g_object_unref().
26378 * g_inet_address_new_from_string:
26379 * @string: a string representation of an IP address
26381 * Parses @string as an IP address and creates a new #GInetAddress.
26383 * Returns: (nullable) (transfer full): a new #GInetAddress corresponding
26384 * to @string, or %NULL if @string could not be parsed.
26385 * Free the returned object with g_object_unref().
26391 * g_inet_address_new_loopback:
26392 * @family: the address family
26394 * Creates a #GInetAddress for the loopback address for @family.
26396 * Returns: a new #GInetAddress corresponding to the loopback address
26398 * Free the returned object with g_object_unref().
26404 * g_inet_address_to_bytes: (skip)
26405 * @address: a #GInetAddress
26407 * Gets the raw binary address data from @address.
26409 * Returns: a pointer to an internal array of the bytes in @address,
26410 * which should not be modified, stored, or freed. The size of this
26411 * array can be gotten with g_inet_address_get_native_size().
26417 * g_inet_address_to_string:
26418 * @address: a #GInetAddress
26420 * Converts @address to string form.
26422 * Returns: a representation of @address as a string, which should be
26429 * g_inet_socket_address_get_address:
26430 * @address: a #GInetSocketAddress
26432 * Gets @address's #GInetAddress.
26434 * Returns: (transfer none): the #GInetAddress for @address, which must be
26435 * g_object_ref()'d if it will be stored
26441 * g_inet_socket_address_get_flowinfo:
26442 * @address: a %G_SOCKET_FAMILY_IPV6 #GInetSocketAddress
26444 * Gets the `sin6_flowinfo` field from @address,
26445 * which must be an IPv6 address.
26447 * Returns: the flowinfo field
26453 * g_inet_socket_address_get_port:
26454 * @address: a #GInetSocketAddress
26456 * Gets @address's port.
26458 * Returns: the port for @address
26464 * g_inet_socket_address_get_scope_id:
26465 * @address: a %G_SOCKET_FAMILY_IPV6 #GInetAddress
26467 * Gets the `sin6_scope_id` field from @address,
26468 * which must be an IPv6 address.
26470 * Returns: the scope id field
26476 * g_inet_socket_address_new:
26477 * @address: a #GInetAddress
26478 * @port: a port number
26480 * Creates a new #GInetSocketAddress for @address and @port.
26482 * Returns: a new #GInetSocketAddress
26488 * g_inet_socket_address_new_from_string:
26489 * @address: the string form of an IP address
26490 * @port: a port number
26492 * Creates a new #GInetSocketAddress for @address and @port.
26494 * If @address is an IPv6 address, it can also contain a scope ID
26495 * (separated from the address by a `%`).
26497 * Returns: (nullable) (transfer full): a new #GInetSocketAddress,
26498 * or %NULL if @address cannot be parsed.
26505 * @initable: a #GInitable.
26506 * @cancellable: optional #GCancellable object, %NULL to ignore.
26507 * @error: a #GError location to store the error occurring, or %NULL to
26510 * Initializes the object implementing the interface.
26512 * This method is intended for language bindings. If writing in C,
26513 * g_initable_new() should typically be used instead.
26515 * The object must be initialized before any real use after initial
26516 * construction, either with this function or g_async_initable_init_async().
26518 * Implementations may also support cancellation. If @cancellable is not %NULL,
26519 * then initialization can be cancelled by triggering the cancellable object
26520 * from another thread. If the operation was cancelled, the error
26521 * %G_IO_ERROR_CANCELLED will be returned. If @cancellable is not %NULL and
26522 * the object doesn't support cancellable initialization the error
26523 * %G_IO_ERROR_NOT_SUPPORTED will be returned.
26525 * If the object is not initialized, or initialization returns with an
26526 * error, then all operations on the object except g_object_ref() and
26527 * g_object_unref() are considered to be invalid, and have undefined
26528 * behaviour. See the [introduction][ginitable] for more details.
26530 * Callers should not assume that a class which implements #GInitable can be
26531 * initialized multiple times, unless the class explicitly documents itself as
26532 * supporting this. Generally, a class’ implementation of init() can assume
26533 * (and assert) that it will only be called once. Previously, this documentation
26534 * recommended all #GInitable implementations should be idempotent; that
26535 * recommendation was relaxed in GLib 2.54.
26537 * If a class explicitly supports being initialized multiple times, it is
26538 * recommended that the method is idempotent: multiple calls with the same
26539 * arguments should return the same results. Only the first call initializes
26540 * the object; further calls return the result of the first call.
26542 * One reason why a class might need to support idempotent initialization is if
26543 * it is designed to be used via the singleton pattern, with a
26544 * #GObjectClass.constructor that sometimes returns an existing instance.
26545 * In this pattern, a caller would expect to be able to call g_initable_init()
26546 * on the result of g_object_new(), regardless of whether it is in fact a new
26549 * Returns: %TRUE if successful. If an error has occurred, this function will
26550 * return %FALSE and set @error appropriately if present.
26557 * @object_type: a #GType supporting #GInitable.
26558 * @cancellable: optional #GCancellable object, %NULL to ignore.
26559 * @error: a #GError location to store the error occurring, or %NULL to
26561 * @first_property_name: (nullable): the name of the first property, or %NULL if no
26563 * @...: the value if the first property, followed by and other property
26564 * value pairs, and ended by %NULL.
26566 * Helper function for constructing #GInitable object. This is
26567 * similar to g_object_new() but also initializes the object
26568 * and returns %NULL, setting an error on failure.
26570 * Returns: (type GObject.Object) (transfer full): a newly allocated
26571 * #GObject, or %NULL on error
26577 * g_initable_new_valist:
26578 * @object_type: a #GType supporting #GInitable.
26579 * @first_property_name: the name of the first property, followed by
26580 * the value, and other property value pairs, and ended by %NULL.
26581 * @var_args: The var args list generated from @first_property_name.
26582 * @cancellable: optional #GCancellable object, %NULL to ignore.
26583 * @error: a #GError location to store the error occurring, or %NULL to
26586 * Helper function for constructing #GInitable object. This is
26587 * similar to g_object_new_valist() but also initializes the object
26588 * and returns %NULL, setting an error on failure.
26590 * Returns: (type GObject.Object) (transfer full): a newly allocated
26591 * #GObject, or %NULL on error
26598 * @object_type: a #GType supporting #GInitable.
26599 * @n_parameters: the number of parameters in @parameters
26600 * @parameters: (array length=n_parameters): the parameters to use to construct the object
26601 * @cancellable: optional #GCancellable object, %NULL to ignore.
26602 * @error: a #GError location to store the error occurring, or %NULL to
26605 * Helper function for constructing #GInitable object. This is
26606 * similar to g_object_newv() but also initializes the object
26607 * and returns %NULL, setting an error on failure.
26609 * Returns: (type GObject.Object) (transfer full): a newly allocated
26610 * #GObject, or %NULL on error
26612 * Deprecated: 2.54: Use g_object_new_with_properties() and
26613 * g_initable_init() instead. See #GParameter for more information.
26618 * g_input_stream_clear_pending:
26619 * @stream: input stream
26621 * Clears the pending flag on @stream.
26626 * g_input_stream_close:
26627 * @stream: A #GInputStream.
26628 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
26629 * @error: location to store the error occurring, or %NULL to ignore
26631 * Closes the stream, releasing resources related to it.
26633 * Once the stream is closed, all other operations will return %G_IO_ERROR_CLOSED.
26634 * Closing a stream multiple times will not return an error.
26636 * Streams will be automatically closed when the last reference
26637 * is dropped, but you might want to call this function to make sure
26638 * resources are released as early as possible.
26640 * Some streams might keep the backing store of the stream (e.g. a file descriptor)
26641 * open after the stream is closed. See the documentation for the individual
26642 * stream for details.
26644 * On failure the first error that happened will be reported, but the close
26645 * operation will finish as much as possible. A stream that failed to
26646 * close will still return %G_IO_ERROR_CLOSED for all operations. Still, it
26647 * is important to check and report the error to the user.
26649 * If @cancellable is not %NULL, then the operation can be cancelled by
26650 * triggering the cancellable object from another thread. If the operation
26651 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
26652 * Cancelling a close will still leave the stream closed, but some streams
26653 * can use a faster close that doesn't block to e.g. check errors.
26655 * Returns: %TRUE on success, %FALSE on failure
26660 * g_input_stream_close_async:
26661 * @stream: A #GInputStream.
26662 * @io_priority: the [I/O priority][io-priority] of the request
26663 * @cancellable: (nullable): optional cancellable object
26664 * @callback: (scope async): callback to call when the request is satisfied
26665 * @user_data: (closure): the data to pass to callback function
26667 * Requests an asynchronous closes of the stream, releasing resources related to it.
26668 * When the operation is finished @callback will be called.
26669 * You can then call g_input_stream_close_finish() to get the result of the
26672 * For behaviour details see g_input_stream_close().
26674 * The asynchronous methods have a default fallback that uses threads to implement
26675 * asynchronicity, so they are optional for inheriting classes. However, if you
26676 * override one you must override all.
26681 * g_input_stream_close_finish:
26682 * @stream: a #GInputStream.
26683 * @result: a #GAsyncResult.
26684 * @error: a #GError location to store the error occurring, or %NULL to
26687 * Finishes closing a stream asynchronously, started from g_input_stream_close_async().
26689 * Returns: %TRUE if the stream was closed successfully.
26694 * g_input_stream_has_pending:
26695 * @stream: input stream.
26697 * Checks if an input stream has pending actions.
26699 * Returns: %TRUE if @stream has pending actions.
26704 * g_input_stream_is_closed:
26705 * @stream: input stream.
26707 * Checks if an input stream is closed.
26709 * Returns: %TRUE if the stream is closed.
26714 * g_input_stream_read:
26715 * @stream: a #GInputStream.
26716 * @buffer: (array length=count) (element-type guint8) (out caller-allocates):
26717 * a buffer to read data into (which should be at least count bytes long).
26718 * @count: (in): the number of bytes that will be read from the stream
26719 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
26720 * @error: location to store the error occurring, or %NULL to ignore
26722 * Tries to read @count bytes from the stream into the buffer starting at
26723 * @buffer. Will block during this read.
26725 * If count is zero returns zero and does nothing. A value of @count
26726 * larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
26728 * On success, the number of bytes read into the buffer is returned.
26729 * It is not an error if this is not the same as the requested size, as it
26730 * can happen e.g. near the end of a file. Zero is returned on end of file
26731 * (or if @count is zero), but never otherwise.
26733 * The returned @buffer is not a nul-terminated string, it can contain nul bytes
26734 * at any position, and this function doesn't nul-terminate the @buffer.
26736 * If @cancellable is not %NULL, then the operation can be cancelled by
26737 * triggering the cancellable object from another thread. If the operation
26738 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
26739 * operation was partially finished when the operation was cancelled the
26740 * partial result will be returned, without an error.
26742 * On error -1 is returned and @error is set accordingly.
26744 * Returns: Number of bytes read, or -1 on error, or 0 on end of file.
26749 * g_input_stream_read_all:
26750 * @stream: a #GInputStream.
26751 * @buffer: (array length=count) (element-type guint8) (out caller-allocates):
26752 * a buffer to read data into (which should be at least count bytes long).
26753 * @count: (in): the number of bytes that will be read from the stream
26754 * @bytes_read: (out): location to store the number of bytes that was read from the stream
26755 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
26756 * @error: location to store the error occurring, or %NULL to ignore
26758 * Tries to read @count bytes from the stream into the buffer starting at
26759 * @buffer. Will block during this read.
26761 * This function is similar to g_input_stream_read(), except it tries to
26762 * read as many bytes as requested, only stopping on an error or end of stream.
26764 * On a successful read of @count bytes, or if we reached the end of the
26765 * stream, %TRUE is returned, and @bytes_read is set to the number of bytes
26766 * read into @buffer.
26768 * If there is an error during the operation %FALSE is returned and @error
26769 * is set to indicate the error status.
26771 * As a special exception to the normal conventions for functions that
26772 * use #GError, if this function returns %FALSE (and sets @error) then
26773 * @bytes_read will be set to the number of bytes that were successfully
26774 * read before the error was encountered. This functionality is only
26775 * available from C. If you need it from another language then you must
26776 * write your own loop around g_input_stream_read().
26778 * Returns: %TRUE on success, %FALSE if there was an error
26783 * g_input_stream_read_all_async:
26784 * @stream: A #GInputStream
26785 * @buffer: (array length=count) (element-type guint8) (out caller-allocates):
26786 * a buffer to read data into (which should be at least count bytes long)
26787 * @count: (in): the number of bytes that will be read from the stream
26788 * @io_priority: the [I/O priority][io-priority] of the request
26789 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore
26790 * @callback: (scope async): callback to call when the request is satisfied
26791 * @user_data: (closure): the data to pass to callback function
26793 * Request an asynchronous read of @count bytes from the stream into the
26794 * buffer starting at @buffer.
26796 * This is the asynchronous equivalent of g_input_stream_read_all().
26798 * Call g_input_stream_read_all_finish() to collect the result.
26800 * Any outstanding I/O request with higher priority (lower numerical
26801 * value) will be executed before an outstanding request with lower
26802 * priority. Default priority is %G_PRIORITY_DEFAULT.
26809 * g_input_stream_read_all_finish:
26810 * @stream: a #GInputStream
26811 * @result: a #GAsyncResult
26812 * @bytes_read: (out): location to store the number of bytes that was read from the stream
26813 * @error: a #GError location to store the error occurring, or %NULL to ignore
26815 * Finishes an asynchronous stream read operation started with
26816 * g_input_stream_read_all_async().
26818 * As a special exception to the normal conventions for functions that
26819 * use #GError, if this function returns %FALSE (and sets @error) then
26820 * @bytes_read will be set to the number of bytes that were successfully
26821 * read before the error was encountered. This functionality is only
26822 * available from C. If you need it from another language then you must
26823 * write your own loop around g_input_stream_read_async().
26825 * Returns: %TRUE on success, %FALSE if there was an error
26831 * g_input_stream_read_async:
26832 * @stream: A #GInputStream.
26833 * @buffer: (array length=count) (element-type guint8) (out caller-allocates):
26834 * a buffer to read data into (which should be at least count bytes long).
26835 * @count: (in): the number of bytes that will be read from the stream
26836 * @io_priority: the [I/O priority][io-priority]
26838 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
26839 * @callback: (scope async): callback to call when the request is satisfied
26840 * @user_data: (closure): the data to pass to callback function
26842 * Request an asynchronous read of @count bytes from the stream into the buffer
26843 * starting at @buffer. When the operation is finished @callback will be called.
26844 * You can then call g_input_stream_read_finish() to get the result of the
26847 * During an async request no other sync and async calls are allowed on @stream, and will
26848 * result in %G_IO_ERROR_PENDING errors.
26850 * A value of @count larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
26852 * On success, the number of bytes read into the buffer will be passed to the
26853 * callback. It is not an error if this is not the same as the requested size, as it
26854 * can happen e.g. near the end of a file, but generally we try to read
26855 * as many bytes as requested. Zero is returned on end of file
26856 * (or if @count is zero), but never otherwise.
26858 * Any outstanding i/o request with higher priority (lower numerical value) will
26859 * be executed before an outstanding request with lower priority. Default
26860 * priority is %G_PRIORITY_DEFAULT.
26862 * The asynchronous methods have a default fallback that uses threads to implement
26863 * asynchronicity, so they are optional for inheriting classes. However, if you
26864 * override one you must override all.
26869 * g_input_stream_read_bytes:
26870 * @stream: a #GInputStream.
26871 * @count: maximum number of bytes that will be read from the stream. Common
26872 * values include 4096 and 8192.
26873 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
26874 * @error: location to store the error occurring, or %NULL to ignore
26876 * Like g_input_stream_read(), this tries to read @count bytes from
26877 * the stream in a blocking fashion. However, rather than reading into
26878 * a user-supplied buffer, this will create a new #GBytes containing
26879 * the data that was read. This may be easier to use from language
26882 * If count is zero, returns a zero-length #GBytes and does nothing. A
26883 * value of @count larger than %G_MAXSSIZE will cause a
26884 * %G_IO_ERROR_INVALID_ARGUMENT error.
26886 * On success, a new #GBytes is returned. It is not an error if the
26887 * size of this object is not the same as the requested size, as it
26888 * can happen e.g. near the end of a file. A zero-length #GBytes is
26889 * returned on end of file (or if @count is zero), but never
26892 * If @cancellable is not %NULL, then the operation can be cancelled by
26893 * triggering the cancellable object from another thread. If the operation
26894 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
26895 * operation was partially finished when the operation was cancelled the
26896 * partial result will be returned, without an error.
26898 * On error %NULL is returned and @error is set accordingly.
26900 * Returns: (transfer full): a new #GBytes, or %NULL on error
26906 * g_input_stream_read_bytes_async:
26907 * @stream: A #GInputStream.
26908 * @count: the number of bytes that will be read from the stream
26909 * @io_priority: the [I/O priority][io-priority] of the request
26910 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
26911 * @callback: (scope async): callback to call when the request is satisfied
26912 * @user_data: (closure): the data to pass to callback function
26914 * Request an asynchronous read of @count bytes from the stream into a
26915 * new #GBytes. When the operation is finished @callback will be
26916 * called. You can then call g_input_stream_read_bytes_finish() to get the
26917 * result of the operation.
26919 * During an async request no other sync and async calls are allowed
26920 * on @stream, and will result in %G_IO_ERROR_PENDING errors.
26922 * A value of @count larger than %G_MAXSSIZE will cause a
26923 * %G_IO_ERROR_INVALID_ARGUMENT error.
26925 * On success, the new #GBytes will be passed to the callback. It is
26926 * not an error if this is smaller than the requested size, as it can
26927 * happen e.g. near the end of a file, but generally we try to read as
26928 * many bytes as requested. Zero is returned on end of file (or if
26929 * @count is zero), but never otherwise.
26931 * Any outstanding I/O request with higher priority (lower numerical
26932 * value) will be executed before an outstanding request with lower
26933 * priority. Default priority is %G_PRIORITY_DEFAULT.
26940 * g_input_stream_read_bytes_finish:
26941 * @stream: a #GInputStream.
26942 * @result: a #GAsyncResult.
26943 * @error: a #GError location to store the error occurring, or %NULL to
26946 * Finishes an asynchronous stream read-into-#GBytes operation.
26948 * Returns: (transfer full): the newly-allocated #GBytes, or %NULL on error
26954 * g_input_stream_read_finish:
26955 * @stream: a #GInputStream.
26956 * @result: a #GAsyncResult.
26957 * @error: a #GError location to store the error occurring, or %NULL to
26960 * Finishes an asynchronous stream read operation.
26962 * Returns: number of bytes read in, or -1 on error, or 0 on end of file.
26967 * g_input_stream_set_pending:
26968 * @stream: input stream
26969 * @error: a #GError location to store the error occurring, or %NULL to
26972 * Sets @stream to have actions pending. If the pending flag is
26973 * already set or @stream is closed, it will return %FALSE and set
26976 * Returns: %TRUE if pending was previously unset and is now set.
26981 * g_input_stream_skip:
26982 * @stream: a #GInputStream.
26983 * @count: the number of bytes that will be skipped from the stream
26984 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
26985 * @error: location to store the error occurring, or %NULL to ignore
26987 * Tries to skip @count bytes from the stream. Will block during the operation.
26989 * This is identical to g_input_stream_read(), from a behaviour standpoint,
26990 * but the bytes that are skipped are not returned to the user. Some
26991 * streams have an implementation that is more efficient than reading the data.
26993 * This function is optional for inherited classes, as the default implementation
26994 * emulates it using read.
26996 * If @cancellable is not %NULL, then the operation can be cancelled by
26997 * triggering the cancellable object from another thread. If the operation
26998 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
26999 * operation was partially finished when the operation was cancelled the
27000 * partial result will be returned, without an error.
27002 * Returns: Number of bytes skipped, or -1 on error
27007 * g_input_stream_skip_async:
27008 * @stream: A #GInputStream.
27009 * @count: the number of bytes that will be skipped from the stream
27010 * @io_priority: the [I/O priority][io-priority] of the request
27011 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
27012 * @callback: (scope async): callback to call when the request is satisfied
27013 * @user_data: (closure): the data to pass to callback function
27015 * Request an asynchronous skip of @count bytes from the stream.
27016 * When the operation is finished @callback will be called.
27017 * You can then call g_input_stream_skip_finish() to get the result
27018 * of the operation.
27020 * During an async request no other sync and async calls are allowed,
27021 * and will result in %G_IO_ERROR_PENDING errors.
27023 * A value of @count larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
27025 * On success, the number of bytes skipped will be passed to the callback.
27026 * It is not an error if this is not the same as the requested size, as it
27027 * can happen e.g. near the end of a file, but generally we try to skip
27028 * as many bytes as requested. Zero is returned on end of file
27029 * (or if @count is zero), but never otherwise.
27031 * Any outstanding i/o request with higher priority (lower numerical value)
27032 * will be executed before an outstanding request with lower priority.
27033 * Default priority is %G_PRIORITY_DEFAULT.
27035 * The asynchronous methods have a default fallback that uses threads to
27036 * implement asynchronicity, so they are optional for inheriting classes.
27037 * However, if you override one, you must override all.
27042 * g_input_stream_skip_finish:
27043 * @stream: a #GInputStream.
27044 * @result: a #GAsyncResult.
27045 * @error: a #GError location to store the error occurring, or %NULL to
27048 * Finishes a stream skip operation.
27050 * Returns: the size of the bytes skipped, or `-1` on error.
27055 * g_io_error_from_errno:
27056 * @err_no: Error number as defined in errno.h.
27058 * Converts errno.h error codes into GIO error codes. The fallback
27059 * value %G_IO_ERROR_FAILED is returned for error codes not currently
27060 * handled (but note that future GLib releases may return a more
27061 * specific value instead).
27063 * As %errno is global and may be modified by intermediate function
27064 * calls, you should save its value as soon as the call which sets it
27066 * Returns: #GIOErrorEnum value for the given errno.h error number.
27071 * g_io_error_from_win32_error:
27072 * @error_code: Windows error number.
27074 * Converts some common error codes (as returned from GetLastError()
27075 * or WSAGetLastError()) into GIO error codes. The fallback value
27076 * %G_IO_ERROR_FAILED is returned for error codes not currently
27077 * handled (but note that future GLib releases may return a more
27078 * specific value instead).
27080 * You can use g_win32_error_message() to get a localized string
27081 * corresponding to @error_code. (But note that unlike g_strerror(),
27082 * g_win32_error_message() returns a string that must be freed.)
27084 * Returns: #GIOErrorEnum value for the given error number.
27090 * g_io_error_quark:
27092 * Gets the GIO Error Quark.
27094 * Returns: a #GQuark.
27099 * g_io_extension_get_name:
27100 * @extension: a #GIOExtension
27102 * Gets the name under which @extension was registered.
27104 * Note that the same type may be registered as extension
27105 * for multiple extension points, under different names.
27107 * Returns: the name of @extension.
27112 * g_io_extension_get_priority:
27113 * @extension: a #GIOExtension
27115 * Gets the priority with which @extension was registered.
27117 * Returns: the priority of @extension
27122 * g_io_extension_get_type:
27123 * @extension: a #GIOExtension
27125 * Gets the type associated with @extension.
27127 * Returns: the type of @extension
27132 * g_io_extension_point_get_extension_by_name:
27133 * @extension_point: a #GIOExtensionPoint
27134 * @name: the name of the extension to get
27136 * Finds a #GIOExtension for an extension point by name.
27138 * Returns: (transfer none): the #GIOExtension for @extension_point that has the
27139 * given name, or %NULL if there is no extension with that name
27144 * g_io_extension_point_get_extensions:
27145 * @extension_point: a #GIOExtensionPoint
27147 * Gets a list of all extensions that implement this extension point.
27148 * The list is sorted by priority, beginning with the highest priority.
27150 * Returns: (element-type GIOExtension) (transfer none): a #GList of
27151 * #GIOExtensions. The list is owned by GIO and should not be
27157 * g_io_extension_point_get_required_type:
27158 * @extension_point: a #GIOExtensionPoint
27160 * Gets the required type for @extension_point.
27162 * Returns: the #GType that all implementations must have,
27163 * or #G_TYPE_INVALID if the extension point has no required type
27168 * g_io_extension_point_implement:
27169 * @extension_point_name: the name of the extension point
27170 * @type: the #GType to register as extension
27171 * @extension_name: the name for the extension
27172 * @priority: the priority for the extension
27174 * Registers @type as extension for the extension point with name
27175 * @extension_point_name.
27177 * If @type has already been registered as an extension for this
27178 * extension point, the existing #GIOExtension object is returned.
27180 * Returns: (transfer none): a #GIOExtension object for #GType
27185 * g_io_extension_point_lookup:
27186 * @name: the name of the extension point
27188 * Looks up an existing extension point.
27190 * Returns: (transfer none): the #GIOExtensionPoint, or %NULL if there
27191 * is no registered extension point with the given name.
27196 * g_io_extension_point_register:
27197 * @name: The name of the extension point
27199 * Registers an extension point.
27201 * Returns: (transfer none): the new #GIOExtensionPoint. This object is
27202 * owned by GIO and should not be freed.
27207 * g_io_extension_point_set_required_type:
27208 * @extension_point: a #GIOExtensionPoint
27209 * @type: the #GType to require
27211 * Sets the required type for @extension_point to @type.
27212 * All implementations must henceforth have this type.
27217 * g_io_extension_ref_class:
27218 * @extension: a #GIOExtension
27220 * Gets a reference to the class for the type that is
27221 * associated with @extension.
27223 * Returns: (transfer full): the #GTypeClass for the type of @extension
27229 * @filename: (type filename): filename of the shared library module.
27231 * Creates a new GIOModule that will load the specific
27232 * shared library when in use.
27234 * Returns: a #GIOModule from given @filename,
27235 * or %NULL on error.
27240 * g_io_module_scope_block:
27241 * @scope: a module loading scope
27242 * @basename: the basename to block
27244 * Block modules with the given @basename from being loaded when
27245 * this scope is used with g_io_modules_scan_all_in_directory_with_scope()
27246 * or g_io_modules_load_all_in_directory_with_scope().
27253 * g_io_module_scope_free:
27254 * @scope: a module loading scope
27256 * Free a module scope.
27263 * g_io_module_scope_new:
27264 * @flags: flags for the new scope
27266 * Create a new scope for loading of IO modules. A scope can be used for
27267 * blocking duplicate modules, or blocking a module you don't want to load.
27269 * Specify the %G_IO_MODULE_SCOPE_BLOCK_DUPLICATES flag to block modules
27270 * which have the same base name as a module that has already been seen
27273 * Returns: (transfer full): the new module scope
27279 * g_io_modules_load_all_in_directory:
27280 * @dirname: (type filename): pathname for a directory containing modules
27283 * Loads all the modules in the specified directory.
27285 * If don't require all modules to be initialized (and thus registering
27286 * all gtypes) then you can use g_io_modules_scan_all_in_directory()
27287 * which allows delayed/lazy loading of modules.
27289 * Returns: (element-type GIOModule) (transfer full): a list of #GIOModules loaded
27290 * from the directory,
27291 * All the modules are loaded into memory, if you want to
27292 * unload them (enabling on-demand loading) you must call
27293 * g_type_module_unuse() on all the modules. Free the list
27294 * with g_list_free().
27299 * g_io_modules_load_all_in_directory_with_scope:
27300 * @dirname: (type filename): pathname for a directory containing modules
27302 * @scope: a scope to use when scanning the modules.
27304 * Loads all the modules in the specified directory.
27306 * If don't require all modules to be initialized (and thus registering
27307 * all gtypes) then you can use g_io_modules_scan_all_in_directory()
27308 * which allows delayed/lazy loading of modules.
27310 * Returns: (element-type GIOModule) (transfer full): a list of #GIOModules loaded
27311 * from the directory,
27312 * All the modules are loaded into memory, if you want to
27313 * unload them (enabling on-demand loading) you must call
27314 * g_type_module_unuse() on all the modules. Free the list
27315 * with g_list_free().
27321 * g_io_modules_scan_all_in_directory:
27322 * @dirname: (type filename): pathname for a directory containing modules
27325 * Scans all the modules in the specified directory, ensuring that
27326 * any extension point implemented by a module is registered.
27328 * This may not actually load and initialize all the types in each
27329 * module, some modules may be lazily loaded and initialized when
27330 * an extension point it implements is used with e.g.
27331 * g_io_extension_point_get_extensions() or
27332 * g_io_extension_point_get_extension_by_name().
27334 * If you need to guarantee that all types are loaded in all the modules,
27335 * use g_io_modules_load_all_in_directory().
27342 * g_io_modules_scan_all_in_directory_with_scope:
27343 * @dirname: (type filename): pathname for a directory containing modules
27345 * @scope: a scope to use when scanning the modules
27347 * Scans all the modules in the specified directory, ensuring that
27348 * any extension point implemented by a module is registered.
27350 * This may not actually load and initialize all the types in each
27351 * module, some modules may be lazily loaded and initialized when
27352 * an extension point it implements is used with e.g.
27353 * g_io_extension_point_get_extensions() or
27354 * g_io_extension_point_get_extension_by_name().
27356 * If you need to guarantee that all types are loaded in all the modules,
27357 * use g_io_modules_load_all_in_directory().
27364 * g_io_scheduler_cancel_all_jobs:
27366 * Cancels all cancellable I/O jobs.
27368 * A job is cancellable if a #GCancellable was passed into
27369 * g_io_scheduler_push_job().
27371 * Deprecated: You should never call this function, since you don't
27372 * know how other libraries in your program might be making use of
27378 * g_io_scheduler_job_send_to_mainloop:
27379 * @job: a #GIOSchedulerJob
27380 * @func: a #GSourceFunc callback that will be called in the original thread
27381 * @user_data: data to pass to @func
27382 * @notify: (nullable): a #GDestroyNotify for @user_data, or %NULL
27384 * Used from an I/O job to send a callback to be run in the thread
27385 * that the job was started from, waiting for the result (and thus
27386 * blocking the I/O job).
27388 * Returns: The return value of @func
27389 * Deprecated: Use g_main_context_invoke().
27394 * g_io_scheduler_job_send_to_mainloop_async:
27395 * @job: a #GIOSchedulerJob
27396 * @func: a #GSourceFunc callback that will be called in the original thread
27397 * @user_data: data to pass to @func
27398 * @notify: (nullable): a #GDestroyNotify for @user_data, or %NULL
27400 * Used from an I/O job to send a callback to be run asynchronously in
27401 * the thread that the job was started from. The callback will be run
27402 * when the main loop is available, but at that time the I/O job might
27403 * have finished. The return value from the callback is ignored.
27405 * Note that if you are passing the @user_data from g_io_scheduler_push_job()
27406 * on to this function you have to ensure that it is not freed before
27407 * @func is called, either by passing %NULL as @notify to
27408 * g_io_scheduler_push_job() or by using refcounting for @user_data.
27410 * Deprecated: Use g_main_context_invoke().
27415 * g_io_scheduler_push_job:
27416 * @job_func: a #GIOSchedulerJobFunc.
27417 * @user_data: data to pass to @job_func
27418 * @notify: (nullable): a #GDestroyNotify for @user_data, or %NULL
27419 * @io_priority: the [I/O priority][io-priority]
27421 * @cancellable: optional #GCancellable object, %NULL to ignore.
27423 * Schedules the I/O job to run in another thread.
27425 * @notify will be called on @user_data after @job_func has returned,
27426 * regardless whether the job was cancelled or has run to completion.
27428 * If @cancellable is not %NULL, it can be used to cancel the I/O job
27429 * by calling g_cancellable_cancel() or by calling
27430 * g_io_scheduler_cancel_all_jobs().
27432 * Deprecated: use #GThreadPool or g_task_run_in_thread()
27437 * g_io_stream_clear_pending:
27438 * @stream: a #GIOStream
27440 * Clears the pending flag on @stream.
27447 * g_io_stream_close:
27448 * @stream: a #GIOStream
27449 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore
27450 * @error: location to store the error occurring, or %NULL to ignore
27452 * Closes the stream, releasing resources related to it. This will also
27453 * close the individual input and output streams, if they are not already
27456 * Once the stream is closed, all other operations will return
27457 * %G_IO_ERROR_CLOSED. Closing a stream multiple times will not
27460 * Closing a stream will automatically flush any outstanding buffers
27463 * Streams will be automatically closed when the last reference
27464 * is dropped, but you might want to call this function to make sure
27465 * resources are released as early as possible.
27467 * Some streams might keep the backing store of the stream (e.g. a file
27468 * descriptor) open after the stream is closed. See the documentation for
27469 * the individual stream for details.
27471 * On failure the first error that happened will be reported, but the
27472 * close operation will finish as much as possible. A stream that failed
27473 * to close will still return %G_IO_ERROR_CLOSED for all operations.
27474 * Still, it is important to check and report the error to the user,
27475 * otherwise there might be a loss of data as all data might not be written.
27477 * If @cancellable is not NULL, then the operation can be cancelled by
27478 * triggering the cancellable object from another thread. If the operation
27479 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
27480 * Cancelling a close will still leave the stream closed, but some streams
27481 * can use a faster close that doesn't block to e.g. check errors.
27483 * The default implementation of this method just calls close on the
27484 * individual input/output streams.
27486 * Returns: %TRUE on success, %FALSE on failure
27492 * g_io_stream_close_async:
27493 * @stream: a #GIOStream
27494 * @io_priority: the io priority of the request
27495 * @cancellable: (nullable): optional cancellable object
27496 * @callback: (scope async): callback to call when the request is satisfied
27497 * @user_data: (closure): the data to pass to callback function
27499 * Requests an asynchronous close of the stream, releasing resources
27500 * related to it. When the operation is finished @callback will be
27501 * called. You can then call g_io_stream_close_finish() to get
27502 * the result of the operation.
27504 * For behaviour details see g_io_stream_close().
27506 * The asynchronous methods have a default fallback that uses threads
27507 * to implement asynchronicity, so they are optional for inheriting
27508 * classes. However, if you override one you must override all.
27515 * g_io_stream_close_finish:
27516 * @stream: a #GIOStream
27517 * @result: a #GAsyncResult
27518 * @error: a #GError location to store the error occurring, or %NULL to
27523 * Returns: %TRUE if stream was successfully closed, %FALSE otherwise.
27529 * g_io_stream_get_input_stream:
27530 * @stream: a #GIOStream
27532 * Gets the input stream for this object. This is used
27535 * Returns: (transfer none): a #GInputStream, owned by the #GIOStream.
27542 * g_io_stream_get_output_stream:
27543 * @stream: a #GIOStream
27545 * Gets the output stream for this object. This is used for
27548 * Returns: (transfer none): a #GOutputStream, owned by the #GIOStream.
27555 * g_io_stream_has_pending:
27556 * @stream: a #GIOStream
27558 * Checks if a stream has pending actions.
27560 * Returns: %TRUE if @stream has pending actions.
27566 * g_io_stream_is_closed:
27567 * @stream: a #GIOStream
27569 * Checks if a stream is closed.
27571 * Returns: %TRUE if the stream is closed.
27577 * g_io_stream_set_pending:
27578 * @stream: a #GIOStream
27579 * @error: a #GError location to store the error occurring, or %NULL to
27582 * Sets @stream to have actions pending. If the pending flag is
27583 * already set or @stream is closed, it will return %FALSE and set
27586 * Returns: %TRUE if pending was previously unset and is now set.
27592 * g_io_stream_splice_async:
27593 * @stream1: a #GIOStream.
27594 * @stream2: a #GIOStream.
27595 * @flags: a set of #GIOStreamSpliceFlags.
27596 * @io_priority: the io priority of the request.
27597 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
27598 * @callback: (scope async): a #GAsyncReadyCallback.
27599 * @user_data: (closure): user data passed to @callback.
27601 * Asynchronously splice the output stream of @stream1 to the input stream of
27602 * @stream2, and splice the output stream of @stream2 to the input stream of
27605 * When the operation is finished @callback will be called.
27606 * You can then call g_io_stream_splice_finish() to get the
27607 * result of the operation.
27614 * g_io_stream_splice_finish:
27615 * @result: a #GAsyncResult.
27616 * @error: a #GError location to store the error occurring, or %NULL to
27619 * Finishes an asynchronous io stream splice operation.
27621 * Returns: %TRUE on success, %FALSE otherwise.
27627 * g_keyfile_settings_backend_new:
27628 * @filename: the filename of the keyfile
27629 * @root_path: the path under which all settings keys appear
27630 * @root_group: (nullable): the group name corresponding to
27631 * @root_path, or %NULL
27633 * Creates a keyfile-backed #GSettingsBackend.
27635 * The filename of the keyfile to use is given by @filename.
27637 * All settings read to or written from the backend must fall under the
27638 * path given in @root_path (which must start and end with a slash and
27639 * not contain two consecutive slashes). @root_path may be "/".
27641 * If @root_group is non-%NULL then it specifies the name of the keyfile
27642 * group used for keys that are written directly below @root_path. For
27643 * example, if @root_path is "/apps/example/" and @root_group is
27644 * "toplevel", then settings the key "/apps/example/enabled" to a value
27645 * of %TRUE will cause the following to appear in the keyfile:
27652 * If @root_group is %NULL then it is not permitted to store keys
27653 * directly below the @root_path.
27655 * For keys not stored directly below @root_path (ie: in a sub-path),
27656 * the name of the subpath (with the final slash stripped) is used as
27657 * the name of the keyfile group. To continue the example, if
27658 * "/apps/example/profiles/default/font-size" were set to
27659 * 12 then the following would appear in the keyfile:
27662 * [profiles/default]
27666 * The backend will refuse writes (and return writability as being
27667 * %FALSE) for keys outside of @root_path and, in the event that
27668 * @root_group is %NULL, also for keys directly under @root_path.
27669 * Writes will also be refused if the backend detects that it has the
27670 * inability to rewrite the keyfile (ie: the containing directory is not
27673 * There is no checking done for your key namespace clashing with the
27674 * syntax of the key file format. For example, if you have '[' or ']'
27675 * characters in your path names or '=' in your key names you may be in
27678 * The backend reads default values from a keyfile called `defaults` in
27679 * the directory specified by the #GKeyfileSettingsBackend:defaults-dir property,
27680 * and a list of locked keys from a text file with the name `locks` in
27681 * the same location.
27683 * Returns: (transfer full): a keyfile-backed #GSettingsBackend
27688 * g_list_model_get_item: (skip)
27689 * @list: a #GListModel
27690 * @position: the position of the item to fetch
27692 * Get the item at @position. If @position is greater than the number of
27693 * items in @list, %NULL is returned.
27695 * %NULL is never returned for an index that is smaller than the length
27696 * of the list. See g_list_model_get_n_items().
27698 * Returns: (transfer full) (nullable): the item at @position.
27704 * g_list_model_get_item_type:
27705 * @list: a #GListModel
27707 * Gets the type of the items in @list. All items returned from
27708 * g_list_model_get_type() are of that type or a subtype, or are an
27709 * implementation of that interface.
27711 * The item type of a #GListModel can not change during the life of the
27714 * Returns: the #GType of the items contained in @list.
27720 * g_list_model_get_n_items:
27721 * @list: a #GListModel
27723 * Gets the number of items in @list.
27725 * Depending on the model implementation, calling this function may be
27726 * less efficient than iterating the list with increasing values for
27727 * @position until g_list_model_get_item() returns %NULL.
27729 * Returns: the number of items in @list.
27735 * g_list_model_get_object: (rename-to g_list_model_get_item)
27736 * @list: a #GListModel
27737 * @position: the position of the item to fetch
27739 * Get the item at @position. If @position is greater than the number of
27740 * items in @list, %NULL is returned.
27742 * %NULL is never returned for an index that is smaller than the length
27743 * of the list. See g_list_model_get_n_items().
27745 * Returns: (transfer full) (nullable): the object at @position.
27751 * g_list_model_items_changed:
27752 * @list: a #GListModel
27753 * @position: the position at which @list changed
27754 * @removed: the number of items removed
27755 * @added: the number of items added
27757 * Emits the #GListModel::items-changed signal on @list.
27759 * This function should only be called by classes implementing
27760 * #GListModel. It has to be called after the internal representation
27761 * of @list has been updated, because handlers connected to this signal
27762 * might query the new state of the list.
27764 * Implementations must only make changes to the model (as visible to
27765 * its consumer) in places that will not cause problems for that
27766 * consumer. For models that are driven directly by a write API (such
27767 * as #GListStore), changes can be reported in response to uses of that
27768 * API. For models that represent remote data, changes should only be
27769 * made from a fresh mainloop dispatch. It is particularly not
27770 * permitted to make changes in response to a call to the #GListModel
27773 * Stated another way: in general, it is assumed that code making a
27774 * series of accesses to the model via the API, without returning to the
27775 * mainloop, and without calling other code, will continue to view the
27776 * same contents of the model.
27783 * g_list_store_append:
27784 * @store: a #GListStore
27785 * @item: (type GObject): the new item
27787 * Appends @item to @store. @item must be of type #GListStore:item-type.
27789 * This function takes a ref on @item.
27791 * Use g_list_store_splice() to append multiple items at the same time
27799 * g_list_store_find:
27800 * @store: a #GListStore
27801 * @item: (type GObject): an item
27802 * @position: (out) (optional): the first position of @item, if it was found.
27804 * Looks up the given @item in the list store by looping over the items until
27805 * the first occurrence of @item. If @item was not found, then @position will
27806 * not be set, and this method will return %FALSE.
27808 * If you need to compare the two items with a custom comparison function, use
27809 * g_list_store_find_with_equal_func() with a custom #GEqualFunc instead.
27811 * Returns: Whether @store contains @item. If it was found, @position will be
27812 * set to the position where @item occurred for the first time.
27818 * g_list_store_find_with_equal_func:
27819 * @store: a #GListStore
27820 * @item: (type GObject): an item
27821 * @equal_func: (scope call): A custom equality check function
27822 * @position: (out) (optional): the first position of @item, if it was found.
27824 * Looks up the given @item in the list store by looping over the items and
27825 * comparing them with @compare_func until the first occurrence of @item which
27826 * matches. If @item was not found, then @position will not be set, and this
27827 * method will return %FALSE.
27829 * Returns: Whether @store contains @item. If it was found, @position will be
27830 * set to the position where @item occurred for the first time.
27836 * g_list_store_insert:
27837 * @store: a #GListStore
27838 * @position: the position at which to insert the new item
27839 * @item: (type GObject): the new item
27841 * Inserts @item into @store at @position. @item must be of type
27842 * #GListStore:item-type or derived from it. @position must be smaller
27843 * than the length of the list, or equal to it to append.
27845 * This function takes a ref on @item.
27847 * Use g_list_store_splice() to insert multiple items at the same time
27855 * g_list_store_insert_sorted:
27856 * @store: a #GListStore
27857 * @item: (type GObject): the new item
27858 * @compare_func: (scope call): pairwise comparison function for sorting
27859 * @user_data: (closure): user data for @compare_func
27861 * Inserts @item into @store at a position to be determined by the
27864 * The list must already be sorted before calling this function or the
27865 * result is undefined. Usually you would approach this by only ever
27866 * inserting items by way of this function.
27868 * This function takes a ref on @item.
27870 * Returns: the position at which @item was inserted
27876 * g_list_store_new:
27877 * @item_type: the #GType of items in the list
27879 * Creates a new #GListStore with items of type @item_type. @item_type
27880 * must be a subclass of #GObject.
27882 * Returns: a new #GListStore
27888 * g_list_store_remove:
27889 * @store: a #GListStore
27890 * @position: the position of the item that is to be removed
27892 * Removes the item from @store that is at @position. @position must be
27893 * smaller than the current length of the list.
27895 * Use g_list_store_splice() to remove multiple items at the same time
27903 * g_list_store_remove_all:
27904 * @store: a #GListStore
27906 * Removes all items from @store.
27913 * g_list_store_sort:
27914 * @store: a #GListStore
27915 * @compare_func: (scope call): pairwise comparison function for sorting
27916 * @user_data: (closure): user data for @compare_func
27918 * Sort the items in @store according to @compare_func.
27925 * g_list_store_splice:
27926 * @store: a #GListStore
27927 * @position: the position at which to make the change
27928 * @n_removals: the number of items to remove
27929 * @additions: (array length=n_additions) (element-type GObject): the items to add
27930 * @n_additions: the number of items to add
27932 * Changes @store by removing @n_removals items and adding @n_additions
27933 * items to it. @additions must contain @n_additions items of type
27934 * #GListStore:item-type. %NULL is not permitted.
27936 * This function is more efficient than g_list_store_insert() and
27937 * g_list_store_remove(), because it only emits
27938 * #GListModel::items-changed once for the change.
27940 * This function takes a ref on each item in @additions.
27942 * The parameters @position and @n_removals must be correct (ie:
27943 * @position + @n_removals must be less than or equal to the length of
27944 * the list at the time this function is called).
27951 * g_loadable_icon_load:
27952 * @icon: a #GLoadableIcon.
27953 * @size: an integer.
27954 * @type: (out) (optional): a location to store the type of the loaded
27955 * icon, %NULL to ignore.
27956 * @cancellable: (nullable): optional #GCancellable object, %NULL to
27958 * @error: a #GError location to store the error occurring, or %NULL
27961 * Loads a loadable icon. For the asynchronous version of this function,
27962 * see g_loadable_icon_load_async().
27964 * Returns: (transfer full): a #GInputStream to read the icon from.
27969 * g_loadable_icon_load_async:
27970 * @icon: a #GLoadableIcon.
27971 * @size: an integer.
27972 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
27973 * @callback: (scope async): a #GAsyncReadyCallback to call when the
27974 * request is satisfied
27975 * @user_data: (closure): the data to pass to callback function
27977 * Loads an icon asynchronously. To finish this function, see
27978 * g_loadable_icon_load_finish(). For the synchronous, blocking
27979 * version of this function, see g_loadable_icon_load().
27984 * g_loadable_icon_load_finish:
27985 * @icon: a #GLoadableIcon.
27986 * @res: a #GAsyncResult.
27987 * @type: (out) (optional): a location to store the type of the loaded
27988 * icon, %NULL to ignore.
27989 * @error: a #GError location to store the error occurring, or %NULL to
27992 * Finishes an asynchronous icon load started in g_loadable_icon_load_async().
27994 * Returns: (transfer full): a #GInputStream to read the icon from.
28001 * Returns a new #GVfs handle for a local vfs.
28003 * Returns: a new #GVfs handle.
28008 * g_memory_input_stream_add_bytes:
28009 * @stream: a #GMemoryInputStream
28010 * @bytes: input data
28012 * Appends @bytes to data that can be read from the input stream.
28019 * g_memory_input_stream_add_data:
28020 * @stream: a #GMemoryInputStream
28021 * @data: (array length=len) (element-type guint8) (transfer full): input data
28022 * @len: length of the data, may be -1 if @data is a nul-terminated string
28023 * @destroy: (nullable): function that is called to free @data, or %NULL
28025 * Appends @data to data that can be read from the input stream
28030 * g_memory_input_stream_new:
28032 * Creates a new empty #GMemoryInputStream.
28034 * Returns: a new #GInputStream
28039 * g_memory_input_stream_new_from_bytes:
28040 * @bytes: a #GBytes
28042 * Creates a new #GMemoryInputStream with data from the given @bytes.
28044 * Returns: new #GInputStream read from @bytes
28050 * g_memory_input_stream_new_from_data:
28051 * @data: (array length=len) (element-type guint8) (transfer full): input data
28052 * @len: length of the data, may be -1 if @data is a nul-terminated string
28053 * @destroy: (nullable): function that is called to free @data, or %NULL
28055 * Creates a new #GMemoryInputStream with data in memory of a given size.
28057 * Returns: new #GInputStream read from @data of @len bytes.
28062 * g_memory_monitor_dup_default:
28064 * Gets a reference to the default #GMemoryMonitor for the system.
28066 * Returns: (not nullable) (transfer full): a new reference to the default #GMemoryMonitor
28072 * g_memory_output_stream_get_data:
28073 * @ostream: a #GMemoryOutputStream
28075 * Gets any loaded data from the @ostream.
28077 * Note that the returned pointer may become invalid on the next
28078 * write or truncate operation on the stream.
28080 * Returns: (transfer none): pointer to the stream's data, or %NULL if the data
28086 * g_memory_output_stream_get_data_size:
28087 * @ostream: a #GMemoryOutputStream
28089 * Returns the number of bytes from the start up to including the last
28090 * byte written in the stream that has not been truncated away.
28092 * Returns: the number of bytes written to the stream
28098 * g_memory_output_stream_get_size:
28099 * @ostream: a #GMemoryOutputStream
28101 * Gets the size of the currently allocated data area (available from
28102 * g_memory_output_stream_get_data()).
28104 * You probably don't want to use this function on resizable streams.
28105 * See g_memory_output_stream_get_data_size() instead. For resizable
28106 * streams the size returned by this function is an implementation
28107 * detail and may be change at any time in response to operations on the
28110 * If the stream is fixed-sized (ie: no realloc was passed to
28111 * g_memory_output_stream_new()) then this is the maximum size of the
28112 * stream and further writes will return %G_IO_ERROR_NO_SPACE.
28114 * In any case, if you want the number of bytes currently written to the
28115 * stream, use g_memory_output_stream_get_data_size().
28117 * Returns: the number of bytes allocated for the data buffer
28122 * g_memory_output_stream_new: (skip)
28123 * @data: (nullable): pointer to a chunk of memory to use, or %NULL
28124 * @size: the size of @data
28125 * @realloc_function: (nullable): a function with realloc() semantics (like g_realloc())
28126 * to be called when @data needs to be grown, or %NULL
28127 * @destroy_function: (nullable): a function to be called on @data when the stream is
28128 * finalized, or %NULL
28130 * Creates a new #GMemoryOutputStream.
28132 * In most cases this is not the function you want. See
28133 * g_memory_output_stream_new_resizable() instead.
28135 * If @data is non-%NULL, the stream will use that for its internal storage.
28137 * If @realloc_fn is non-%NULL, it will be used for resizing the internal
28138 * storage when necessary and the stream will be considered resizable.
28139 * In that case, the stream will start out being (conceptually) empty.
28140 * @size is used only as a hint for how big @data is. Specifically,
28141 * seeking to the end of a newly-created stream will seek to zero, not
28142 * @size. Seeking past the end of the stream and then writing will
28143 * introduce a zero-filled gap.
28145 * If @realloc_fn is %NULL then the stream is fixed-sized. Seeking to
28146 * the end will seek to @size exactly. Writing past the end will give
28147 * an 'out of space' error. Attempting to seek past the end will fail.
28148 * Unlike the resizable case, seeking to an offset within the stream and
28149 * writing will preserve the bytes passed in as @data before that point
28150 * and will return them as part of g_memory_output_stream_steal_data().
28151 * If you intend to seek you should probably therefore ensure that @data
28152 * is properly initialised.
28154 * It is probably only meaningful to provide @data and @size in the case
28155 * that you want a fixed-sized stream. Put another way: if @realloc_fn
28156 * is non-%NULL then it makes most sense to give @data as %NULL and
28157 * @size as 0 (allowing #GMemoryOutputStream to do the initial
28158 * allocation for itself).
28160 * |[<!-- language="C" -->
28161 * // a stream that can grow
28162 * stream = g_memory_output_stream_new (NULL, 0, realloc, free);
28164 * // another stream that can grow
28165 * stream2 = g_memory_output_stream_new (NULL, 0, g_realloc, g_free);
28167 * // a fixed-size stream
28168 * data = malloc (200);
28169 * stream3 = g_memory_output_stream_new (data, 200, NULL, free);
28172 * Returns: A newly created #GMemoryOutputStream object.
28177 * g_memory_output_stream_new_resizable:
28179 * Creates a new #GMemoryOutputStream, using g_realloc() and g_free()
28180 * for memory allocation.
28187 * g_memory_output_stream_steal_as_bytes:
28188 * @ostream: a #GMemoryOutputStream
28190 * Returns data from the @ostream as a #GBytes. @ostream must be
28191 * closed before calling this function.
28193 * Returns: (transfer full): the stream's data
28199 * g_memory_output_stream_steal_data:
28200 * @ostream: a #GMemoryOutputStream
28202 * Gets any loaded data from the @ostream. Ownership of the data
28203 * is transferred to the caller; when no longer needed it must be
28204 * freed using the free function set in @ostream's
28205 * #GMemoryOutputStream:destroy-function property.
28207 * @ostream must be closed before calling this function.
28209 * Returns: (transfer full): the stream's data, or %NULL if it has previously
28216 * g_memory_settings_backend_new:
28218 * Creates a memory-backed #GSettingsBackend.
28220 * This backend allows changes to settings, but does not write them
28221 * to any backing storage, so the next time you run your application,
28222 * the memory backend will start out with the default values again.
28224 * Returns: (transfer full): a newly created #GSettingsBackend
28232 * @label: (nullable): the section label, or %NULL
28233 * @detailed_action: (nullable): the detailed action string, or %NULL
28235 * Convenience function for appending a normal menu item to the end of
28236 * @menu. Combine g_menu_item_new() and g_menu_insert_item() for a more
28237 * flexible alternative.
28244 * g_menu_append_item:
28246 * @item: a #GMenuItem to append
28248 * Appends @item to the end of @menu.
28250 * See g_menu_insert_item() for more information.
28257 * g_menu_append_section:
28259 * @label: (nullable): the section label, or %NULL
28260 * @section: a #GMenuModel with the items of the section
28262 * Convenience function for appending a section menu item to the end of
28263 * @menu. Combine g_menu_item_new_section() and g_menu_insert_item() for a
28264 * more flexible alternative.
28271 * g_menu_append_submenu:
28273 * @label: (nullable): the section label, or %NULL
28274 * @submenu: a #GMenuModel with the items of the submenu
28276 * Convenience function for appending a submenu menu item to the end of
28277 * @menu. Combine g_menu_item_new_submenu() and g_menu_insert_item() for a
28278 * more flexible alternative.
28285 * g_menu_attribute_iter_get_name:
28286 * @iter: a #GMenuAttributeIter
28288 * Gets the name of the attribute at the current iterator position, as
28291 * The iterator is not advanced.
28293 * Returns: the name of the attribute
28299 * g_menu_attribute_iter_get_next:
28300 * @iter: a #GMenuAttributeIter
28301 * @out_name: (out) (optional) (transfer none): the type of the attribute
28302 * @value: (out) (optional) (transfer full): the attribute value
28304 * This function combines g_menu_attribute_iter_next() with
28305 * g_menu_attribute_iter_get_name() and g_menu_attribute_iter_get_value().
28307 * First the iterator is advanced to the next (possibly first) attribute.
28308 * If that fails, then %FALSE is returned and there are no other
28311 * If successful, @name and @value are set to the name and value of the
28312 * attribute that has just been advanced to. At this point,
28313 * g_menu_attribute_iter_get_name() and g_menu_attribute_iter_get_value() will
28314 * return the same values again.
28316 * The value returned in @name remains valid for as long as the iterator
28317 * remains at the current position. The value returned in @value must
28318 * be unreffed using g_variant_unref() when it is no longer in use.
28320 * Returns: %TRUE on success, or %FALSE if there is no additional
28327 * g_menu_attribute_iter_get_value:
28328 * @iter: a #GMenuAttributeIter
28330 * Gets the value of the attribute at the current iterator position.
28332 * The iterator is not advanced.
28334 * Returns: (transfer full): the value of the current attribute
28340 * g_menu_attribute_iter_next:
28341 * @iter: a #GMenuAttributeIter
28343 * Attempts to advance the iterator to the next (possibly first)
28346 * %TRUE is returned on success, or %FALSE if there are no more
28349 * You must call this function when you first acquire the iterator
28350 * to advance it to the first attribute (and determine if the first
28351 * attribute exists at all).
28353 * Returns: %TRUE on success, or %FALSE when there are no more attributes
28362 * Marks @menu as frozen.
28364 * After the menu is frozen, it is an error to attempt to make any
28365 * changes to it. In effect this means that the #GMenu API must no
28368 * This function causes g_menu_model_is_mutable() to begin returning
28369 * %FALSE, which has some positive performance implications.
28378 * @position: the position at which to insert the item
28379 * @label: (nullable): the section label, or %NULL
28380 * @detailed_action: (nullable): the detailed action string, or %NULL
28382 * Convenience function for inserting a normal menu item into @menu.
28383 * Combine g_menu_item_new() and g_menu_insert_item() for a more flexible
28391 * g_menu_insert_item:
28393 * @position: the position at which to insert the item
28394 * @item: the #GMenuItem to insert
28396 * Inserts @item into @menu.
28398 * The "insertion" is actually done by copying all of the attribute and
28399 * link values of @item and using them to form a new item within @menu.
28400 * As such, @item itself is not really inserted, but rather, a menu item
28401 * that is exactly the same as the one presently described by @item.
28403 * This means that @item is essentially useless after the insertion
28404 * occurs. Any changes you make to it are ignored unless it is inserted
28405 * again (at which point its updated values will be copied).
28407 * You should probably just free @item once you're done.
28409 * There are many convenience functions to take care of common cases.
28410 * See g_menu_insert(), g_menu_insert_section() and
28411 * g_menu_insert_submenu() as well as "prepend" and "append" variants of
28412 * each of these functions.
28419 * g_menu_insert_section:
28421 * @position: the position at which to insert the item
28422 * @label: (nullable): the section label, or %NULL
28423 * @section: a #GMenuModel with the items of the section
28425 * Convenience function for inserting a section menu item into @menu.
28426 * Combine g_menu_item_new_section() and g_menu_insert_item() for a more
28427 * flexible alternative.
28434 * g_menu_insert_submenu:
28436 * @position: the position at which to insert the item
28437 * @label: (nullable): the section label, or %NULL
28438 * @submenu: a #GMenuModel with the items of the submenu
28440 * Convenience function for inserting a submenu menu item into @menu.
28441 * Combine g_menu_item_new_submenu() and g_menu_insert_item() for a more
28442 * flexible alternative.
28449 * g_menu_item_get_attribute:
28450 * @menu_item: a #GMenuItem
28451 * @attribute: the attribute name to query
28452 * @format_string: a #GVariant format string
28453 * @...: positional parameters, as per @format_string
28455 * Queries the named @attribute on @menu_item.
28457 * If the attribute exists and matches the #GVariantType corresponding
28458 * to @format_string then @format_string is used to deconstruct the
28459 * value into the positional parameters and %TRUE is returned.
28461 * If the attribute does not exist, or it does exist but has the wrong
28462 * type, then the positional parameters are ignored and %FALSE is
28465 * Returns: %TRUE if the named attribute was found with the expected
28472 * g_menu_item_get_attribute_value:
28473 * @menu_item: a #GMenuItem
28474 * @attribute: the attribute name to query
28475 * @expected_type: (nullable): the expected type of the attribute
28477 * Queries the named @attribute on @menu_item.
28479 * If @expected_type is specified and the attribute does not have this
28480 * type, %NULL is returned. %NULL is also returned if the attribute
28481 * simply does not exist.
28483 * Returns: (nullable) (transfer full): the attribute value, or %NULL
28489 * g_menu_item_get_link:
28490 * @menu_item: a #GMenuItem
28491 * @link: the link name to query
28493 * Queries the named @link on @menu_item.
28495 * Returns: (nullable) (transfer full): the link, or %NULL
28502 * @label: (nullable): the section label, or %NULL
28503 * @detailed_action: (nullable): the detailed action string, or %NULL
28505 * Creates a new #GMenuItem.
28507 * If @label is non-%NULL it is used to set the "label" attribute of the
28510 * If @detailed_action is non-%NULL it is used to set the "action" and
28511 * possibly the "target" attribute of the new item. See
28512 * g_menu_item_set_detailed_action() for more information.
28514 * Returns: a new #GMenuItem
28520 * g_menu_item_new_from_model:
28521 * @model: a #GMenuModel
28522 * @item_index: the index of an item in @model
28524 * Creates a #GMenuItem as an exact copy of an existing menu item in a
28527 * @item_index must be valid (ie: be sure to call
28528 * g_menu_model_get_n_items() first).
28530 * Returns: a new #GMenuItem.
28536 * g_menu_item_new_section:
28537 * @label: (nullable): the section label, or %NULL
28538 * @section: a #GMenuModel with the items of the section
28540 * Creates a new #GMenuItem representing a section.
28542 * This is a convenience API around g_menu_item_new() and
28543 * g_menu_item_set_section().
28545 * The effect of having one menu appear as a section of another is
28546 * exactly as it sounds: the items from @section become a direct part of
28547 * the menu that @menu_item is added to.
28549 * Visual separation is typically displayed between two non-empty
28550 * sections. If @label is non-%NULL then it will be encorporated into
28551 * this visual indication. This allows for labeled subsections of a
28554 * As a simple example, consider a typical "Edit" menu from a simple
28555 * program. It probably contains an "Undo" and "Redo" item, followed by
28556 * a separator, followed by "Cut", "Copy" and "Paste".
28558 * This would be accomplished by creating three #GMenu instances. The
28559 * first would be populated with the "Undo" and "Redo" items, and the
28560 * second with the "Cut", "Copy" and "Paste" items. The first and
28561 * second menus would then be added as submenus of the third. In XML
28562 * format, this would look something like the following:
28564 * <menu id='edit-menu'>
28566 * <item label='Undo'/>
28567 * <item label='Redo'/>
28570 * <item label='Cut'/>
28571 * <item label='Copy'/>
28572 * <item label='Paste'/>
28577 * The following example is exactly equivalent. It is more illustrative
28578 * of the exact relationship between the menus and items (keeping in
28579 * mind that the 'link' element defines a new menu that is linked to the
28580 * containing one). The style of the second example is more verbose and
28581 * difficult to read (and therefore not recommended except for the
28582 * purpose of understanding what is really going on).
28584 * <menu id='edit-menu'>
28586 * <link name='section'>
28587 * <item label='Undo'/>
28588 * <item label='Redo'/>
28592 * <link name='section'>
28593 * <item label='Cut'/>
28594 * <item label='Copy'/>
28595 * <item label='Paste'/>
28601 * Returns: a new #GMenuItem
28607 * g_menu_item_new_submenu:
28608 * @label: (nullable): the section label, or %NULL
28609 * @submenu: a #GMenuModel with the items of the submenu
28611 * Creates a new #GMenuItem representing a submenu.
28613 * This is a convenience API around g_menu_item_new() and
28614 * g_menu_item_set_submenu().
28616 * Returns: a new #GMenuItem
28622 * g_menu_item_set_action_and_target:
28623 * @menu_item: a #GMenuItem
28624 * @action: (nullable): the name of the action for this item
28625 * @format_string: (nullable): a GVariant format string
28626 * @...: positional parameters, as per @format_string
28628 * Sets or unsets the "action" and "target" attributes of @menu_item.
28630 * If @action is %NULL then both the "action" and "target" attributes
28631 * are unset (and @format_string is ignored along with the positional
28634 * If @action is non-%NULL then the "action" attribute is set.
28635 * @format_string is then inspected. If it is non-%NULL then the proper
28636 * position parameters are collected to create a #GVariant instance to
28637 * use as the target value. If it is %NULL then the positional
28638 * parameters are ignored and the "target" attribute is unset.
28640 * See also g_menu_item_set_action_and_target_value() for an equivalent
28641 * call that directly accepts a #GVariant. See
28642 * g_menu_item_set_detailed_action() for a more convenient version that
28643 * works with string-typed targets.
28645 * See also g_menu_item_set_action_and_target_value() for a
28646 * description of the semantics of the action and target attributes.
28653 * g_menu_item_set_action_and_target_value:
28654 * @menu_item: a #GMenuItem
28655 * @action: (nullable): the name of the action for this item
28656 * @target_value: (nullable): a #GVariant to use as the action target
28658 * Sets or unsets the "action" and "target" attributes of @menu_item.
28660 * If @action is %NULL then both the "action" and "target" attributes
28661 * are unset (and @target_value is ignored).
28663 * If @action is non-%NULL then the "action" attribute is set. The
28664 * "target" attribute is then set to the value of @target_value if it is
28665 * non-%NULL or unset otherwise.
28667 * Normal menu items (ie: not submenu, section or other custom item
28668 * types) are expected to have the "action" attribute set to identify
28669 * the action that they are associated with. The state type of the
28670 * action help to determine the disposition of the menu item. See
28671 * #GAction and #GActionGroup for an overview of actions.
28673 * In general, clicking on the menu item will result in activation of
28674 * the named action with the "target" attribute given as the parameter
28675 * to the action invocation. If the "target" attribute is not set then
28676 * the action is invoked with no parameter.
28678 * If the action has no state then the menu item is usually drawn as a
28679 * plain menu item (ie: with no additional decoration).
28681 * If the action has a boolean state then the menu item is usually drawn
28682 * as a toggle menu item (ie: with a checkmark or equivalent
28683 * indication). The item should be marked as 'toggled' or 'checked'
28684 * when the boolean state is %TRUE.
28686 * If the action has a string state then the menu item is usually drawn
28687 * as a radio menu item (ie: with a radio bullet or equivalent
28688 * indication). The item should be marked as 'selected' when the string
28689 * state is equal to the value of the @target property.
28691 * See g_menu_item_set_action_and_target() or
28692 * g_menu_item_set_detailed_action() for two equivalent calls that are
28693 * probably more convenient for most uses.
28700 * g_menu_item_set_attribute:
28701 * @menu_item: a #GMenuItem
28702 * @attribute: the attribute to set
28703 * @format_string: (nullable): a #GVariant format string, or %NULL
28704 * @...: positional parameters, as per @format_string
28706 * Sets or unsets an attribute on @menu_item.
28708 * The attribute to set or unset is specified by @attribute. This
28709 * can be one of the standard attribute names %G_MENU_ATTRIBUTE_LABEL,
28710 * %G_MENU_ATTRIBUTE_ACTION, %G_MENU_ATTRIBUTE_TARGET, or a custom
28712 * Attribute names are restricted to lowercase characters, numbers
28713 * and '-'. Furthermore, the names must begin with a lowercase character,
28714 * must not end with a '-', and must not contain consecutive dashes.
28716 * If @format_string is non-%NULL then the proper position parameters
28717 * are collected to create a #GVariant instance to use as the attribute
28718 * value. If it is %NULL then the positional parameterrs are ignored
28719 * and the named attribute is unset.
28721 * See also g_menu_item_set_attribute_value() for an equivalent call
28722 * that directly accepts a #GVariant.
28729 * g_menu_item_set_attribute_value:
28730 * @menu_item: a #GMenuItem
28731 * @attribute: the attribute to set
28732 * @value: (nullable): a #GVariant to use as the value, or %NULL
28734 * Sets or unsets an attribute on @menu_item.
28736 * The attribute to set or unset is specified by @attribute. This
28737 * can be one of the standard attribute names %G_MENU_ATTRIBUTE_LABEL,
28738 * %G_MENU_ATTRIBUTE_ACTION, %G_MENU_ATTRIBUTE_TARGET, or a custom
28740 * Attribute names are restricted to lowercase characters, numbers
28741 * and '-'. Furthermore, the names must begin with a lowercase character,
28742 * must not end with a '-', and must not contain consecutive dashes.
28744 * must consist only of lowercase
28745 * ASCII characters, digits and '-'.
28747 * If @value is non-%NULL then it is used as the new value for the
28748 * attribute. If @value is %NULL then the attribute is unset. If
28749 * the @value #GVariant is floating, it is consumed.
28751 * See also g_menu_item_set_attribute() for a more convenient way to do
28759 * g_menu_item_set_detailed_action:
28760 * @menu_item: a #GMenuItem
28761 * @detailed_action: the "detailed" action string
28763 * Sets the "action" and possibly the "target" attribute of @menu_item.
28765 * The format of @detailed_action is the same format parsed by
28766 * g_action_parse_detailed_name().
28768 * See g_menu_item_set_action_and_target() or
28769 * g_menu_item_set_action_and_target_value() for more flexible (but
28770 * slightly less convenient) alternatives.
28772 * See also g_menu_item_set_action_and_target_value() for a description of
28773 * the semantics of the action and target attributes.
28780 * g_menu_item_set_icon:
28781 * @menu_item: a #GMenuItem
28782 * @icon: a #GIcon, or %NULL
28784 * Sets (or unsets) the icon on @menu_item.
28786 * This call is the same as calling g_icon_serialize() and using the
28787 * result as the value to g_menu_item_set_attribute_value() for
28788 * %G_MENU_ATTRIBUTE_ICON.
28790 * This API is only intended for use with "noun" menu items; things like
28791 * bookmarks or applications in an "Open With" menu. Don't use it on
28792 * menu items corresponding to verbs (eg: stock icons for 'Save' or
28795 * If @icon is %NULL then the icon is unset.
28802 * g_menu_item_set_label:
28803 * @menu_item: a #GMenuItem
28804 * @label: (nullable): the label to set, or %NULL to unset
28806 * Sets or unsets the "label" attribute of @menu_item.
28808 * If @label is non-%NULL it is used as the label for the menu item. If
28809 * it is %NULL then the label attribute is unset.
28816 * g_menu_item_set_link:
28817 * @menu_item: a #GMenuItem
28818 * @link: type of link to establish or unset
28819 * @model: (nullable): the #GMenuModel to link to (or %NULL to unset)
28821 * Creates a link from @menu_item to @model if non-%NULL, or unsets it.
28823 * Links are used to establish a relationship between a particular menu
28824 * item and another menu. For example, %G_MENU_LINK_SUBMENU is used to
28825 * associate a submenu with a particular menu item, and %G_MENU_LINK_SECTION
28826 * is used to create a section. Other types of link can be used, but there
28827 * is no guarantee that clients will be able to make sense of them.
28828 * Link types are restricted to lowercase characters, numbers
28829 * and '-'. Furthermore, the names must begin with a lowercase character,
28830 * must not end with a '-', and must not contain consecutive dashes.
28837 * g_menu_item_set_section:
28838 * @menu_item: a #GMenuItem
28839 * @section: (nullable): a #GMenuModel, or %NULL
28841 * Sets or unsets the "section" link of @menu_item to @section.
28843 * The effect of having one menu appear as a section of another is
28844 * exactly as it sounds: the items from @section become a direct part of
28845 * the menu that @menu_item is added to. See g_menu_item_new_section()
28846 * for more information about what it means for a menu item to be a
28854 * g_menu_item_set_submenu:
28855 * @menu_item: a #GMenuItem
28856 * @submenu: (nullable): a #GMenuModel, or %NULL
28858 * Sets or unsets the "submenu" link of @menu_item to @submenu.
28860 * If @submenu is non-%NULL, it is linked to. If it is %NULL then the
28863 * The effect of having one menu appear as a submenu of another is
28864 * exactly as it sounds.
28871 * g_menu_link_iter_get_name:
28872 * @iter: a #GMenuLinkIter
28874 * Gets the name of the link at the current iterator position.
28876 * The iterator is not advanced.
28878 * Returns: the type of the link
28884 * g_menu_link_iter_get_next:
28885 * @iter: a #GMenuLinkIter
28886 * @out_link: (out) (optional) (transfer none): the name of the link
28887 * @value: (out) (optional) (transfer full): the linked #GMenuModel
28889 * This function combines g_menu_link_iter_next() with
28890 * g_menu_link_iter_get_name() and g_menu_link_iter_get_value().
28892 * First the iterator is advanced to the next (possibly first) link.
28893 * If that fails, then %FALSE is returned and there are no other effects.
28895 * If successful, @out_link and @value are set to the name and #GMenuModel
28896 * of the link that has just been advanced to. At this point,
28897 * g_menu_link_iter_get_name() and g_menu_link_iter_get_value() will return the
28898 * same values again.
28900 * The value returned in @out_link remains valid for as long as the iterator
28901 * remains at the current position. The value returned in @value must
28902 * be unreffed using g_object_unref() when it is no longer in use.
28904 * Returns: %TRUE on success, or %FALSE if there is no additional link
28910 * g_menu_link_iter_get_value:
28911 * @iter: a #GMenuLinkIter
28913 * Gets the linked #GMenuModel at the current iterator position.
28915 * The iterator is not advanced.
28917 * Returns: (transfer full): the #GMenuModel that is linked to
28923 * g_menu_link_iter_next:
28924 * @iter: a #GMenuLinkIter
28926 * Attempts to advance the iterator to the next (possibly first)
28929 * %TRUE is returned on success, or %FALSE if there are no more links.
28931 * You must call this function when you first acquire the iterator to
28932 * advance it to the first link (and determine if the first link exists
28935 * Returns: %TRUE on success, or %FALSE when there are no more links
28941 * g_menu_model_get_item_attribute:
28942 * @model: a #GMenuModel
28943 * @item_index: the index of the item
28944 * @attribute: the attribute to query
28945 * @format_string: a #GVariant format string
28946 * @...: positional parameters, as per @format_string
28948 * Queries item at position @item_index in @model for the attribute
28949 * specified by @attribute.
28951 * If the attribute exists and matches the #GVariantType corresponding
28952 * to @format_string then @format_string is used to deconstruct the
28953 * value into the positional parameters and %TRUE is returned.
28955 * If the attribute does not exist, or it does exist but has the wrong
28956 * type, then the positional parameters are ignored and %FALSE is
28959 * This function is a mix of g_menu_model_get_item_attribute_value() and
28960 * g_variant_get(), followed by a g_variant_unref(). As such,
28961 * @format_string must make a complete copy of the data (since the
28962 * #GVariant may go away after the call to g_variant_unref()). In
28963 * particular, no '&' characters are allowed in @format_string.
28965 * Returns: %TRUE if the named attribute was found with the expected
28972 * g_menu_model_get_item_attribute_value:
28973 * @model: a #GMenuModel
28974 * @item_index: the index of the item
28975 * @attribute: the attribute to query
28976 * @expected_type: (nullable): the expected type of the attribute, or
28979 * Queries the item at position @item_index in @model for the attribute
28980 * specified by @attribute.
28982 * If @expected_type is non-%NULL then it specifies the expected type of
28983 * the attribute. If it is %NULL then any type will be accepted.
28985 * If the attribute exists and matches @expected_type (or if the
28986 * expected type is unspecified) then the value is returned.
28988 * If the attribute does not exist, or does not match the expected type
28989 * then %NULL is returned.
28991 * Returns: (nullable) (transfer full): the value of the attribute
28997 * g_menu_model_get_item_link:
28998 * @model: a #GMenuModel
28999 * @item_index: the index of the item
29000 * @link: the link to query
29002 * Queries the item at position @item_index in @model for the link
29003 * specified by @link.
29005 * If the link exists, the linked #GMenuModel is returned. If the link
29006 * does not exist, %NULL is returned.
29008 * Returns: (nullable) (transfer full): the linked #GMenuModel, or %NULL
29014 * g_menu_model_get_n_items:
29015 * @model: a #GMenuModel
29017 * Query the number of items in @model.
29019 * Returns: the number of items
29025 * g_menu_model_is_mutable:
29026 * @model: a #GMenuModel
29028 * Queries if @model is mutable.
29030 * An immutable #GMenuModel will never emit the #GMenuModel::items-changed
29031 * signal. Consumers of the model may make optimisations accordingly.
29033 * Returns: %TRUE if the model is mutable (ie: "items-changed" may be
29040 * g_menu_model_items_changed:
29041 * @model: a #GMenuModel
29042 * @position: the position of the change
29043 * @removed: the number of items removed
29044 * @added: the number of items added
29046 * Requests emission of the #GMenuModel::items-changed signal on @model.
29048 * This function should never be called except by #GMenuModel
29049 * subclasses. Any other calls to this function will very likely lead
29050 * to a violation of the interface of the model.
29052 * The implementation should update its internal representation of the
29053 * menu before emitting the signal. The implementation should further
29054 * expect to receive queries about the new state of the menu (and
29055 * particularly added menu items) while signal handlers are running.
29057 * The implementation must dispatch this call directly from a mainloop
29058 * entry and not in response to calls -- particularly those from the
29059 * #GMenuModel API. Said another way: the menu must not change while
29060 * user code is running without returning to the mainloop.
29067 * g_menu_model_iterate_item_attributes:
29068 * @model: a #GMenuModel
29069 * @item_index: the index of the item
29071 * Creates a #GMenuAttributeIter to iterate over the attributes of
29072 * the item at position @item_index in @model.
29074 * You must free the iterator with g_object_unref() when you are done.
29076 * Returns: (transfer full): a new #GMenuAttributeIter
29082 * g_menu_model_iterate_item_links:
29083 * @model: a #GMenuModel
29084 * @item_index: the index of the item
29086 * Creates a #GMenuLinkIter to iterate over the links of the item at
29087 * position @item_index in @model.
29089 * You must free the iterator with g_object_unref() when you are done.
29091 * Returns: (transfer full): a new #GMenuLinkIter
29099 * Creates a new #GMenu.
29101 * The new menu has no items.
29103 * Returns: a new #GMenu
29111 * @label: (nullable): the section label, or %NULL
29112 * @detailed_action: (nullable): the detailed action string, or %NULL
29114 * Convenience function for prepending a normal menu item to the start
29115 * of @menu. Combine g_menu_item_new() and g_menu_insert_item() for a more
29116 * flexible alternative.
29123 * g_menu_prepend_item:
29125 * @item: a #GMenuItem to prepend
29127 * Prepends @item to the start of @menu.
29129 * See g_menu_insert_item() for more information.
29136 * g_menu_prepend_section:
29138 * @label: (nullable): the section label, or %NULL
29139 * @section: a #GMenuModel with the items of the section
29141 * Convenience function for prepending a section menu item to the start
29142 * of @menu. Combine g_menu_item_new_section() and g_menu_insert_item() for
29143 * a more flexible alternative.
29150 * g_menu_prepend_submenu:
29152 * @label: (nullable): the section label, or %NULL
29153 * @submenu: a #GMenuModel with the items of the submenu
29155 * Convenience function for prepending a submenu menu item to the start
29156 * of @menu. Combine g_menu_item_new_submenu() and g_menu_insert_item() for
29157 * a more flexible alternative.
29166 * @position: the position of the item to remove
29168 * Removes an item from the menu.
29170 * @position gives the index of the item to remove.
29172 * It is an error if position is not in range the range from 0 to one
29173 * less than the number of items in the menu.
29175 * It is not possible to remove items by identity since items are added
29176 * to the menu simply by copying their links and attributes (ie:
29177 * identity of the item itself is not preserved).
29184 * g_menu_remove_all:
29187 * Removes all items in the menu.
29194 * g_mount_can_eject:
29195 * @mount: a #GMount.
29197 * Checks if @mount can be ejected.
29199 * Returns: %TRUE if the @mount can be ejected.
29204 * g_mount_can_unmount:
29205 * @mount: a #GMount.
29207 * Checks if @mount can be unmounted.
29209 * Returns: %TRUE if the @mount can be unmounted.
29215 * @mount: a #GMount.
29216 * @flags: flags affecting the unmount if required for eject
29217 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
29218 * @callback: (nullable): a #GAsyncReadyCallback, or %NULL.
29219 * @user_data: user data passed to @callback.
29221 * Ejects a mount. This is an asynchronous operation, and is
29222 * finished by calling g_mount_eject_finish() with the @mount
29223 * and #GAsyncResult data returned in the @callback.
29225 * Deprecated: 2.22: Use g_mount_eject_with_operation() instead.
29230 * g_mount_eject_finish:
29231 * @mount: a #GMount.
29232 * @result: a #GAsyncResult.
29233 * @error: a #GError location to store the error occurring, or %NULL to
29236 * Finishes ejecting a mount. If any errors occurred during the operation,
29237 * @error will be set to contain the errors and %FALSE will be returned.
29239 * Returns: %TRUE if the mount was successfully ejected. %FALSE otherwise.
29240 * Deprecated: 2.22: Use g_mount_eject_with_operation_finish() instead.
29245 * g_mount_eject_with_operation:
29246 * @mount: a #GMount.
29247 * @flags: flags affecting the unmount if required for eject
29248 * @mount_operation: (nullable): a #GMountOperation or %NULL to avoid
29249 * user interaction.
29250 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
29251 * @callback: (nullable): a #GAsyncReadyCallback, or %NULL.
29252 * @user_data: user data passed to @callback.
29254 * Ejects a mount. This is an asynchronous operation, and is
29255 * finished by calling g_mount_eject_with_operation_finish() with the @mount
29256 * and #GAsyncResult data returned in the @callback.
29263 * g_mount_eject_with_operation_finish:
29264 * @mount: a #GMount.
29265 * @result: a #GAsyncResult.
29266 * @error: a #GError location to store the error occurring, or %NULL to
29269 * Finishes ejecting a mount. If any errors occurred during the operation,
29270 * @error will be set to contain the errors and %FALSE will be returned.
29272 * Returns: %TRUE if the mount was successfully ejected. %FALSE otherwise.
29278 * g_mount_get_default_location:
29279 * @mount: a #GMount.
29281 * Gets the default location of @mount. The default location of the given
29282 * @mount is a path that reflects the main entry point for the user (e.g.
29283 * the home directory, or the root of the volume).
29285 * Returns: (transfer full): a #GFile.
29286 * The returned object should be unreffed with
29287 * g_object_unref() when no longer needed.
29292 * g_mount_get_drive:
29293 * @mount: a #GMount.
29295 * Gets the drive for the @mount.
29297 * This is a convenience method for getting the #GVolume and then
29298 * using that object to get the #GDrive.
29300 * Returns: (transfer full) (nullable): a #GDrive or %NULL if @mount is not
29301 * associated with a volume or a drive.
29302 * The returned object should be unreffed with
29303 * g_object_unref() when no longer needed.
29308 * g_mount_get_icon:
29309 * @mount: a #GMount.
29311 * Gets the icon for @mount.
29313 * Returns: (transfer full): a #GIcon.
29314 * The returned object should be unreffed with
29315 * g_object_unref() when no longer needed.
29320 * g_mount_get_name:
29321 * @mount: a #GMount.
29323 * Gets the name of @mount.
29325 * Returns: the name for the given @mount.
29326 * The returned string should be freed with g_free()
29327 * when no longer needed.
29332 * g_mount_get_root:
29333 * @mount: a #GMount.
29335 * Gets the root directory on @mount.
29337 * Returns: (transfer full): a #GFile.
29338 * The returned object should be unreffed with
29339 * g_object_unref() when no longer needed.
29344 * g_mount_get_sort_key:
29345 * @mount: A #GMount.
29347 * Gets the sort key for @mount, if any.
29349 * Returns: (nullable): Sorting key for @mount or %NULL if no such key is available.
29355 * g_mount_get_symbolic_icon:
29356 * @mount: a #GMount.
29358 * Gets the symbolic icon for @mount.
29360 * Returns: (transfer full): a #GIcon.
29361 * The returned object should be unreffed with
29362 * g_object_unref() when no longer needed.
29368 * g_mount_get_uuid:
29369 * @mount: a #GMount.
29371 * Gets the UUID for the @mount. The reference is typically based on
29372 * the file system UUID for the mount in question and should be
29373 * considered an opaque string. Returns %NULL if there is no UUID
29376 * Returns: (nullable) (transfer full): the UUID for @mount or %NULL if no UUID
29378 * The returned string should be freed with g_free()
29379 * when no longer needed.
29384 * g_mount_get_volume:
29385 * @mount: a #GMount.
29387 * Gets the volume for the @mount.
29389 * Returns: (transfer full) (nullable): a #GVolume or %NULL if @mount is not
29390 * associated with a volume.
29391 * The returned object should be unreffed with
29392 * g_object_unref() when no longer needed.
29397 * g_mount_guess_content_type:
29398 * @mount: a #GMount
29399 * @force_rescan: Whether to force a rescan of the content.
29400 * Otherwise a cached result will be used if available
29401 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore
29402 * @callback: a #GAsyncReadyCallback
29403 * @user_data: user data passed to @callback
29405 * Tries to guess the type of content stored on @mount. Returns one or
29406 * more textual identifiers of well-known content types (typically
29407 * prefixed with "x-content/"), e.g. x-content/image-dcf for camera
29408 * memory cards. See the
29409 * [shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec)
29410 * specification for more on x-content types.
29412 * This is an asynchronous operation (see
29413 * g_mount_guess_content_type_sync() for the synchronous version), and
29414 * is finished by calling g_mount_guess_content_type_finish() with the
29415 * @mount and #GAsyncResult data returned in the @callback.
29422 * g_mount_guess_content_type_finish:
29423 * @mount: a #GMount
29424 * @result: a #GAsyncResult
29425 * @error: a #GError location to store the error occurring, or %NULL to
29428 * Finishes guessing content types of @mount. If any errors occurred
29429 * during the operation, @error will be set to contain the errors and
29430 * %FALSE will be returned. In particular, you may get an
29431 * %G_IO_ERROR_NOT_SUPPORTED if the mount does not support content
29434 * Returns: (transfer full) (element-type utf8): a %NULL-terminated array of content types or %NULL on error.
29435 * Caller should free this array with g_strfreev() when done with it.
29441 * g_mount_guess_content_type_sync:
29442 * @mount: a #GMount
29443 * @force_rescan: Whether to force a rescan of the content.
29444 * Otherwise a cached result will be used if available
29445 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore
29446 * @error: a #GError location to store the error occurring, or %NULL to
29449 * Tries to guess the type of content stored on @mount. Returns one or
29450 * more textual identifiers of well-known content types (typically
29451 * prefixed with "x-content/"), e.g. x-content/image-dcf for camera
29452 * memory cards. See the
29453 * [shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec)
29454 * specification for more on x-content types.
29456 * This is a synchronous operation and as such may block doing IO;
29457 * see g_mount_guess_content_type() for the asynchronous version.
29459 * Returns: (transfer full) (element-type utf8): a %NULL-terminated array of content types or %NULL on error.
29460 * Caller should free this array with g_strfreev() when done with it.
29466 * g_mount_is_shadowed:
29467 * @mount: A #GMount.
29469 * Determines if @mount is shadowed. Applications or libraries should
29470 * avoid displaying @mount in the user interface if it is shadowed.
29472 * A mount is said to be shadowed if there exists one or more user
29473 * visible objects (currently #GMount objects) with a root that is
29474 * inside the root of @mount.
29476 * One application of shadow mounts is when exposing a single file
29477 * system that is used to address several logical volumes. In this
29478 * situation, a #GVolumeMonitor implementation would create two
29479 * #GVolume objects (for example, one for the camera functionality of
29480 * the device and one for a SD card reader on the device) with
29481 * activation URIs `gphoto2://[usb:001,002]/store1/`
29482 * and `gphoto2://[usb:001,002]/store2/`. When the
29483 * underlying mount (with root
29484 * `gphoto2://[usb:001,002]/`) is mounted, said
29485 * #GVolumeMonitor implementation would create two #GMount objects
29486 * (each with their root matching the corresponding volume activation
29487 * root) that would shadow the original mount.
29489 * The proxy monitor in GVfs 2.26 and later, automatically creates and
29490 * manage shadow mounts (and shadows the underlying mount) if the
29491 * activation root on a #GVolume is set.
29493 * Returns: %TRUE if @mount is shadowed.
29499 * g_mount_operation_get_anonymous:
29500 * @op: a #GMountOperation.
29502 * Check to see whether the mount operation is being used
29503 * for an anonymous user.
29505 * Returns: %TRUE if mount operation is anonymous.
29510 * g_mount_operation_get_choice:
29511 * @op: a #GMountOperation.
29513 * Gets a choice from the mount operation.
29515 * Returns: an integer containing an index of the user's choice from
29516 * the choice's list, or `0`.
29521 * g_mount_operation_get_domain:
29522 * @op: a #GMountOperation.
29524 * Gets the domain of the mount operation.
29526 * Returns: (nullable): a string set to the domain.
29531 * g_mount_operation_get_is_tcrypt_hidden_volume:
29532 * @op: a #GMountOperation.
29534 * Check to see whether the mount operation is being used
29535 * for a TCRYPT hidden volume.
29537 * Returns: %TRUE if mount operation is for hidden volume.
29543 * g_mount_operation_get_is_tcrypt_system_volume:
29544 * @op: a #GMountOperation.
29546 * Check to see whether the mount operation is being used
29547 * for a TCRYPT system volume.
29549 * Returns: %TRUE if mount operation is for system volume.
29555 * g_mount_operation_get_password:
29556 * @op: a #GMountOperation.
29558 * Gets a password from the mount operation.
29560 * Returns: (nullable): a string containing the password within @op.
29565 * g_mount_operation_get_password_save:
29566 * @op: a #GMountOperation.
29568 * Gets the state of saving passwords for the mount operation.
29570 * Returns: a #GPasswordSave flag.
29575 * g_mount_operation_get_pim:
29576 * @op: a #GMountOperation.
29578 * Gets a PIM from the mount operation.
29580 * Returns: The VeraCrypt PIM within @op.
29586 * g_mount_operation_get_username:
29587 * @op: a #GMountOperation.
29589 * Get the user name from the mount operation.
29591 * Returns: (nullable): a string containing the user name.
29596 * g_mount_operation_new:
29598 * Creates a new mount operation.
29600 * Returns: a #GMountOperation.
29605 * g_mount_operation_reply:
29606 * @op: a #GMountOperation
29607 * @result: a #GMountOperationResult
29609 * Emits the #GMountOperation::reply signal.
29614 * g_mount_operation_set_anonymous:
29615 * @op: a #GMountOperation.
29616 * @anonymous: boolean value.
29618 * Sets the mount operation to use an anonymous user if @anonymous is %TRUE.
29623 * g_mount_operation_set_choice:
29624 * @op: a #GMountOperation.
29625 * @choice: an integer.
29627 * Sets a default choice for the mount operation.
29632 * g_mount_operation_set_domain:
29633 * @op: a #GMountOperation.
29634 * @domain: (nullable): the domain to set.
29636 * Sets the mount operation's domain.
29641 * g_mount_operation_set_is_tcrypt_hidden_volume:
29642 * @op: a #GMountOperation.
29643 * @hidden_volume: boolean value.
29645 * Sets the mount operation to use a hidden volume if @hidden_volume is %TRUE.
29652 * g_mount_operation_set_is_tcrypt_system_volume:
29653 * @op: a #GMountOperation.
29654 * @system_volume: boolean value.
29656 * Sets the mount operation to use a system volume if @system_volume is %TRUE.
29663 * g_mount_operation_set_password:
29664 * @op: a #GMountOperation.
29665 * @password: (nullable): password to set.
29667 * Sets the mount operation's password to @password.
29672 * g_mount_operation_set_password_save:
29673 * @op: a #GMountOperation.
29674 * @save: a set of #GPasswordSave flags.
29676 * Sets the state of saving passwords for the mount operation.
29681 * g_mount_operation_set_pim:
29682 * @op: a #GMountOperation.
29683 * @pim: an unsigned integer.
29685 * Sets the mount operation's PIM to @pim.
29692 * g_mount_operation_set_username:
29693 * @op: a #GMountOperation.
29694 * @username: (nullable): input username.
29696 * Sets the user name within @op to @username.
29702 * @mount: a #GMount.
29703 * @flags: flags affecting the operation
29704 * @mount_operation: (nullable): a #GMountOperation or %NULL to avoid
29705 * user interaction.
29706 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
29707 * @callback: (nullable): a #GAsyncReadyCallback, or %NULL.
29708 * @user_data: user data passed to @callback.
29710 * Remounts a mount. This is an asynchronous operation, and is
29711 * finished by calling g_mount_remount_finish() with the @mount
29712 * and #GAsyncResults data returned in the @callback.
29714 * Remounting is useful when some setting affecting the operation
29715 * of the volume has been changed, as these may need a remount to
29716 * take affect. While this is semantically equivalent with unmounting
29717 * and then remounting not all backends might need to actually be
29723 * g_mount_remount_finish:
29724 * @mount: a #GMount.
29725 * @result: a #GAsyncResult.
29726 * @error: a #GError location to store the error occurring, or %NULL to
29729 * Finishes remounting a mount. If any errors occurred during the operation,
29730 * @error will be set to contain the errors and %FALSE will be returned.
29732 * Returns: %TRUE if the mount was successfully remounted. %FALSE otherwise.
29738 * @mount: A #GMount.
29740 * Increments the shadow count on @mount. Usually used by
29741 * #GVolumeMonitor implementations when creating a shadow mount for
29742 * @mount, see g_mount_is_shadowed() for more information. The caller
29743 * will need to emit the #GMount::changed signal on @mount manually.
29751 * @mount: a #GMount.
29752 * @flags: flags affecting the operation
29753 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
29754 * @callback: (nullable): a #GAsyncReadyCallback, or %NULL.
29755 * @user_data: user data passed to @callback.
29757 * Unmounts a mount. This is an asynchronous operation, and is
29758 * finished by calling g_mount_unmount_finish() with the @mount
29759 * and #GAsyncResult data returned in the @callback.
29761 * Deprecated: 2.22: Use g_mount_unmount_with_operation() instead.
29766 * g_mount_unmount_finish:
29767 * @mount: a #GMount.
29768 * @result: a #GAsyncResult.
29769 * @error: a #GError location to store the error occurring, or %NULL to
29772 * Finishes unmounting a mount. If any errors occurred during the operation,
29773 * @error will be set to contain the errors and %FALSE will be returned.
29775 * Returns: %TRUE if the mount was successfully unmounted. %FALSE otherwise.
29776 * Deprecated: 2.22: Use g_mount_unmount_with_operation_finish() instead.
29781 * g_mount_unmount_with_operation:
29782 * @mount: a #GMount.
29783 * @flags: flags affecting the operation
29784 * @mount_operation: (nullable): a #GMountOperation or %NULL to avoid
29785 * user interaction.
29786 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
29787 * @callback: (nullable): a #GAsyncReadyCallback, or %NULL.
29788 * @user_data: user data passed to @callback.
29790 * Unmounts a mount. This is an asynchronous operation, and is
29791 * finished by calling g_mount_unmount_with_operation_finish() with the @mount
29792 * and #GAsyncResult data returned in the @callback.
29799 * g_mount_unmount_with_operation_finish:
29800 * @mount: a #GMount.
29801 * @result: a #GAsyncResult.
29802 * @error: a #GError location to store the error occurring, or %NULL to
29805 * Finishes unmounting a mount. If any errors occurred during the operation,
29806 * @error will be set to contain the errors and %FALSE will be returned.
29808 * Returns: %TRUE if the mount was successfully unmounted. %FALSE otherwise.
29814 * g_mount_unshadow:
29815 * @mount: A #GMount.
29817 * Decrements the shadow count on @mount. Usually used by
29818 * #GVolumeMonitor implementations when destroying a shadow mount for
29819 * @mount, see g_mount_is_shadowed() for more information. The caller
29820 * will need to emit the #GMount::changed signal on @mount manually.
29827 * g_native_socket_address_new:
29828 * @native: a native address object
29829 * @len: the length of @native, in bytes
29831 * Creates a new #GNativeSocketAddress for @native and @len.
29833 * Returns: a new #GNativeSocketAddress
29839 * g_network_address_get_hostname:
29840 * @addr: a #GNetworkAddress
29842 * Gets @addr's hostname. This might be either UTF-8 or ASCII-encoded,
29843 * depending on what @addr was created with.
29845 * Returns: @addr's hostname
29851 * g_network_address_get_port:
29852 * @addr: a #GNetworkAddress
29854 * Gets @addr's port number
29856 * Returns: @addr's port (which may be 0)
29862 * g_network_address_get_scheme:
29863 * @addr: a #GNetworkAddress
29865 * Gets @addr's scheme
29867 * Returns: (nullable): @addr's scheme (%NULL if not built from URI)
29873 * g_network_address_new:
29874 * @hostname: the hostname
29877 * Creates a new #GSocketConnectable for connecting to the given
29878 * @hostname and @port.
29880 * Note that depending on the configuration of the machine, a
29881 * @hostname of `localhost` may refer to the IPv4 loopback address
29882 * only, or to both IPv4 and IPv6; use
29883 * g_network_address_new_loopback() to create a #GNetworkAddress that
29884 * is guaranteed to resolve to both addresses.
29886 * Returns: (transfer full) (type GNetworkAddress): the new #GNetworkAddress
29892 * g_network_address_new_loopback:
29895 * Creates a new #GSocketConnectable for connecting to the local host
29896 * over a loopback connection to the given @port. This is intended for
29897 * use in connecting to local services which may be running on IPv4 or
29900 * The connectable will return IPv4 and IPv6 loopback addresses,
29901 * regardless of how the host resolves `localhost`. By contrast,
29902 * g_network_address_new() will often only return an IPv4 address when
29903 * resolving `localhost`, and an IPv6 address for `localhost6`.
29905 * g_network_address_get_hostname() will always return `localhost` for
29906 * a #GNetworkAddress created with this constructor.
29908 * Returns: (transfer full) (type GNetworkAddress): the new #GNetworkAddress
29914 * g_network_address_parse:
29915 * @host_and_port: the hostname and optionally a port
29916 * @default_port: the default port if not in @host_and_port
29917 * @error: a pointer to a #GError, or %NULL
29919 * Creates a new #GSocketConnectable for connecting to the given
29920 * @hostname and @port. May fail and return %NULL in case
29921 * parsing @host_and_port fails.
29923 * @host_and_port may be in any of a number of recognised formats; an IPv6
29924 * address, an IPv4 address, or a domain name (in which case a DNS
29925 * lookup is performed). Quoting with [] is supported for all address
29926 * types. A port override may be specified in the usual way with a
29929 * If no port is specified in @host_and_port then @default_port will be
29930 * used as the port number to connect to.
29932 * In general, @host_and_port is expected to be provided by the user
29933 * (allowing them to give the hostname, and a port override if necessary)
29934 * and @default_port is expected to be provided by the application.
29936 * (The port component of @host_and_port can also be specified as a
29937 * service name rather than as a numeric port, but this functionality
29938 * is deprecated, because it depends on the contents of /etc/services,
29939 * which is generally quite sparse on platforms other than Linux.)
29941 * Returns: (transfer full) (type GNetworkAddress): the new
29942 * #GNetworkAddress, or %NULL on error
29948 * g_network_address_parse_uri:
29949 * @uri: the hostname and optionally a port
29950 * @default_port: The default port if none is found in the URI
29951 * @error: a pointer to a #GError, or %NULL
29953 * Creates a new #GSocketConnectable for connecting to the given
29954 * @uri. May fail and return %NULL in case parsing @uri fails.
29956 * Using this rather than g_network_address_new() or
29957 * g_network_address_parse() allows #GSocketClient to determine
29958 * when to use application-specific proxy protocols.
29960 * Returns: (transfer full) (type GNetworkAddress): the new
29961 * #GNetworkAddress, or %NULL on error
29967 * g_network_monitor_base_add_network:
29968 * @monitor: the #GNetworkMonitorBase
29969 * @network: (transfer none): a #GInetAddressMask
29971 * Adds @network to @monitor's list of available networks.
29978 * g_network_monitor_base_remove_network:
29979 * @monitor: the #GNetworkMonitorBase
29980 * @network: a #GInetAddressMask
29982 * Removes @network from @monitor's list of available networks.
29989 * g_network_monitor_base_set_networks:
29990 * @monitor: the #GNetworkMonitorBase
29991 * @networks: (array length=length): an array of #GInetAddressMask
29992 * @length: length of @networks
29994 * Drops @monitor's current list of available networks and replaces
29995 * it with @networks.
30000 * g_network_monitor_can_reach:
30001 * @monitor: a #GNetworkMonitor
30002 * @connectable: a #GSocketConnectable
30003 * @cancellable: (nullable): a #GCancellable, or %NULL
30004 * @error: return location for a #GError, or %NULL
30006 * Attempts to determine whether or not the host pointed to by
30007 * @connectable can be reached, without actually trying to connect to
30010 * This may return %TRUE even when #GNetworkMonitor:network-available
30011 * is %FALSE, if, for example, @monitor can determine that
30012 * @connectable refers to a host on a local network.
30014 * If @monitor believes that an attempt to connect to @connectable
30015 * will succeed, it will return %TRUE. Otherwise, it will return
30016 * %FALSE and set @error to an appropriate error (such as
30017 * %G_IO_ERROR_HOST_UNREACHABLE).
30019 * Note that although this does not attempt to connect to
30020 * @connectable, it may still block for a brief period of time (eg,
30021 * trying to do multicast DNS on the local network), so if you do not
30022 * want to block, you should use g_network_monitor_can_reach_async().
30024 * Returns: %TRUE if @connectable is reachable, %FALSE if not.
30030 * g_network_monitor_can_reach_async:
30031 * @monitor: a #GNetworkMonitor
30032 * @connectable: a #GSocketConnectable
30033 * @cancellable: (nullable): a #GCancellable, or %NULL
30034 * @callback: (scope async): a #GAsyncReadyCallback to call when the
30035 * request is satisfied
30036 * @user_data: (closure): the data to pass to callback function
30038 * Asynchronously attempts to determine whether or not the host
30039 * pointed to by @connectable can be reached, without actually
30040 * trying to connect to it.
30042 * For more details, see g_network_monitor_can_reach().
30044 * When the operation is finished, @callback will be called.
30045 * You can then call g_network_monitor_can_reach_finish()
30046 * to get the result of the operation.
30051 * g_network_monitor_can_reach_finish:
30052 * @monitor: a #GNetworkMonitor
30053 * @result: a #GAsyncResult
30054 * @error: return location for errors, or %NULL
30056 * Finishes an async network connectivity test.
30057 * See g_network_monitor_can_reach_async().
30059 * Returns: %TRUE if network is reachable, %FALSE if not.
30064 * g_network_monitor_get_connectivity:
30065 * @monitor: the #GNetworkMonitor
30067 * Gets a more detailed networking state than
30068 * g_network_monitor_get_network_available().
30070 * If #GNetworkMonitor:network-available is %FALSE, then the
30071 * connectivity state will be %G_NETWORK_CONNECTIVITY_LOCAL.
30073 * If #GNetworkMonitor:network-available is %TRUE, then the
30074 * connectivity state will be %G_NETWORK_CONNECTIVITY_FULL (if there
30075 * is full Internet connectivity), %G_NETWORK_CONNECTIVITY_LIMITED (if
30076 * the host has a default route, but appears to be unable to actually
30077 * reach the full Internet), or %G_NETWORK_CONNECTIVITY_PORTAL (if the
30078 * host is trapped behind a "captive portal" that requires some sort
30079 * of login or acknowledgement before allowing full Internet access).
30081 * Note that in the case of %G_NETWORK_CONNECTIVITY_LIMITED and
30082 * %G_NETWORK_CONNECTIVITY_PORTAL, it is possible that some sites are
30083 * reachable but others are not. In this case, applications can
30084 * attempt to connect to remote servers, but should gracefully fall
30085 * back to their "offline" behavior if the connection attempt fails.
30087 * Returns: the network connectivity state
30093 * g_network_monitor_get_default:
30095 * Gets the default #GNetworkMonitor for the system.
30097 * Returns: (not nullable) (transfer none): a #GNetworkMonitor, which will be
30098 * a dummy object if no network monitor is available
30104 * g_network_monitor_get_network_available:
30105 * @monitor: the #GNetworkMonitor
30107 * Checks if the network is available. "Available" here means that the
30108 * system has a default route available for at least one of IPv4 or
30109 * IPv6. It does not necessarily imply that the public Internet is
30110 * reachable. See #GNetworkMonitor:network-available for more details.
30112 * Returns: whether the network is available
30118 * g_network_monitor_get_network_metered:
30119 * @monitor: the #GNetworkMonitor
30121 * Checks if the network is metered.
30122 * See #GNetworkMonitor:network-metered for more details.
30124 * Returns: whether the connection is metered
30130 * g_network_service_get_domain:
30131 * @srv: a #GNetworkService
30133 * Gets the domain that @srv serves. This might be either UTF-8 or
30134 * ASCII-encoded, depending on what @srv was created with.
30136 * Returns: @srv's domain name
30142 * g_network_service_get_protocol:
30143 * @srv: a #GNetworkService
30145 * Gets @srv's protocol name (eg, "tcp").
30147 * Returns: @srv's protocol name
30153 * g_network_service_get_scheme:
30154 * @srv: a #GNetworkService
30156 * Gets the URI scheme used to resolve proxies. By default, the service name
30157 * is used as scheme.
30159 * Returns: @srv's scheme name
30165 * g_network_service_get_service:
30166 * @srv: a #GNetworkService
30168 * Gets @srv's service name (eg, "ldap").
30170 * Returns: @srv's service name
30176 * g_network_service_new:
30177 * @service: the service type to look up (eg, "ldap")
30178 * @protocol: the networking protocol to use for @service (eg, "tcp")
30179 * @domain: the DNS domain to look up the service in
30181 * Creates a new #GNetworkService representing the given @service,
30182 * @protocol, and @domain. This will initially be unresolved; use the
30183 * #GSocketConnectable interface to resolve it.
30185 * Returns: (transfer full) (type GNetworkService): a new #GNetworkService
30191 * g_network_service_set_scheme:
30192 * @srv: a #GNetworkService
30193 * @scheme: a URI scheme
30195 * Set's the URI scheme used to resolve proxies. By default, the service name
30196 * is used as scheme.
30203 * g_networking_init:
30205 * Initializes the platform networking libraries (eg, on Windows, this
30206 * calls WSAStartup()). GLib will call this itself if it is needed, so
30207 * you only need to call it if you directly call system networking
30208 * functions (without calling any GLib networking functions first).
30215 * g_notification_add_button:
30216 * @notification: a #GNotification
30217 * @label: label of the button
30218 * @detailed_action: a detailed action name
30220 * Adds a button to @notification that activates the action in
30221 * @detailed_action when clicked. That action must be an
30222 * application-wide action (starting with "app."). If @detailed_action
30223 * contains a target, the action will be activated with that target as
30226 * See g_action_parse_detailed_name() for a description of the format
30227 * for @detailed_action.
30234 * g_notification_add_button_with_target: (skip)
30235 * @notification: a #GNotification
30236 * @label: label of the button
30237 * @action: an action name
30238 * @target_format: (nullable): a #GVariant format string, or %NULL
30239 * @...: positional parameters, as determined by @target_format
30241 * Adds a button to @notification that activates @action when clicked.
30242 * @action must be an application-wide action (it must start with "app.").
30244 * If @target_format is given, it is used to collect remaining
30245 * positional parameters into a #GVariant instance, similar to
30246 * g_variant_new(). @action will be activated with that #GVariant as its
30254 * g_notification_add_button_with_target_value: (rename-to g_notification_add_button_with_target)
30255 * @notification: a #GNotification
30256 * @label: label of the button
30257 * @action: an action name
30258 * @target: (nullable): a #GVariant to use as @action's parameter, or %NULL
30260 * Adds a button to @notification that activates @action when clicked.
30261 * @action must be an application-wide action (it must start with "app.").
30263 * If @target is non-%NULL, @action will be activated with @target as
30271 * g_notification_new:
30272 * @title: the title of the notification
30274 * Creates a new #GNotification with @title as its title.
30276 * After populating @notification with more details, it can be sent to
30277 * the desktop shell with g_application_send_notification(). Changing
30278 * any properties after this call will not have any effect until
30279 * resending @notification.
30281 * Returns: a new #GNotification instance
30287 * g_notification_set_body:
30288 * @notification: a #GNotification
30289 * @body: (nullable): the new body for @notification, or %NULL
30291 * Sets the body of @notification to @body.
30298 * g_notification_set_category:
30299 * @notification: a #GNotification
30300 * @category: (nullable): the category for @notification, or %NULL for no category
30302 * Sets the type of @notification to @category. Categories have a main
30303 * type like `email`, `im` or `device` and can have a detail separated
30304 * by a `.`, e.g. `im.received` or `email.arrived`. Setting the category
30305 * helps the notification server to select proper feedback to the user.
30307 * Standard categories are [listed in the specification](https://specifications.freedesktop.org/notification-spec/latest/ar01s06.html).
30314 * g_notification_set_default_action:
30315 * @notification: a #GNotification
30316 * @detailed_action: a detailed action name
30318 * Sets the default action of @notification to @detailed_action. This
30319 * action is activated when the notification is clicked on.
30321 * The action in @detailed_action must be an application-wide action (it
30322 * must start with "app."). If @detailed_action contains a target, the
30323 * given action will be activated with that target as its parameter.
30324 * See g_action_parse_detailed_name() for a description of the format
30325 * for @detailed_action.
30327 * When no default action is set, the application that the notification
30328 * was sent on is activated.
30335 * g_notification_set_default_action_and_target: (skip)
30336 * @notification: a #GNotification
30337 * @action: an action name
30338 * @target_format: (nullable): a #GVariant format string, or %NULL
30339 * @...: positional parameters, as determined by @target_format
30341 * Sets the default action of @notification to @action. This action is
30342 * activated when the notification is clicked on. It must be an
30343 * application-wide action (it must start with "app.").
30345 * If @target_format is given, it is used to collect remaining
30346 * positional parameters into a #GVariant instance, similar to
30347 * g_variant_new(). @action will be activated with that #GVariant as its
30350 * When no default action is set, the application that the notification
30351 * was sent on is activated.
30358 * g_notification_set_default_action_and_target_value: (rename-to g_notification_set_default_action_and_target)
30359 * @notification: a #GNotification
30360 * @action: an action name
30361 * @target: (nullable): a #GVariant to use as @action's parameter, or %NULL
30363 * Sets the default action of @notification to @action. This action is
30364 * activated when the notification is clicked on. It must be an
30365 * application-wide action (start with "app.").
30367 * If @target is non-%NULL, @action will be activated with @target as
30370 * When no default action is set, the application that the notification
30371 * was sent on is activated.
30378 * g_notification_set_icon:
30379 * @notification: a #GNotification
30380 * @icon: the icon to be shown in @notification, as a #GIcon
30382 * Sets the icon of @notification to @icon.
30389 * g_notification_set_priority:
30390 * @notification: a #GNotification
30391 * @priority: a #GNotificationPriority
30393 * Sets the priority of @notification to @priority. See
30394 * #GNotificationPriority for possible values.
30399 * g_notification_set_title:
30400 * @notification: a #GNotification
30401 * @title: the new title for @notification
30403 * Sets the title of @notification to @title.
30410 * g_notification_set_urgent:
30411 * @notification: a #GNotification
30412 * @urgent: %TRUE if @notification is urgent
30414 * Deprecated in favor of g_notification_set_priority().
30417 * Deprecated: 2.42: Since 2.42, this has been deprecated in favour of
30418 * g_notification_set_priority().
30423 * g_null_settings_backend_new:
30425 * Creates a readonly #GSettingsBackend.
30427 * This backend does not allow changes to settings, so all settings
30428 * will always have their default values.
30430 * Returns: (transfer full): a newly created #GSettingsBackend
30436 * g_output_stream_clear_pending:
30437 * @stream: output stream
30439 * Clears the pending flag on @stream.
30444 * g_output_stream_close:
30445 * @stream: A #GOutputStream.
30446 * @cancellable: (nullable): optional cancellable object
30447 * @error: location to store the error occurring, or %NULL to ignore
30449 * Closes the stream, releasing resources related to it.
30451 * Once the stream is closed, all other operations will return %G_IO_ERROR_CLOSED.
30452 * Closing a stream multiple times will not return an error.
30454 * Closing a stream will automatically flush any outstanding buffers in the
30457 * Streams will be automatically closed when the last reference
30458 * is dropped, but you might want to call this function to make sure
30459 * resources are released as early as possible.
30461 * Some streams might keep the backing store of the stream (e.g. a file descriptor)
30462 * open after the stream is closed. See the documentation for the individual
30463 * stream for details.
30465 * On failure the first error that happened will be reported, but the close
30466 * operation will finish as much as possible. A stream that failed to
30467 * close will still return %G_IO_ERROR_CLOSED for all operations. Still, it
30468 * is important to check and report the error to the user, otherwise
30469 * there might be a loss of data as all data might not be written.
30471 * If @cancellable is not %NULL, then the operation can be cancelled by
30472 * triggering the cancellable object from another thread. If the operation
30473 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
30474 * Cancelling a close will still leave the stream closed, but there some streams
30475 * can use a faster close that doesn't block to e.g. check errors. On
30476 * cancellation (as with any error) there is no guarantee that all written
30477 * data will reach the target.
30479 * Returns: %TRUE on success, %FALSE on failure
30484 * g_output_stream_close_async:
30485 * @stream: A #GOutputStream.
30486 * @io_priority: the io priority of the request.
30487 * @cancellable: (nullable): optional cancellable object
30488 * @callback: (scope async): callback to call when the request is satisfied
30489 * @user_data: (closure): the data to pass to callback function
30491 * Requests an asynchronous close of the stream, releasing resources
30492 * related to it. When the operation is finished @callback will be
30493 * called. You can then call g_output_stream_close_finish() to get
30494 * the result of the operation.
30496 * For behaviour details see g_output_stream_close().
30498 * The asynchronous methods have a default fallback that uses threads
30499 * to implement asynchronicity, so they are optional for inheriting
30500 * classes. However, if you override one you must override all.
30505 * g_output_stream_close_finish:
30506 * @stream: a #GOutputStream.
30507 * @result: a #GAsyncResult.
30508 * @error: a #GError location to store the error occurring, or %NULL to
30511 * Closes an output stream.
30513 * Returns: %TRUE if stream was successfully closed, %FALSE otherwise.
30518 * g_output_stream_flush:
30519 * @stream: a #GOutputStream.
30520 * @cancellable: (nullable): optional cancellable object
30521 * @error: location to store the error occurring, or %NULL to ignore
30523 * Forces a write of all user-space buffered data for the given
30524 * @stream. Will block during the operation. Closing the stream will
30525 * implicitly cause a flush.
30527 * This function is optional for inherited classes.
30529 * If @cancellable is not %NULL, then the operation can be cancelled by
30530 * triggering the cancellable object from another thread. If the operation
30531 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
30533 * Returns: %TRUE on success, %FALSE on error
30538 * g_output_stream_flush_async:
30539 * @stream: a #GOutputStream.
30540 * @io_priority: the io priority of the request.
30541 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
30542 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
30543 * @user_data: (closure): the data to pass to callback function
30545 * Forces an asynchronous write of all user-space buffered data for
30546 * the given @stream.
30547 * For behaviour details see g_output_stream_flush().
30549 * When the operation is finished @callback will be
30550 * called. You can then call g_output_stream_flush_finish() to get the
30551 * result of the operation.
30556 * g_output_stream_flush_finish:
30557 * @stream: a #GOutputStream.
30558 * @result: a GAsyncResult.
30559 * @error: a #GError location to store the error occurring, or %NULL to
30562 * Finishes flushing an output stream.
30564 * Returns: %TRUE if flush operation succeeded, %FALSE otherwise.
30569 * g_output_stream_has_pending:
30570 * @stream: a #GOutputStream.
30572 * Checks if an output stream has pending actions.
30574 * Returns: %TRUE if @stream has pending actions.
30579 * g_output_stream_is_closed:
30580 * @stream: a #GOutputStream.
30582 * Checks if an output stream has already been closed.
30584 * Returns: %TRUE if @stream is closed. %FALSE otherwise.
30589 * g_output_stream_is_closing:
30590 * @stream: a #GOutputStream.
30592 * Checks if an output stream is being closed. This can be
30593 * used inside e.g. a flush implementation to see if the
30594 * flush (or other i/o operation) is called from within
30595 * the closing operation.
30597 * Returns: %TRUE if @stream is being closed. %FALSE otherwise.
30603 * g_output_stream_printf:
30604 * @stream: a #GOutputStream.
30605 * @bytes_written: (out) (optional): location to store the number of bytes that was
30606 * written to the stream
30607 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
30608 * @error: location to store the error occurring, or %NULL to ignore
30609 * @format: the format string. See the printf() documentation
30610 * @...: the parameters to insert into the format string
30612 * This is a utility function around g_output_stream_write_all(). It
30613 * uses g_strdup_vprintf() to turn @format and @... into a string that
30614 * is then written to @stream.
30616 * See the documentation of g_output_stream_write_all() about the
30617 * behavior of the actual write operation.
30619 * Note that partial writes cannot be properly checked with this
30620 * function due to the variable length of the written string, if you
30621 * need precise control over partial write failures, you need to
30622 * create you own printf()-like wrapper around g_output_stream_write()
30623 * or g_output_stream_write_all().
30626 * Returns: %TRUE on success, %FALSE if there was an error
30631 * g_output_stream_set_pending:
30632 * @stream: a #GOutputStream.
30633 * @error: a #GError location to store the error occurring, or %NULL to
30636 * Sets @stream to have actions pending. If the pending flag is
30637 * already set or @stream is closed, it will return %FALSE and set
30640 * Returns: %TRUE if pending was previously unset and is now set.
30645 * g_output_stream_splice:
30646 * @stream: a #GOutputStream.
30647 * @source: a #GInputStream.
30648 * @flags: a set of #GOutputStreamSpliceFlags.
30649 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
30650 * @error: a #GError location to store the error occurring, or %NULL to
30653 * Splices an input stream into an output stream.
30655 * Returns: a #gssize containing the size of the data spliced, or
30656 * -1 if an error occurred. Note that if the number of bytes
30657 * spliced is greater than %G_MAXSSIZE, then that will be
30658 * returned, and there is no way to determine the actual number
30659 * of bytes spliced.
30664 * g_output_stream_splice_async:
30665 * @stream: a #GOutputStream.
30666 * @source: a #GInputStream.
30667 * @flags: a set of #GOutputStreamSpliceFlags.
30668 * @io_priority: the io priority of the request.
30669 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
30670 * @callback: (scope async): a #GAsyncReadyCallback.
30671 * @user_data: (closure): user data passed to @callback.
30673 * Splices a stream asynchronously.
30674 * When the operation is finished @callback will be called.
30675 * You can then call g_output_stream_splice_finish() to get the
30676 * result of the operation.
30678 * For the synchronous, blocking version of this function, see
30679 * g_output_stream_splice().
30684 * g_output_stream_splice_finish:
30685 * @stream: a #GOutputStream.
30686 * @result: a #GAsyncResult.
30687 * @error: a #GError location to store the error occurring, or %NULL to
30690 * Finishes an asynchronous stream splice operation.
30692 * Returns: a #gssize of the number of bytes spliced. Note that if the
30693 * number of bytes spliced is greater than %G_MAXSSIZE, then that
30694 * will be returned, and there is no way to determine the actual
30695 * number of bytes spliced.
30700 * g_output_stream_vprintf:
30701 * @stream: a #GOutputStream.
30702 * @bytes_written: (out) (optional): location to store the number of bytes that was
30703 * written to the stream
30704 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
30705 * @error: location to store the error occurring, or %NULL to ignore
30706 * @format: the format string. See the printf() documentation
30707 * @args: the parameters to insert into the format string
30709 * This is a utility function around g_output_stream_write_all(). It
30710 * uses g_strdup_vprintf() to turn @format and @args into a string that
30711 * is then written to @stream.
30713 * See the documentation of g_output_stream_write_all() about the
30714 * behavior of the actual write operation.
30716 * Note that partial writes cannot be properly checked with this
30717 * function due to the variable length of the written string, if you
30718 * need precise control over partial write failures, you need to
30719 * create you own printf()-like wrapper around g_output_stream_write()
30720 * or g_output_stream_write_all().
30723 * Returns: %TRUE on success, %FALSE if there was an error
30728 * g_output_stream_write: (virtual write_fn)
30729 * @stream: a #GOutputStream.
30730 * @buffer: (array length=count) (element-type guint8): the buffer containing the data to write.
30731 * @count: the number of bytes to write
30732 * @cancellable: (nullable): optional cancellable object
30733 * @error: location to store the error occurring, or %NULL to ignore
30735 * Tries to write @count bytes from @buffer into the stream. Will block
30736 * during the operation.
30738 * If count is 0, returns 0 and does nothing. A value of @count
30739 * larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
30741 * On success, the number of bytes written to the stream is returned.
30742 * It is not an error if this is not the same as the requested size, as it
30743 * can happen e.g. on a partial I/O error, or if there is not enough
30744 * storage in the stream. All writes block until at least one byte
30745 * is written or an error occurs; 0 is never returned (unless
30748 * If @cancellable is not %NULL, then the operation can be cancelled by
30749 * triggering the cancellable object from another thread. If the operation
30750 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
30751 * operation was partially finished when the operation was cancelled the
30752 * partial result will be returned, without an error.
30754 * On error -1 is returned and @error is set accordingly.
30756 * Returns: Number of bytes written, or -1 on error
30761 * g_output_stream_write_all:
30762 * @stream: a #GOutputStream.
30763 * @buffer: (array length=count) (element-type guint8): the buffer containing the data to write.
30764 * @count: the number of bytes to write
30765 * @bytes_written: (out) (optional): location to store the number of bytes that was
30766 * written to the stream
30767 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
30768 * @error: location to store the error occurring, or %NULL to ignore
30770 * Tries to write @count bytes from @buffer into the stream. Will block
30771 * during the operation.
30773 * This function is similar to g_output_stream_write(), except it tries to
30774 * write as many bytes as requested, only stopping on an error.
30776 * On a successful write of @count bytes, %TRUE is returned, and @bytes_written
30777 * is set to @count.
30779 * If there is an error during the operation %FALSE is returned and @error
30780 * is set to indicate the error status.
30782 * As a special exception to the normal conventions for functions that
30783 * use #GError, if this function returns %FALSE (and sets @error) then
30784 * @bytes_written will be set to the number of bytes that were
30785 * successfully written before the error was encountered. This
30786 * functionality is only available from C. If you need it from another
30787 * language then you must write your own loop around
30788 * g_output_stream_write().
30790 * Returns: %TRUE on success, %FALSE if there was an error
30795 * g_output_stream_write_all_async:
30796 * @stream: A #GOutputStream
30797 * @buffer: (array length=count) (element-type guint8): the buffer containing the data to write
30798 * @count: the number of bytes to write
30799 * @io_priority: the io priority of the request
30800 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore
30801 * @callback: (scope async): callback to call when the request is satisfied
30802 * @user_data: (closure): the data to pass to callback function
30804 * Request an asynchronous write of @count bytes from @buffer into
30805 * the stream. When the operation is finished @callback will be called.
30806 * You can then call g_output_stream_write_all_finish() to get the result of the
30809 * This is the asynchronous version of g_output_stream_write_all().
30811 * Call g_output_stream_write_all_finish() to collect the result.
30813 * Any outstanding I/O request with higher priority (lower numerical
30814 * value) will be executed before an outstanding request with lower
30815 * priority. Default priority is %G_PRIORITY_DEFAULT.
30817 * Note that no copy of @buffer will be made, so it must stay valid
30818 * until @callback is called.
30825 * g_output_stream_write_all_finish:
30826 * @stream: a #GOutputStream
30827 * @result: a #GAsyncResult
30828 * @bytes_written: (out) (optional): location to store the number of bytes that was written to the stream
30829 * @error: a #GError location to store the error occurring, or %NULL to ignore.
30831 * Finishes an asynchronous stream write operation started with
30832 * g_output_stream_write_all_async().
30834 * As a special exception to the normal conventions for functions that
30835 * use #GError, if this function returns %FALSE (and sets @error) then
30836 * @bytes_written will be set to the number of bytes that were
30837 * successfully written before the error was encountered. This
30838 * functionality is only available from C. If you need it from another
30839 * language then you must write your own loop around
30840 * g_output_stream_write_async().
30842 * Returns: %TRUE on success, %FALSE if there was an error
30848 * g_output_stream_write_async:
30849 * @stream: A #GOutputStream.
30850 * @buffer: (array length=count) (element-type guint8): the buffer containing the data to write.
30851 * @count: the number of bytes to write
30852 * @io_priority: the io priority of the request.
30853 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
30854 * @callback: (scope async): callback to call when the request is satisfied
30855 * @user_data: (closure): the data to pass to callback function
30857 * Request an asynchronous write of @count bytes from @buffer into
30858 * the stream. When the operation is finished @callback will be called.
30859 * You can then call g_output_stream_write_finish() to get the result of the
30862 * During an async request no other sync and async calls are allowed,
30863 * and will result in %G_IO_ERROR_PENDING errors.
30865 * A value of @count larger than %G_MAXSSIZE will cause a
30866 * %G_IO_ERROR_INVALID_ARGUMENT error.
30868 * On success, the number of bytes written will be passed to the
30869 * @callback. It is not an error if this is not the same as the
30870 * requested size, as it can happen e.g. on a partial I/O error,
30871 * but generally we try to write as many bytes as requested.
30873 * You are guaranteed that this method will never fail with
30874 * %G_IO_ERROR_WOULD_BLOCK - if @stream can't accept more data, the
30875 * method will just wait until this changes.
30877 * Any outstanding I/O request with higher priority (lower numerical
30878 * value) will be executed before an outstanding request with lower
30879 * priority. Default priority is %G_PRIORITY_DEFAULT.
30881 * The asynchronous methods have a default fallback that uses threads
30882 * to implement asynchronicity, so they are optional for inheriting
30883 * classes. However, if you override one you must override all.
30885 * For the synchronous, blocking version of this function, see
30886 * g_output_stream_write().
30888 * Note that no copy of @buffer will be made, so it must stay valid
30889 * until @callback is called. See g_output_stream_write_bytes_async()
30890 * for a #GBytes version that will automatically hold a reference to
30891 * the contents (without copying) for the duration of the call.
30896 * g_output_stream_write_bytes:
30897 * @stream: a #GOutputStream.
30898 * @bytes: the #GBytes to write
30899 * @cancellable: (nullable): optional cancellable object
30900 * @error: location to store the error occurring, or %NULL to ignore
30902 * A wrapper function for g_output_stream_write() which takes a
30903 * #GBytes as input. This can be more convenient for use by language
30904 * bindings or in other cases where the refcounted nature of #GBytes
30905 * is helpful over a bare pointer interface.
30907 * However, note that this function may still perform partial writes,
30908 * just like g_output_stream_write(). If that occurs, to continue
30909 * writing, you will need to create a new #GBytes containing just the
30910 * remaining bytes, using g_bytes_new_from_bytes(). Passing the same
30911 * #GBytes instance multiple times potentially can result in duplicated
30912 * data in the output stream.
30914 * Returns: Number of bytes written, or -1 on error
30919 * g_output_stream_write_bytes_async:
30920 * @stream: A #GOutputStream.
30921 * @bytes: The bytes to write
30922 * @io_priority: the io priority of the request.
30923 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
30924 * @callback: (scope async): callback to call when the request is satisfied
30925 * @user_data: (closure): the data to pass to callback function
30927 * This function is similar to g_output_stream_write_async(), but
30928 * takes a #GBytes as input. Due to the refcounted nature of #GBytes,
30929 * this allows the stream to avoid taking a copy of the data.
30931 * However, note that this function may still perform partial writes,
30932 * just like g_output_stream_write_async(). If that occurs, to continue
30933 * writing, you will need to create a new #GBytes containing just the
30934 * remaining bytes, using g_bytes_new_from_bytes(). Passing the same
30935 * #GBytes instance multiple times potentially can result in duplicated
30936 * data in the output stream.
30938 * For the synchronous, blocking version of this function, see
30939 * g_output_stream_write_bytes().
30944 * g_output_stream_write_bytes_finish:
30945 * @stream: a #GOutputStream.
30946 * @result: a #GAsyncResult.
30947 * @error: a #GError location to store the error occurring, or %NULL to
30950 * Finishes a stream write-from-#GBytes operation.
30952 * Returns: a #gssize containing the number of bytes written to the stream.
30957 * g_output_stream_write_finish:
30958 * @stream: a #GOutputStream.
30959 * @result: a #GAsyncResult.
30960 * @error: a #GError location to store the error occurring, or %NULL to
30963 * Finishes a stream write operation.
30965 * Returns: a #gssize containing the number of bytes written to the stream.
30970 * g_output_stream_writev: (virtual writev_fn)
30971 * @stream: a #GOutputStream.
30972 * @vectors: (array length=n_vectors): the buffer containing the #GOutputVectors to write.
30973 * @n_vectors: the number of vectors to write
30974 * @bytes_written: (out) (optional): location to store the number of bytes that were
30975 * written to the stream
30976 * @cancellable: (nullable): optional cancellable object
30977 * @error: location to store the error occurring, or %NULL to ignore
30979 * Tries to write the bytes contained in the @n_vectors @vectors into the
30980 * stream. Will block during the operation.
30982 * If @n_vectors is 0 or the sum of all bytes in @vectors is 0, returns 0 and
30985 * On success, the number of bytes written to the stream is returned.
30986 * It is not an error if this is not the same as the requested size, as it
30987 * can happen e.g. on a partial I/O error, or if there is not enough
30988 * storage in the stream. All writes block until at least one byte
30989 * is written or an error occurs; 0 is never returned (unless
30990 * @n_vectors is 0 or the sum of all bytes in @vectors is 0).
30992 * If @cancellable is not %NULL, then the operation can be cancelled by
30993 * triggering the cancellable object from another thread. If the operation
30994 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
30995 * operation was partially finished when the operation was cancelled the
30996 * partial result will be returned, without an error.
30998 * Some implementations of g_output_stream_writev() may have limitations on the
30999 * aggregate buffer size, and will return %G_IO_ERROR_INVALID_ARGUMENT if these
31000 * are exceeded. For example, when writing to a local file on UNIX platforms,
31001 * the aggregate buffer size must not exceed %G_MAXSSIZE bytes.
31003 * Returns: %TRUE on success, %FALSE if there was an error
31009 * g_output_stream_writev_all:
31010 * @stream: a #GOutputStream.
31011 * @vectors: (array length=n_vectors): the buffer containing the #GOutputVectors to write.
31012 * @n_vectors: the number of vectors to write
31013 * @bytes_written: (out) (optional): location to store the number of bytes that were
31014 * written to the stream
31015 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
31016 * @error: location to store the error occurring, or %NULL to ignore
31018 * Tries to write the bytes contained in the @n_vectors @vectors into the
31019 * stream. Will block during the operation.
31021 * This function is similar to g_output_stream_writev(), except it tries to
31022 * write as many bytes as requested, only stopping on an error.
31024 * On a successful write of all @n_vectors vectors, %TRUE is returned, and
31025 * @bytes_written is set to the sum of all the sizes of @vectors.
31027 * If there is an error during the operation %FALSE is returned and @error
31028 * is set to indicate the error status.
31030 * As a special exception to the normal conventions for functions that
31031 * use #GError, if this function returns %FALSE (and sets @error) then
31032 * @bytes_written will be set to the number of bytes that were
31033 * successfully written before the error was encountered. This
31034 * functionality is only available from C. If you need it from another
31035 * language then you must write your own loop around
31036 * g_output_stream_write().
31038 * The content of the individual elements of @vectors might be changed by this
31041 * Returns: %TRUE on success, %FALSE if there was an error
31047 * g_output_stream_writev_all_async:
31048 * @stream: A #GOutputStream
31049 * @vectors: (array length=n_vectors): the buffer containing the #GOutputVectors to write.
31050 * @n_vectors: the number of vectors to write
31051 * @io_priority: the I/O priority of the request
31052 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore
31053 * @callback: (scope async): callback to call when the request is satisfied
31054 * @user_data: (closure): the data to pass to callback function
31056 * Request an asynchronous write of the bytes contained in the @n_vectors @vectors into
31057 * the stream. When the operation is finished @callback will be called.
31058 * You can then call g_output_stream_writev_all_finish() to get the result of the
31061 * This is the asynchronous version of g_output_stream_writev_all().
31063 * Call g_output_stream_writev_all_finish() to collect the result.
31065 * Any outstanding I/O request with higher priority (lower numerical
31066 * value) will be executed before an outstanding request with lower
31067 * priority. Default priority is %G_PRIORITY_DEFAULT.
31069 * Note that no copy of @vectors will be made, so it must stay valid
31070 * until @callback is called. The content of the individual elements
31071 * of @vectors might be changed by this function.
31078 * g_output_stream_writev_all_finish:
31079 * @stream: a #GOutputStream
31080 * @result: a #GAsyncResult
31081 * @bytes_written: (out) (optional): location to store the number of bytes that were written to the stream
31082 * @error: a #GError location to store the error occurring, or %NULL to ignore.
31084 * Finishes an asynchronous stream write operation started with
31085 * g_output_stream_writev_all_async().
31087 * As a special exception to the normal conventions for functions that
31088 * use #GError, if this function returns %FALSE (and sets @error) then
31089 * @bytes_written will be set to the number of bytes that were
31090 * successfully written before the error was encountered. This
31091 * functionality is only available from C. If you need it from another
31092 * language then you must write your own loop around
31093 * g_output_stream_writev_async().
31095 * Returns: %TRUE on success, %FALSE if there was an error
31101 * g_output_stream_writev_async:
31102 * @stream: A #GOutputStream.
31103 * @vectors: (array length=n_vectors): the buffer containing the #GOutputVectors to write.
31104 * @n_vectors: the number of vectors to write
31105 * @io_priority: the I/O priority of the request.
31106 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
31107 * @callback: (scope async): callback to call when the request is satisfied
31108 * @user_data: (closure): the data to pass to callback function
31110 * Request an asynchronous write of the bytes contained in @n_vectors @vectors into
31111 * the stream. When the operation is finished @callback will be called.
31112 * You can then call g_output_stream_writev_finish() to get the result of the
31115 * During an async request no other sync and async calls are allowed,
31116 * and will result in %G_IO_ERROR_PENDING errors.
31118 * On success, the number of bytes written will be passed to the
31119 * @callback. It is not an error if this is not the same as the
31120 * requested size, as it can happen e.g. on a partial I/O error,
31121 * but generally we try to write as many bytes as requested.
31123 * You are guaranteed that this method will never fail with
31124 * %G_IO_ERROR_WOULD_BLOCK — if @stream can't accept more data, the
31125 * method will just wait until this changes.
31127 * Any outstanding I/O request with higher priority (lower numerical
31128 * value) will be executed before an outstanding request with lower
31129 * priority. Default priority is %G_PRIORITY_DEFAULT.
31131 * The asynchronous methods have a default fallback that uses threads
31132 * to implement asynchronicity, so they are optional for inheriting
31133 * classes. However, if you override one you must override all.
31135 * For the synchronous, blocking version of this function, see
31136 * g_output_stream_writev().
31138 * Note that no copy of @vectors will be made, so it must stay valid
31139 * until @callback is called.
31146 * g_output_stream_writev_finish:
31147 * @stream: a #GOutputStream.
31148 * @result: a #GAsyncResult.
31149 * @bytes_written: (out) (optional): location to store the number of bytes that were written to the stream
31150 * @error: a #GError location to store the error occurring, or %NULL to
31153 * Finishes a stream writev operation.
31155 * Returns: %TRUE on success, %FALSE if there was an error
31161 * g_permission_acquire:
31162 * @permission: a #GPermission instance
31163 * @cancellable: (nullable): a #GCancellable, or %NULL
31164 * @error: a pointer to a %NULL #GError, or %NULL
31166 * Attempts to acquire the permission represented by @permission.
31168 * The precise method by which this happens depends on the permission
31169 * and the underlying authentication mechanism. A simple example is
31170 * that a dialog may appear asking the user to enter their password.
31172 * You should check with g_permission_get_can_acquire() before calling
31175 * If the permission is acquired then %TRUE is returned. Otherwise,
31176 * %FALSE is returned and @error is set appropriately.
31178 * This call is blocking, likely for a very long time (in the case that
31179 * user interaction is required). See g_permission_acquire_async() for
31180 * the non-blocking version.
31182 * Returns: %TRUE if the permission was successfully acquired
31188 * g_permission_acquire_async:
31189 * @permission: a #GPermission instance
31190 * @cancellable: (nullable): a #GCancellable, or %NULL
31191 * @callback: the #GAsyncReadyCallback to call when done
31192 * @user_data: the user data to pass to @callback
31194 * Attempts to acquire the permission represented by @permission.
31196 * This is the first half of the asynchronous version of
31197 * g_permission_acquire().
31204 * g_permission_acquire_finish:
31205 * @permission: a #GPermission instance
31206 * @result: the #GAsyncResult given to the #GAsyncReadyCallback
31207 * @error: a pointer to a %NULL #GError, or %NULL
31209 * Collects the result of attempting to acquire the permission
31210 * represented by @permission.
31212 * This is the second half of the asynchronous version of
31213 * g_permission_acquire().
31215 * Returns: %TRUE if the permission was successfully acquired
31221 * g_permission_get_allowed:
31222 * @permission: a #GPermission instance
31224 * Gets the value of the 'allowed' property. This property is %TRUE if
31225 * the caller currently has permission to perform the action that
31226 * @permission represents the permission to perform.
31228 * Returns: the value of the 'allowed' property
31234 * g_permission_get_can_acquire:
31235 * @permission: a #GPermission instance
31237 * Gets the value of the 'can-acquire' property. This property is %TRUE
31238 * if it is generally possible to acquire the permission by calling
31239 * g_permission_acquire().
31241 * Returns: the value of the 'can-acquire' property
31247 * g_permission_get_can_release:
31248 * @permission: a #GPermission instance
31250 * Gets the value of the 'can-release' property. This property is %TRUE
31251 * if it is generally possible to release the permission by calling
31252 * g_permission_release().
31254 * Returns: the value of the 'can-release' property
31260 * g_permission_impl_update:
31261 * @permission: a #GPermission instance
31262 * @allowed: the new value for the 'allowed' property
31263 * @can_acquire: the new value for the 'can-acquire' property
31264 * @can_release: the new value for the 'can-release' property
31266 * This function is called by the #GPermission implementation to update
31267 * the properties of the permission. You should never call this
31268 * function except from a #GPermission implementation.
31270 * GObject notify signals are generated, as appropriate.
31277 * g_permission_release:
31278 * @permission: a #GPermission instance
31279 * @cancellable: (nullable): a #GCancellable, or %NULL
31280 * @error: a pointer to a %NULL #GError, or %NULL
31282 * Attempts to release the permission represented by @permission.
31284 * The precise method by which this happens depends on the permission
31285 * and the underlying authentication mechanism. In most cases the
31286 * permission will be dropped immediately without further action.
31288 * You should check with g_permission_get_can_release() before calling
31291 * If the permission is released then %TRUE is returned. Otherwise,
31292 * %FALSE is returned and @error is set appropriately.
31294 * This call is blocking, likely for a very long time (in the case that
31295 * user interaction is required). See g_permission_release_async() for
31296 * the non-blocking version.
31298 * Returns: %TRUE if the permission was successfully released
31304 * g_permission_release_async:
31305 * @permission: a #GPermission instance
31306 * @cancellable: (nullable): a #GCancellable, or %NULL
31307 * @callback: the #GAsyncReadyCallback to call when done
31308 * @user_data: the user data to pass to @callback
31310 * Attempts to release the permission represented by @permission.
31312 * This is the first half of the asynchronous version of
31313 * g_permission_release().
31320 * g_permission_release_finish:
31321 * @permission: a #GPermission instance
31322 * @result: the #GAsyncResult given to the #GAsyncReadyCallback
31323 * @error: a pointer to a %NULL #GError, or %NULL
31325 * Collects the result of attempting to release the permission
31326 * represented by @permission.
31328 * This is the second half of the asynchronous version of
31329 * g_permission_release().
31331 * Returns: %TRUE if the permission was successfully released
31337 * g_pollable_input_stream_can_poll:
31338 * @stream: a #GPollableInputStream.
31340 * Checks if @stream is actually pollable. Some classes may implement
31341 * #GPollableInputStream but have only certain instances of that class
31342 * be pollable. If this method returns %FALSE, then the behavior of
31343 * other #GPollableInputStream methods is undefined.
31345 * For any given stream, the value returned by this method is constant;
31346 * a stream cannot switch from pollable to non-pollable or vice versa.
31348 * Returns: %TRUE if @stream is pollable, %FALSE if not.
31354 * g_pollable_input_stream_create_source:
31355 * @stream: a #GPollableInputStream.
31356 * @cancellable: (nullable): a #GCancellable, or %NULL
31358 * Creates a #GSource that triggers when @stream can be read, or
31359 * @cancellable is triggered or an error occurs. The callback on the
31360 * source is of the #GPollableSourceFunc type.
31362 * As with g_pollable_input_stream_is_readable(), it is possible that
31363 * the stream may not actually be readable even after the source
31364 * triggers, so you should use g_pollable_input_stream_read_nonblocking()
31365 * rather than g_input_stream_read() from the callback.
31367 * Returns: (transfer full): a new #GSource
31373 * g_pollable_input_stream_is_readable:
31374 * @stream: a #GPollableInputStream.
31376 * Checks if @stream can be read.
31378 * Note that some stream types may not be able to implement this 100%
31379 * reliably, and it is possible that a call to g_input_stream_read()
31380 * after this returns %TRUE would still block. To guarantee
31381 * non-blocking behavior, you should always use
31382 * g_pollable_input_stream_read_nonblocking(), which will return a
31383 * %G_IO_ERROR_WOULD_BLOCK error rather than blocking.
31385 * Returns: %TRUE if @stream is readable, %FALSE if not. If an error
31386 * has occurred on @stream, this will result in
31387 * g_pollable_input_stream_is_readable() returning %TRUE, and the
31388 * next attempt to read will return the error.
31394 * g_pollable_input_stream_read_nonblocking: (virtual read_nonblocking)
31395 * @stream: a #GPollableInputStream
31396 * @buffer: (array length=count) (element-type guint8) (out caller-allocates): a
31397 * buffer to read data into (which should be at least @count bytes long).
31398 * @count: (in): the number of bytes you want to read
31399 * @cancellable: (nullable): a #GCancellable, or %NULL
31400 * @error: #GError for error reporting, or %NULL to ignore.
31402 * Attempts to read up to @count bytes from @stream into @buffer, as
31403 * with g_input_stream_read(). If @stream is not currently readable,
31404 * this will immediately return %G_IO_ERROR_WOULD_BLOCK, and you can
31405 * use g_pollable_input_stream_create_source() to create a #GSource
31406 * that will be triggered when @stream is readable.
31408 * Note that since this method never blocks, you cannot actually
31409 * use @cancellable to cancel it. However, it will return an error
31410 * if @cancellable has already been cancelled when you call, which
31411 * may happen if you call this method after a source triggers due
31412 * to having been cancelled.
31414 * Returns: the number of bytes read, or -1 on error (including
31415 * %G_IO_ERROR_WOULD_BLOCK).
31420 * g_pollable_output_stream_can_poll:
31421 * @stream: a #GPollableOutputStream.
31423 * Checks if @stream is actually pollable. Some classes may implement
31424 * #GPollableOutputStream but have only certain instances of that
31425 * class be pollable. If this method returns %FALSE, then the behavior
31426 * of other #GPollableOutputStream methods is undefined.
31428 * For any given stream, the value returned by this method is constant;
31429 * a stream cannot switch from pollable to non-pollable or vice versa.
31431 * Returns: %TRUE if @stream is pollable, %FALSE if not.
31437 * g_pollable_output_stream_create_source:
31438 * @stream: a #GPollableOutputStream.
31439 * @cancellable: (nullable): a #GCancellable, or %NULL
31441 * Creates a #GSource that triggers when @stream can be written, or
31442 * @cancellable is triggered or an error occurs. The callback on the
31443 * source is of the #GPollableSourceFunc type.
31445 * As with g_pollable_output_stream_is_writable(), it is possible that
31446 * the stream may not actually be writable even after the source
31447 * triggers, so you should use g_pollable_output_stream_write_nonblocking()
31448 * rather than g_output_stream_write() from the callback.
31450 * Returns: (transfer full): a new #GSource
31456 * g_pollable_output_stream_is_writable:
31457 * @stream: a #GPollableOutputStream.
31459 * Checks if @stream can be written.
31461 * Note that some stream types may not be able to implement this 100%
31462 * reliably, and it is possible that a call to g_output_stream_write()
31463 * after this returns %TRUE would still block. To guarantee
31464 * non-blocking behavior, you should always use
31465 * g_pollable_output_stream_write_nonblocking(), which will return a
31466 * %G_IO_ERROR_WOULD_BLOCK error rather than blocking.
31468 * Returns: %TRUE if @stream is writable, %FALSE if not. If an error
31469 * has occurred on @stream, this will result in
31470 * g_pollable_output_stream_is_writable() returning %TRUE, and the
31471 * next attempt to write will return the error.
31477 * g_pollable_output_stream_write_nonblocking: (virtual write_nonblocking)
31478 * @stream: a #GPollableOutputStream
31479 * @buffer: (array length=count) (element-type guint8): a buffer to write
31481 * @count: the number of bytes you want to write
31482 * @cancellable: (nullable): a #GCancellable, or %NULL
31483 * @error: #GError for error reporting, or %NULL to ignore.
31485 * Attempts to write up to @count bytes from @buffer to @stream, as
31486 * with g_output_stream_write(). If @stream is not currently writable,
31487 * this will immediately return %G_IO_ERROR_WOULD_BLOCK, and you can
31488 * use g_pollable_output_stream_create_source() to create a #GSource
31489 * that will be triggered when @stream is writable.
31491 * Note that since this method never blocks, you cannot actually
31492 * use @cancellable to cancel it. However, it will return an error
31493 * if @cancellable has already been cancelled when you call, which
31494 * may happen if you call this method after a source triggers due
31495 * to having been cancelled.
31497 * Also note that if %G_IO_ERROR_WOULD_BLOCK is returned some underlying
31498 * transports like D/TLS require that you re-send the same @buffer and
31499 * @count in the next write call.
31501 * Returns: the number of bytes written, or -1 on error (including
31502 * %G_IO_ERROR_WOULD_BLOCK).
31507 * g_pollable_output_stream_writev_nonblocking: (virtual writev_nonblocking)
31508 * @stream: a #GPollableOutputStream
31509 * @vectors: (array length=n_vectors): the buffer containing the #GOutputVectors to write.
31510 * @n_vectors: the number of vectors to write
31511 * @bytes_written: (out) (optional): location to store the number of bytes that were
31512 * written to the stream
31513 * @cancellable: (nullable): a #GCancellable, or %NULL
31514 * @error: #GError for error reporting, or %NULL to ignore.
31516 * Attempts to write the bytes contained in the @n_vectors @vectors to @stream,
31517 * as with g_output_stream_writev(). If @stream is not currently writable,
31518 * this will immediately return %@G_POLLABLE_RETURN_WOULD_BLOCK, and you can
31519 * use g_pollable_output_stream_create_source() to create a #GSource
31520 * that will be triggered when @stream is writable. @error will *not* be
31521 * set in that case.
31523 * Note that since this method never blocks, you cannot actually
31524 * use @cancellable to cancel it. However, it will return an error
31525 * if @cancellable has already been cancelled when you call, which
31526 * may happen if you call this method after a source triggers due
31527 * to having been cancelled.
31529 * Also note that if %G_POLLABLE_RETURN_WOULD_BLOCK is returned some underlying
31530 * transports like D/TLS require that you re-send the same @vectors and
31531 * @n_vectors in the next write call.
31533 * Returns: %@G_POLLABLE_RETURN_OK on success, %G_POLLABLE_RETURN_WOULD_BLOCK
31534 * if the stream is not currently writable (and @error is *not* set), or
31535 * %G_POLLABLE_RETURN_FAILED if there was an error in which case @error will
31542 * g_pollable_source_new:
31543 * @pollable_stream: the stream associated with the new source
31545 * Utility method for #GPollableInputStream and #GPollableOutputStream
31546 * implementations. Creates a new #GSource that expects a callback of
31547 * type #GPollableSourceFunc. The new source does not actually do
31548 * anything on its own; use g_source_add_child_source() to add other
31549 * sources to it to cause it to trigger.
31551 * Returns: (transfer full): the new #GSource.
31557 * g_pollable_source_new_full:
31558 * @pollable_stream: (type GObject): the stream associated with the
31560 * @child_source: (nullable): optional child source to attach
31561 * @cancellable: (nullable): optional #GCancellable to attach
31563 * Utility method for #GPollableInputStream and #GPollableOutputStream
31564 * implementations. Creates a new #GSource, as with
31565 * g_pollable_source_new(), but also attaching @child_source (with a
31566 * dummy callback), and @cancellable, if they are non-%NULL.
31568 * Returns: (transfer full): the new #GSource.
31574 * g_pollable_stream_read:
31575 * @stream: a #GInputStream
31576 * @buffer: (array length=count) (element-type guint8): a buffer to
31578 * @count: the number of bytes to read
31579 * @blocking: whether to do blocking I/O
31580 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
31581 * @error: location to store the error occurring, or %NULL to ignore
31583 * Tries to read from @stream, as with g_input_stream_read() (if
31584 * @blocking is %TRUE) or g_pollable_input_stream_read_nonblocking()
31585 * (if @blocking is %FALSE). This can be used to more easily share
31586 * code between blocking and non-blocking implementations of a method.
31588 * If @blocking is %FALSE, then @stream must be a
31589 * #GPollableInputStream for which g_pollable_input_stream_can_poll()
31590 * returns %TRUE, or else the behavior is undefined. If @blocking is
31591 * %TRUE, then @stream does not need to be a #GPollableInputStream.
31593 * Returns: the number of bytes read, or -1 on error.
31599 * g_pollable_stream_write:
31600 * @stream: a #GOutputStream.
31601 * @buffer: (array length=count) (element-type guint8): the buffer
31602 * containing the data to write.
31603 * @count: the number of bytes to write
31604 * @blocking: whether to do blocking I/O
31605 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
31606 * @error: location to store the error occurring, or %NULL to ignore
31608 * Tries to write to @stream, as with g_output_stream_write() (if
31609 * @blocking is %TRUE) or g_pollable_output_stream_write_nonblocking()
31610 * (if @blocking is %FALSE). This can be used to more easily share
31611 * code between blocking and non-blocking implementations of a method.
31613 * If @blocking is %FALSE, then @stream must be a
31614 * #GPollableOutputStream for which
31615 * g_pollable_output_stream_can_poll() returns %TRUE or else the
31616 * behavior is undefined. If @blocking is %TRUE, then @stream does not
31617 * need to be a #GPollableOutputStream.
31619 * Returns: the number of bytes written, or -1 on error.
31625 * g_pollable_stream_write_all:
31626 * @stream: a #GOutputStream.
31627 * @buffer: (array length=count) (element-type guint8): the buffer
31628 * containing the data to write.
31629 * @count: the number of bytes to write
31630 * @blocking: whether to do blocking I/O
31631 * @bytes_written: (out): location to store the number of bytes that was
31632 * written to the stream
31633 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
31634 * @error: location to store the error occurring, or %NULL to ignore
31636 * Tries to write @count bytes to @stream, as with
31637 * g_output_stream_write_all(), but using g_pollable_stream_write()
31638 * rather than g_output_stream_write().
31640 * On a successful write of @count bytes, %TRUE is returned, and
31641 * @bytes_written is set to @count.
31643 * If there is an error during the operation (including
31644 * %G_IO_ERROR_WOULD_BLOCK in the non-blocking case), %FALSE is
31645 * returned and @error is set to indicate the error status,
31646 * @bytes_written is updated to contain the number of bytes written
31647 * into the stream before the error occurred.
31649 * As with g_pollable_stream_write(), if @blocking is %FALSE, then
31650 * @stream must be a #GPollableOutputStream for which
31651 * g_pollable_output_stream_can_poll() returns %TRUE or else the
31652 * behavior is undefined. If @blocking is %TRUE, then @stream does not
31653 * need to be a #GPollableOutputStream.
31655 * Returns: %TRUE on success, %FALSE if there was an error
31661 * g_power_profile_monitor_dup_default:
31663 * Gets a reference to the default #GPowerProfileMonitor for the system.
31665 * Returns: (not nullable) (transfer full): a new reference to the default #GPowerProfileMonitor
31671 * g_power_profile_monitor_get_power_saver_enabled:
31672 * @monitor: a #GPowerProfileMonitor
31674 * Gets whether the system is in “Power Saver” mode.
31676 * You are expected to listen to the
31677 * #GPowerProfileMonitor::notify::power-saver-enabled signal to know when the profile has
31680 * Returns: Whether the system is in “Power Saver” mode.
31686 * g_property_action_new:
31687 * @name: the name of the action to create
31688 * @object: (type GObject.Object): the object that has the property
31690 * @property_name: the name of the property
31692 * Creates a #GAction corresponding to the value of property
31693 * @property_name on @object.
31695 * The property must be existent and readable and writable (and not
31698 * This function takes a reference on @object and doesn't release it
31699 * until the action is destroyed.
31701 * Returns: a new #GPropertyAction
31707 * g_proxy_address_get_destination_hostname:
31708 * @proxy: a #GProxyAddress
31710 * Gets @proxy's destination hostname; that is, the name of the host
31711 * that will be connected to via the proxy, not the name of the proxy
31714 * Returns: the @proxy's destination hostname
31720 * g_proxy_address_get_destination_port:
31721 * @proxy: a #GProxyAddress
31723 * Gets @proxy's destination port; that is, the port on the
31724 * destination host that will be connected to via the proxy, not the
31725 * port number of the proxy itself.
31727 * Returns: the @proxy's destination port
31733 * g_proxy_address_get_destination_protocol:
31734 * @proxy: a #GProxyAddress
31736 * Gets the protocol that is being spoken to the destination
31737 * server; eg, "http" or "ftp".
31739 * Returns: the @proxy's destination protocol
31745 * g_proxy_address_get_password:
31746 * @proxy: a #GProxyAddress
31748 * Gets @proxy's password.
31750 * Returns: (nullable): the @proxy's password
31756 * g_proxy_address_get_protocol:
31757 * @proxy: a #GProxyAddress
31759 * Gets @proxy's protocol. eg, "socks" or "http"
31761 * Returns: the @proxy's protocol
31767 * g_proxy_address_get_uri:
31768 * @proxy: a #GProxyAddress
31770 * Gets the proxy URI that @proxy was constructed from.
31772 * Returns: (nullable): the @proxy's URI, or %NULL if unknown
31778 * g_proxy_address_get_username:
31779 * @proxy: a #GProxyAddress
31781 * Gets @proxy's username.
31783 * Returns: (nullable): the @proxy's username
31789 * g_proxy_address_new:
31790 * @inetaddr: The proxy server #GInetAddress.
31791 * @port: The proxy server port.
31792 * @protocol: The proxy protocol to support, in lower case (e.g. socks, http).
31793 * @dest_hostname: The destination hostname the proxy should tunnel to.
31794 * @dest_port: The destination port to tunnel to.
31795 * @username: (nullable): The username to authenticate to the proxy server
31797 * @password: (nullable): The password to authenticate to the proxy server
31800 * Creates a new #GProxyAddress for @inetaddr with @protocol that should
31801 * tunnel through @dest_hostname and @dest_port.
31803 * (Note that this method doesn't set the #GProxyAddress:uri or
31804 * #GProxyAddress:destination-protocol fields; use g_object_new()
31805 * directly if you want to set those.)
31807 * Returns: a new #GProxyAddress
31814 * @proxy: a #GProxy
31815 * @connection: a #GIOStream
31816 * @proxy_address: a #GProxyAddress
31817 * @cancellable: (nullable): a #GCancellable
31818 * @error: return #GError
31820 * Given @connection to communicate with a proxy (eg, a
31821 * #GSocketConnection that is connected to the proxy server), this
31822 * does the necessary handshake to connect to @proxy_address, and if
31823 * required, wraps the #GIOStream to handle proxy payload.
31825 * Returns: (transfer full): a #GIOStream that will replace @connection. This might
31826 * be the same as @connection, in which case a reference
31833 * g_proxy_connect_async:
31834 * @proxy: a #GProxy
31835 * @connection: a #GIOStream
31836 * @proxy_address: a #GProxyAddress
31837 * @cancellable: (nullable): a #GCancellable
31838 * @callback: (scope async): a #GAsyncReadyCallback
31839 * @user_data: (closure): callback data
31841 * Asynchronous version of g_proxy_connect().
31848 * g_proxy_connect_finish:
31849 * @proxy: a #GProxy
31850 * @result: a #GAsyncResult
31851 * @error: return #GError
31853 * See g_proxy_connect().
31855 * Returns: (transfer full): a #GIOStream.
31861 * g_proxy_get_default_for_protocol:
31862 * @protocol: the proxy protocol name (e.g. http, socks, etc)
31864 * Find the `gio-proxy` extension point for a proxy implementation that supports
31865 * the specified protocol.
31867 * Returns: (nullable) (transfer full): return a #GProxy or NULL if protocol
31868 * is not supported.
31874 * g_proxy_resolver_get_default:
31876 * Gets the default #GProxyResolver for the system.
31878 * Returns: (not nullable) (transfer none): the default #GProxyResolver, which
31879 * will be a dummy object if no proxy resolver is available
31885 * g_proxy_resolver_is_supported:
31886 * @resolver: a #GProxyResolver
31888 * Checks if @resolver can be used on this system. (This is used
31889 * internally; g_proxy_resolver_get_default() will only return a proxy
31890 * resolver that returns %TRUE for this method.)
31892 * Returns: %TRUE if @resolver is supported.
31898 * g_proxy_resolver_lookup:
31899 * @resolver: a #GProxyResolver
31900 * @uri: a URI representing the destination to connect to
31901 * @cancellable: (nullable): a #GCancellable, or %NULL
31902 * @error: return location for a #GError, or %NULL
31904 * Looks into the system proxy configuration to determine what proxy,
31905 * if any, to use to connect to @uri. The returned proxy URIs are of
31906 * the form `<protocol>://[user[:password]@]host:port` or
31907 * `direct://`, where <protocol> could be http, rtsp, socks
31908 * or other proxying protocol.
31910 * If you don't know what network protocol is being used on the
31911 * socket, you should use `none` as the URI protocol.
31912 * In this case, the resolver might still return a generic proxy type
31913 * (such as SOCKS), but would not return protocol-specific proxy types
31916 * `direct://` is used when no proxy is needed.
31917 * Direct connection should not be attempted unless it is part of the
31918 * returned array of proxies.
31920 * Returns: (transfer full) (array zero-terminated=1): A
31921 * NULL-terminated array of proxy URIs. Must be freed
31922 * with g_strfreev().
31928 * g_proxy_resolver_lookup_async:
31929 * @resolver: a #GProxyResolver
31930 * @uri: a URI representing the destination to connect to
31931 * @cancellable: (nullable): a #GCancellable, or %NULL
31932 * @callback: (scope async): callback to call after resolution completes
31933 * @user_data: (closure): data for @callback
31935 * Asynchronous lookup of proxy. See g_proxy_resolver_lookup() for more
31943 * g_proxy_resolver_lookup_finish:
31944 * @resolver: a #GProxyResolver
31945 * @result: the result passed to your #GAsyncReadyCallback
31946 * @error: return location for a #GError, or %NULL
31948 * Call this function to obtain the array of proxy URIs when
31949 * g_proxy_resolver_lookup_async() is complete. See
31950 * g_proxy_resolver_lookup() for more details.
31952 * Returns: (transfer full) (array zero-terminated=1): A
31953 * NULL-terminated array of proxy URIs. Must be freed
31954 * with g_strfreev().
31960 * g_proxy_supports_hostname:
31961 * @proxy: a #GProxy
31963 * Some proxy protocols expect to be passed a hostname, which they
31964 * will resolve to an IP address themselves. Others, like SOCKS4, do
31965 * not allow this. This function will return %FALSE if @proxy is
31966 * implementing such a protocol. When %FALSE is returned, the caller
31967 * should resolve the destination hostname first, and then pass a
31968 * #GProxyAddress containing the stringified IP address to
31969 * g_proxy_connect() or g_proxy_connect_async().
31971 * Returns: %TRUE if hostname resolution is supported.
31977 * g_remote_action_group_activate_action_full:
31978 * @remote: a #GDBusActionGroup
31979 * @action_name: the name of the action to activate
31980 * @parameter: (nullable): the optional parameter to the activation
31981 * @platform_data: the platform data to send
31983 * Activates the remote action.
31985 * This is the same as g_action_group_activate_action() except that it
31986 * allows for provision of "platform data" to be sent along with the
31987 * activation request. This typically contains details such as the user
31988 * interaction timestamp or startup notification information.
31990 * @platform_data must be non-%NULL and must have the type
31991 * %G_VARIANT_TYPE_VARDICT. If it is floating, it will be consumed.
31998 * g_remote_action_group_change_action_state_full:
31999 * @remote: a #GRemoteActionGroup
32000 * @action_name: the name of the action to change the state of
32001 * @value: the new requested value for the state
32002 * @platform_data: the platform data to send
32004 * Changes the state of a remote action.
32006 * This is the same as g_action_group_change_action_state() except that
32007 * it allows for provision of "platform data" to be sent along with the
32008 * state change request. This typically contains details such as the
32009 * user interaction timestamp or startup notification information.
32011 * @platform_data must be non-%NULL and must have the type
32012 * %G_VARIANT_TYPE_VARDICT. If it is floating, it will be consumed.
32019 * g_resolver_error_quark:
32021 * Gets the #GResolver Error Quark.
32023 * Returns: a #GQuark.
32029 * g_resolver_free_addresses: (skip)
32030 * @addresses: a #GList of #GInetAddress
32032 * Frees @addresses (which should be the return value from
32033 * g_resolver_lookup_by_name() or g_resolver_lookup_by_name_finish()).
32034 * (This is a convenience method; you can also simply free the results
32042 * g_resolver_free_targets: (skip)
32043 * @targets: a #GList of #GSrvTarget
32045 * Frees @targets (which should be the return value from
32046 * g_resolver_lookup_service() or g_resolver_lookup_service_finish()).
32047 * (This is a convenience method; you can also simply free the
32048 * results by hand.)
32055 * g_resolver_get_default:
32057 * Gets the default #GResolver. You should unref it when you are done
32058 * with it. #GResolver may use its reference count as a hint about how
32059 * many threads it should allocate for concurrent DNS resolutions.
32061 * Returns: (transfer full): the default #GResolver.
32067 * g_resolver_lookup_by_address:
32068 * @resolver: a #GResolver
32069 * @address: the address to reverse-resolve
32070 * @cancellable: (nullable): a #GCancellable, or %NULL
32071 * @error: return location for a #GError, or %NULL
32073 * Synchronously reverse-resolves @address to determine its
32074 * associated hostname.
32076 * If the DNS resolution fails, @error (if non-%NULL) will be set to
32077 * a value from #GResolverError.
32079 * If @cancellable is non-%NULL, it can be used to cancel the
32080 * operation, in which case @error (if non-%NULL) will be set to
32081 * %G_IO_ERROR_CANCELLED.
32083 * Returns: a hostname (either ASCII-only, or in ASCII-encoded
32084 * form), or %NULL on error.
32090 * g_resolver_lookup_by_address_async:
32091 * @resolver: a #GResolver
32092 * @address: the address to reverse-resolve
32093 * @cancellable: (nullable): a #GCancellable, or %NULL
32094 * @callback: (scope async): callback to call after resolution completes
32095 * @user_data: (closure): data for @callback
32097 * Begins asynchronously reverse-resolving @address to determine its
32098 * associated hostname, and eventually calls @callback, which must
32099 * call g_resolver_lookup_by_address_finish() to get the final result.
32106 * g_resolver_lookup_by_address_finish:
32107 * @resolver: a #GResolver
32108 * @result: the result passed to your #GAsyncReadyCallback
32109 * @error: return location for a #GError, or %NULL
32111 * Retrieves the result of a previous call to
32112 * g_resolver_lookup_by_address_async().
32114 * If the DNS resolution failed, @error (if non-%NULL) will be set to
32115 * a value from #GResolverError. If the operation was cancelled,
32116 * @error will be set to %G_IO_ERROR_CANCELLED.
32118 * Returns: a hostname (either ASCII-only, or in ASCII-encoded
32119 * form), or %NULL on error.
32125 * g_resolver_lookup_by_name:
32126 * @resolver: a #GResolver
32127 * @hostname: the hostname to look up
32128 * @cancellable: (nullable): a #GCancellable, or %NULL
32129 * @error: return location for a #GError, or %NULL
32131 * Synchronously resolves @hostname to determine its associated IP
32132 * address(es). @hostname may be an ASCII-only or UTF-8 hostname, or
32133 * the textual form of an IP address (in which case this just becomes
32134 * a wrapper around g_inet_address_new_from_string()).
32136 * On success, g_resolver_lookup_by_name() will return a non-empty #GList of
32137 * #GInetAddress, sorted in order of preference and guaranteed to not
32138 * contain duplicates. That is, if using the result to connect to
32139 * @hostname, you should attempt to connect to the first address
32140 * first, then the second if the first fails, etc. If you are using
32141 * the result to listen on a socket, it is appropriate to add each
32142 * result using e.g. g_socket_listener_add_address().
32144 * If the DNS resolution fails, @error (if non-%NULL) will be set to a
32145 * value from #GResolverError and %NULL will be returned.
32147 * If @cancellable is non-%NULL, it can be used to cancel the
32148 * operation, in which case @error (if non-%NULL) will be set to
32149 * %G_IO_ERROR_CANCELLED.
32151 * If you are planning to connect to a socket on the resolved IP
32152 * address, it may be easier to create a #GNetworkAddress and use its
32153 * #GSocketConnectable interface.
32155 * Returns: (element-type GInetAddress) (transfer full): a non-empty #GList
32156 * of #GInetAddress, or %NULL on error. You
32157 * must unref each of the addresses and free the list when you are
32158 * done with it. (You can use g_resolver_free_addresses() to do this.)
32164 * g_resolver_lookup_by_name_async:
32165 * @resolver: a #GResolver
32166 * @hostname: the hostname to look up the address of
32167 * @cancellable: (nullable): a #GCancellable, or %NULL
32168 * @callback: (scope async): callback to call after resolution completes
32169 * @user_data: (closure): data for @callback
32171 * Begins asynchronously resolving @hostname to determine its
32172 * associated IP address(es), and eventually calls @callback, which
32173 * must call g_resolver_lookup_by_name_finish() to get the result.
32174 * See g_resolver_lookup_by_name() for more details.
32181 * g_resolver_lookup_by_name_finish:
32182 * @resolver: a #GResolver
32183 * @result: the result passed to your #GAsyncReadyCallback
32184 * @error: return location for a #GError, or %NULL
32186 * Retrieves the result of a call to
32187 * g_resolver_lookup_by_name_async().
32189 * If the DNS resolution failed, @error (if non-%NULL) will be set to
32190 * a value from #GResolverError. If the operation was cancelled,
32191 * @error will be set to %G_IO_ERROR_CANCELLED.
32193 * Returns: (element-type GInetAddress) (transfer full): a #GList
32194 * of #GInetAddress, or %NULL on error. See g_resolver_lookup_by_name()
32195 * for more details.
32201 * g_resolver_lookup_by_name_with_flags:
32202 * @resolver: a #GResolver
32203 * @hostname: the hostname to look up
32204 * @flags: extra #GResolverNameLookupFlags for the lookup
32205 * @cancellable: (nullable): a #GCancellable, or %NULL
32206 * @error: (nullable): return location for a #GError, or %NULL
32208 * This differs from g_resolver_lookup_by_name() in that you can modify
32209 * the lookup behavior with @flags. For example this can be used to limit
32210 * results with #G_RESOLVER_NAME_LOOKUP_FLAGS_IPV4_ONLY.
32212 * Returns: (element-type GInetAddress) (transfer full): a non-empty #GList
32213 * of #GInetAddress, or %NULL on error. You
32214 * must unref each of the addresses and free the list when you are
32215 * done with it. (You can use g_resolver_free_addresses() to do this.)
32221 * g_resolver_lookup_by_name_with_flags_async:
32222 * @resolver: a #GResolver
32223 * @hostname: the hostname to look up the address of
32224 * @flags: extra #GResolverNameLookupFlags for the lookup
32225 * @cancellable: (nullable): a #GCancellable, or %NULL
32226 * @callback: (scope async): callback to call after resolution completes
32227 * @user_data: (closure): data for @callback
32229 * Begins asynchronously resolving @hostname to determine its
32230 * associated IP address(es), and eventually calls @callback, which
32231 * must call g_resolver_lookup_by_name_with_flags_finish() to get the result.
32232 * See g_resolver_lookup_by_name() for more details.
32239 * g_resolver_lookup_by_name_with_flags_finish:
32240 * @resolver: a #GResolver
32241 * @result: the result passed to your #GAsyncReadyCallback
32242 * @error: return location for a #GError, or %NULL
32244 * Retrieves the result of a call to
32245 * g_resolver_lookup_by_name_with_flags_async().
32247 * If the DNS resolution failed, @error (if non-%NULL) will be set to
32248 * a value from #GResolverError. If the operation was cancelled,
32249 * @error will be set to %G_IO_ERROR_CANCELLED.
32251 * Returns: (element-type GInetAddress) (transfer full): a #GList
32252 * of #GInetAddress, or %NULL on error. See g_resolver_lookup_by_name()
32253 * for more details.
32259 * g_resolver_lookup_records:
32260 * @resolver: a #GResolver
32261 * @rrname: the DNS name to look up the record for
32262 * @record_type: the type of DNS record to look up
32263 * @cancellable: (nullable): a #GCancellable, or %NULL
32264 * @error: return location for a #GError, or %NULL
32266 * Synchronously performs a DNS record lookup for the given @rrname and returns
32267 * a list of records as #GVariant tuples. See #GResolverRecordType for
32268 * information on what the records contain for each @record_type.
32270 * If the DNS resolution fails, @error (if non-%NULL) will be set to
32271 * a value from #GResolverError and %NULL will be returned.
32273 * If @cancellable is non-%NULL, it can be used to cancel the
32274 * operation, in which case @error (if non-%NULL) will be set to
32275 * %G_IO_ERROR_CANCELLED.
32277 * Returns: (element-type GVariant) (transfer full): a non-empty #GList of
32278 * #GVariant, or %NULL on error. You must free each of the records and the list
32279 * when you are done with it. (You can use g_list_free_full() with
32280 * g_variant_unref() to do this.)
32286 * g_resolver_lookup_records_async:
32287 * @resolver: a #GResolver
32288 * @rrname: the DNS name to look up the record for
32289 * @record_type: the type of DNS record to look up
32290 * @cancellable: (nullable): a #GCancellable, or %NULL
32291 * @callback: (scope async): callback to call after resolution completes
32292 * @user_data: (closure): data for @callback
32294 * Begins asynchronously performing a DNS lookup for the given
32295 * @rrname, and eventually calls @callback, which must call
32296 * g_resolver_lookup_records_finish() to get the final result. See
32297 * g_resolver_lookup_records() for more details.
32304 * g_resolver_lookup_records_finish:
32305 * @resolver: a #GResolver
32306 * @result: the result passed to your #GAsyncReadyCallback
32307 * @error: return location for a #GError, or %NULL
32309 * Retrieves the result of a previous call to
32310 * g_resolver_lookup_records_async(). Returns a non-empty list of records as
32311 * #GVariant tuples. See #GResolverRecordType for information on what the
32314 * If the DNS resolution failed, @error (if non-%NULL) will be set to
32315 * a value from #GResolverError. If the operation was cancelled,
32316 * @error will be set to %G_IO_ERROR_CANCELLED.
32318 * Returns: (element-type GVariant) (transfer full): a non-empty #GList of
32319 * #GVariant, or %NULL on error. You must free each of the records and the list
32320 * when you are done with it. (You can use g_list_free_full() with
32321 * g_variant_unref() to do this.)
32327 * g_resolver_lookup_service:
32328 * @resolver: a #GResolver
32329 * @service: the service type to look up (eg, "ldap")
32330 * @protocol: the networking protocol to use for @service (eg, "tcp")
32331 * @domain: the DNS domain to look up the service in
32332 * @cancellable: (nullable): a #GCancellable, or %NULL
32333 * @error: return location for a #GError, or %NULL
32335 * Synchronously performs a DNS SRV lookup for the given @service and
32336 * @protocol in the given @domain and returns an array of #GSrvTarget.
32337 * @domain may be an ASCII-only or UTF-8 hostname. Note also that the
32338 * @service and @protocol arguments do not include the leading underscore
32339 * that appears in the actual DNS entry.
32341 * On success, g_resolver_lookup_service() will return a non-empty #GList of
32342 * #GSrvTarget, sorted in order of preference. (That is, you should
32343 * attempt to connect to the first target first, then the second if
32344 * the first fails, etc.)
32346 * If the DNS resolution fails, @error (if non-%NULL) will be set to
32347 * a value from #GResolverError and %NULL will be returned.
32349 * If @cancellable is non-%NULL, it can be used to cancel the
32350 * operation, in which case @error (if non-%NULL) will be set to
32351 * %G_IO_ERROR_CANCELLED.
32353 * If you are planning to connect to the service, it is usually easier
32354 * to create a #GNetworkService and use its #GSocketConnectable
32357 * Returns: (element-type GSrvTarget) (transfer full): a non-empty #GList of
32358 * #GSrvTarget, or %NULL on error. You must free each of the targets and the
32359 * list when you are done with it. (You can use g_resolver_free_targets() to do
32366 * g_resolver_lookup_service_async:
32367 * @resolver: a #GResolver
32368 * @service: the service type to look up (eg, "ldap")
32369 * @protocol: the networking protocol to use for @service (eg, "tcp")
32370 * @domain: the DNS domain to look up the service in
32371 * @cancellable: (nullable): a #GCancellable, or %NULL
32372 * @callback: (scope async): callback to call after resolution completes
32373 * @user_data: (closure): data for @callback
32375 * Begins asynchronously performing a DNS SRV lookup for the given
32376 * @service and @protocol in the given @domain, and eventually calls
32377 * @callback, which must call g_resolver_lookup_service_finish() to
32378 * get the final result. See g_resolver_lookup_service() for more
32386 * g_resolver_lookup_service_finish:
32387 * @resolver: a #GResolver
32388 * @result: the result passed to your #GAsyncReadyCallback
32389 * @error: return location for a #GError, or %NULL
32391 * Retrieves the result of a previous call to
32392 * g_resolver_lookup_service_async().
32394 * If the DNS resolution failed, @error (if non-%NULL) will be set to
32395 * a value from #GResolverError. If the operation was cancelled,
32396 * @error will be set to %G_IO_ERROR_CANCELLED.
32398 * Returns: (element-type GSrvTarget) (transfer full): a non-empty #GList of
32399 * #GSrvTarget, or %NULL on error. See g_resolver_lookup_service() for more
32406 * g_resolver_set_default:
32407 * @resolver: the new default #GResolver
32409 * Sets @resolver to be the application's default resolver (reffing
32410 * @resolver, and unreffing the previous default resolver, if any).
32411 * Future calls to g_resolver_get_default() will return this resolver.
32413 * This can be used if an application wants to perform any sort of DNS
32414 * caching or "pinning"; it can implement its own #GResolver that
32415 * calls the original default resolver for DNS operations, and
32416 * implements its own cache policies on top of that, and then set
32417 * itself as the default resolver for all later code to use.
32424 * g_resource_enumerate_children:
32425 * @resource: A #GResource
32426 * @path: A pathname inside the resource
32427 * @lookup_flags: A #GResourceLookupFlags
32428 * @error: return location for a #GError, or %NULL
32430 * Returns all the names of children at the specified @path in the resource.
32431 * The return result is a %NULL terminated list of strings which should
32432 * be released with g_strfreev().
32434 * If @path is invalid or does not exist in the #GResource,
32435 * %G_RESOURCE_ERROR_NOT_FOUND will be returned.
32437 * @lookup_flags controls the behaviour of the lookup.
32439 * Returns: (array zero-terminated=1) (transfer full): an array of constant strings
32445 * g_resource_error_quark:
32447 * Gets the #GResource Error Quark.
32449 * Returns: a #GQuark
32455 * g_resource_get_info:
32456 * @resource: A #GResource
32457 * @path: A pathname inside the resource
32458 * @lookup_flags: A #GResourceLookupFlags
32459 * @size: (out) (optional): a location to place the length of the contents of the file,
32460 * or %NULL if the length is not needed
32461 * @flags: (out) (optional): a location to place the flags about the file,
32462 * or %NULL if the length is not needed
32463 * @error: return location for a #GError, or %NULL
32465 * Looks for a file at the specified @path in the resource and
32466 * if found returns information about it.
32468 * @lookup_flags controls the behaviour of the lookup.
32470 * Returns: %TRUE if the file was found. %FALSE if there were errors
32477 * @filename: (type filename): the path of a filename to load, in the GLib filename encoding
32478 * @error: return location for a #GError, or %NULL
32480 * Loads a binary resource bundle and creates a #GResource representation of it, allowing
32481 * you to query it for data.
32483 * If you want to use this resource in the global resource namespace you need
32484 * to register it with g_resources_register().
32486 * If @filename is empty or the data in it is corrupt,
32487 * %G_RESOURCE_ERROR_INTERNAL will be returned. If @filename doesn’t exist, or
32488 * there is an error in reading it, an error from g_mapped_file_new() will be
32491 * Returns: (transfer full): a new #GResource, or %NULL on error
32497 * g_resource_lookup_data:
32498 * @resource: A #GResource
32499 * @path: A pathname inside the resource
32500 * @lookup_flags: A #GResourceLookupFlags
32501 * @error: return location for a #GError, or %NULL
32503 * Looks for a file at the specified @path in the resource and
32504 * returns a #GBytes that lets you directly access the data in
32507 * The data is always followed by a zero byte, so you
32508 * can safely use the data as a C string. However, that byte
32509 * is not included in the size of the GBytes.
32511 * For uncompressed resource files this is a pointer directly into
32512 * the resource bundle, which is typically in some readonly data section
32513 * in the program binary. For compressed files we allocate memory on
32514 * the heap and automatically uncompress the data.
32516 * @lookup_flags controls the behaviour of the lookup.
32518 * Returns: (transfer full): #GBytes or %NULL on error.
32519 * Free the returned object with g_bytes_unref()
32525 * g_resource_new_from_data:
32527 * @error: return location for a #GError, or %NULL
32529 * Creates a GResource from a reference to the binary resource bundle.
32530 * This will keep a reference to @data while the resource lives, so
32531 * the data should not be modified or freed.
32533 * If you want to use this resource in the global resource namespace you need
32534 * to register it with g_resources_register().
32536 * Note: @data must be backed by memory that is at least pointer aligned.
32537 * Otherwise this function will internally create a copy of the memory since
32538 * GLib 2.56, or in older versions fail and exit the process.
32540 * If @data is empty or corrupt, %G_RESOURCE_ERROR_INTERNAL will be returned.
32542 * Returns: (transfer full): a new #GResource, or %NULL on error
32548 * g_resource_open_stream:
32549 * @resource: A #GResource
32550 * @path: A pathname inside the resource
32551 * @lookup_flags: A #GResourceLookupFlags
32552 * @error: return location for a #GError, or %NULL
32554 * Looks for a file at the specified @path in the resource and
32555 * returns a #GInputStream that lets you read the data.
32557 * @lookup_flags controls the behaviour of the lookup.
32559 * Returns: (transfer full): #GInputStream or %NULL on error.
32560 * Free the returned object with g_object_unref()
32567 * @resource: A #GResource
32569 * Atomically increments the reference count of @resource by one. This
32570 * function is MT-safe and may be called from any thread.
32572 * Returns: The passed in #GResource
32578 * g_resource_unref:
32579 * @resource: A #GResource
32581 * Atomically decrements the reference count of @resource by one. If the
32582 * reference count drops to 0, all memory allocated by the resource is
32583 * released. This function is MT-safe and may be called from any
32591 * g_resources_enumerate_children:
32592 * @path: A pathname inside the resource
32593 * @lookup_flags: A #GResourceLookupFlags
32594 * @error: return location for a #GError, or %NULL
32596 * Returns all the names of children at the specified @path in the set of
32597 * globally registered resources.
32598 * The return result is a %NULL terminated list of strings which should
32599 * be released with g_strfreev().
32601 * @lookup_flags controls the behaviour of the lookup.
32603 * Returns: (array zero-terminated=1) (transfer full): an array of constant strings
32609 * g_resources_get_info:
32610 * @path: A pathname inside the resource
32611 * @lookup_flags: A #GResourceLookupFlags
32612 * @size: (out) (optional): a location to place the length of the contents of the file,
32613 * or %NULL if the length is not needed
32614 * @flags: (out) (optional): a location to place the #GResourceFlags about the file,
32615 * or %NULL if the flags are not needed
32616 * @error: return location for a #GError, or %NULL
32618 * Looks for a file at the specified @path in the set of
32619 * globally registered resources and if found returns information about it.
32621 * @lookup_flags controls the behaviour of the lookup.
32623 * Returns: %TRUE if the file was found. %FALSE if there were errors
32629 * g_resources_lookup_data:
32630 * @path: A pathname inside the resource
32631 * @lookup_flags: A #GResourceLookupFlags
32632 * @error: return location for a #GError, or %NULL
32634 * Looks for a file at the specified @path in the set of
32635 * globally registered resources and returns a #GBytes that
32636 * lets you directly access the data in memory.
32638 * The data is always followed by a zero byte, so you
32639 * can safely use the data as a C string. However, that byte
32640 * is not included in the size of the GBytes.
32642 * For uncompressed resource files this is a pointer directly into
32643 * the resource bundle, which is typically in some readonly data section
32644 * in the program binary. For compressed files we allocate memory on
32645 * the heap and automatically uncompress the data.
32647 * @lookup_flags controls the behaviour of the lookup.
32649 * Returns: (transfer full): #GBytes or %NULL on error.
32650 * Free the returned object with g_bytes_unref()
32656 * g_resources_open_stream:
32657 * @path: A pathname inside the resource
32658 * @lookup_flags: A #GResourceLookupFlags
32659 * @error: return location for a #GError, or %NULL
32661 * Looks for a file at the specified @path in the set of
32662 * globally registered resources and returns a #GInputStream
32663 * that lets you read the data.
32665 * @lookup_flags controls the behaviour of the lookup.
32667 * Returns: (transfer full): #GInputStream or %NULL on error.
32668 * Free the returned object with g_object_unref()
32674 * g_resources_register:
32675 * @resource: A #GResource
32677 * Registers the resource with the process-global set of resources.
32678 * Once a resource is registered the files in it can be accessed
32679 * with the global resource lookup functions like g_resources_lookup_data().
32686 * g_resources_unregister:
32687 * @resource: A #GResource
32689 * Unregisters the resource from the process-global set of resources.
32696 * g_seekable_can_seek:
32697 * @seekable: a #GSeekable.
32699 * Tests if the stream supports the #GSeekableIface.
32701 * Returns: %TRUE if @seekable can be seeked. %FALSE otherwise.
32706 * g_seekable_can_truncate:
32707 * @seekable: a #GSeekable.
32709 * Tests if the length of the stream can be adjusted with
32710 * g_seekable_truncate().
32712 * Returns: %TRUE if the stream can be truncated, %FALSE otherwise.
32718 * @seekable: a #GSeekable.
32719 * @offset: a #goffset.
32720 * @type: a #GSeekType.
32721 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
32722 * @error: a #GError location to store the error occurring, or %NULL to
32725 * Seeks in the stream by the given @offset, modified by @type.
32727 * Attempting to seek past the end of the stream will have different
32728 * results depending on if the stream is fixed-sized or resizable. If
32729 * the stream is resizable then seeking past the end and then writing
32730 * will result in zeros filling the empty space. Seeking past the end
32731 * of a resizable stream and reading will result in EOF. Seeking past
32732 * the end of a fixed-sized stream will fail.
32734 * Any operation that would result in a negative offset will fail.
32736 * If @cancellable is not %NULL, then the operation can be cancelled by
32737 * triggering the cancellable object from another thread. If the operation
32738 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
32740 * Returns: %TRUE if successful. If an error
32741 * has occurred, this function will return %FALSE and set @error
32742 * appropriately if present.
32748 * @seekable: a #GSeekable.
32750 * Tells the current position within the stream.
32752 * Returns: the (positive or zero) offset from the beginning of the
32753 * buffer, zero if the target is not seekable.
32758 * g_seekable_truncate: (virtual truncate_fn)
32759 * @seekable: a #GSeekable.
32760 * @offset: new length for @seekable, in bytes.
32761 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
32762 * @error: a #GError location to store the error occurring, or %NULL to
32765 * Sets the length of the stream to @offset. If the stream was previously
32766 * larger than @offset, the extra data is discarded. If the stream was
32767 * previously shorter than @offset, it is extended with NUL ('\0') bytes.
32769 * If @cancellable is not %NULL, then the operation can be cancelled by
32770 * triggering the cancellable object from another thread. If the operation
32771 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
32772 * operation was partially finished when the operation was cancelled the
32773 * partial result will be returned, without an error.
32775 * Returns: %TRUE if successful. If an error
32776 * has occurred, this function will return %FALSE and set @error
32777 * appropriately if present.
32782 * g_settings_apply:
32783 * @settings: a #GSettings instance
32785 * Applies any changes that have been made to the settings. This
32786 * function does nothing unless @settings is in 'delay-apply' mode;
32787 * see g_settings_delay(). In the normal case settings are always
32788 * applied immediately.
32793 * g_settings_backend_changed:
32794 * @backend: a #GSettingsBackend implementation
32795 * @key: the name of the key
32796 * @origin_tag: the origin tag
32798 * Signals that a single key has possibly changed. Backend
32799 * implementations should call this if a key has possibly changed its
32802 * @key must be a valid key (ie starting with a slash, not containing
32803 * '//', and not ending with a slash).
32805 * The implementation must call this function during any call to
32806 * g_settings_backend_write(), before the call returns (except in the
32807 * case that no keys are actually changed and it cares to detect this
32808 * fact). It may not rely on the existence of a mainloop for
32809 * dispatching the signal later.
32811 * The implementation may call this function at any other time it likes
32812 * in response to other events (such as changes occurring outside of the
32813 * program). These calls may originate from a mainloop or may originate
32814 * in response to any other action (including from calls to
32815 * g_settings_backend_write()).
32817 * In the case that this call is in response to a call to
32818 * g_settings_backend_write() then @origin_tag must be set to the same
32819 * value that was passed to that call.
32826 * g_settings_backend_changed_tree:
32827 * @backend: a #GSettingsBackend implementation
32828 * @tree: a #GTree containing the changes
32829 * @origin_tag: the origin tag
32831 * This call is a convenience wrapper. It gets the list of changes from
32832 * @tree, computes the longest common prefix and calls
32833 * g_settings_backend_changed().
32840 * g_settings_backend_flatten_tree:
32841 * @tree: a #GTree containing the changes
32842 * @path: (out): the location to save the path
32843 * @keys: (out) (transfer container) (array zero-terminated=1): the
32844 * location to save the relative keys
32845 * @values: (out) (optional) (transfer container) (array zero-terminated=1):
32846 * the location to save the values, or %NULL
32848 * Calculate the longest common prefix of all keys in a tree and write
32849 * out an array of the key names relative to that prefix and,
32850 * optionally, the value to store at each of those keys.
32852 * You must free the value returned in @path, @keys and @values using
32853 * g_free(). You should not attempt to free or unref the contents of
32854 * @keys or @values.
32861 * g_settings_backend_get_default:
32863 * Returns the default #GSettingsBackend. It is possible to override
32864 * the default by setting the `GSETTINGS_BACKEND` environment variable
32865 * to the name of a settings backend.
32867 * The user gets a reference to the backend.
32869 * Returns: (not nullable) (transfer full): the default #GSettingsBackend,
32870 * which will be a dummy (memory) settings backend if no other settings
32871 * backend is available.
32877 * g_settings_backend_keys_changed:
32878 * @backend: a #GSettingsBackend implementation
32879 * @path: the path containing the changes
32880 * @items: (array zero-terminated=1): the %NULL-terminated list of changed keys
32881 * @origin_tag: the origin tag
32883 * Signals that a list of keys have possibly changed. Backend
32884 * implementations should call this if keys have possibly changed their
32887 * @path must be a valid path (ie starting and ending with a slash and
32888 * not containing '//'). Each string in @items must form a valid key
32889 * name when @path is prefixed to it (ie: each item must not start or
32890 * end with '/' and must not contain '//').
32892 * The meaning of this signal is that any of the key names resulting
32893 * from the contatenation of @path with each item in @items may have
32896 * The same rules for when notifications must occur apply as per
32897 * g_settings_backend_changed(). These two calls can be used
32898 * interchangeably if exactly one item has changed (although in that
32899 * case g_settings_backend_changed() is definitely preferred).
32901 * For efficiency reasons, the implementation should strive for @path to
32902 * be as long as possible (ie: the longest common prefix of all of the
32903 * keys that were changed) but this is not strictly required.
32910 * g_settings_backend_path_changed:
32911 * @backend: a #GSettingsBackend implementation
32912 * @path: the path containing the changes
32913 * @origin_tag: the origin tag
32915 * Signals that all keys below a given path may have possibly changed.
32916 * Backend implementations should call this if an entire path of keys
32917 * have possibly changed their values.
32919 * @path must be a valid path (ie starting and ending with a slash and
32920 * not containing '//').
32922 * The meaning of this signal is that any of the key which has a name
32923 * starting with @path may have changed.
32925 * The same rules for when notifications must occur apply as per
32926 * g_settings_backend_changed(). This call might be an appropriate
32927 * reasponse to a 'reset' call but implementations are also free to
32928 * explicitly list the keys that were affected by that call if they can
32931 * For efficiency reasons, the implementation should strive for @path to
32932 * be as long as possible (ie: the longest common prefix of all of the
32933 * keys that were changed) but this is not strictly required. As an
32934 * example, if this function is called with the path of "/" then every
32935 * single key in the application will be notified of a possible change.
32942 * g_settings_backend_path_writable_changed:
32943 * @backend: a #GSettingsBackend implementation
32944 * @path: the name of the path
32946 * Signals that the writability of all keys below a given path may have
32949 * Since GSettings performs no locking operations for itself, this call
32950 * will always be made in response to external events.
32957 * g_settings_backend_writable_changed:
32958 * @backend: a #GSettingsBackend implementation
32959 * @key: the name of the key
32961 * Signals that the writability of a single key has possibly changed.
32963 * Since GSettings performs no locking operations for itself, this call
32964 * will always be made in response to external events.
32972 * @settings: a #GSettings object
32973 * @key: the key to bind
32974 * @object: (type GObject.Object): a #GObject
32975 * @property: the name of the property to bind
32976 * @flags: flags for the binding
32978 * Create a binding between the @key in the @settings object
32979 * and the property @property of @object.
32981 * The binding uses the default GIO mapping functions to map
32982 * between the settings and property values. These functions
32983 * handle booleans, numeric types and string types in a
32984 * straightforward way. Use g_settings_bind_with_mapping() if
32985 * you need a custom mapping, or map between types that are not
32986 * supported by the default mapping functions.
32988 * Unless the @flags include %G_SETTINGS_BIND_NO_SENSITIVITY, this
32989 * function also establishes a binding between the writability of
32990 * @key and the "sensitive" property of @object (if @object has
32991 * a boolean property by that name). See g_settings_bind_writable()
32992 * for more details about writable bindings.
32994 * Note that the lifecycle of the binding is tied to @object,
32995 * and that you can have only one binding per object property.
32996 * If you bind the same property twice on the same object, the second
32997 * binding overrides the first one.
33004 * g_settings_bind_with_mapping: (skip)
33005 * @settings: a #GSettings object
33006 * @key: the key to bind
33007 * @object: (type GObject.Object): a #GObject
33008 * @property: the name of the property to bind
33009 * @flags: flags for the binding
33010 * @get_mapping: a function that gets called to convert values
33011 * from @settings to @object, or %NULL to use the default GIO mapping
33012 * @set_mapping: a function that gets called to convert values
33013 * from @object to @settings, or %NULL to use the default GIO mapping
33014 * @user_data: data that gets passed to @get_mapping and @set_mapping
33015 * @destroy: #GDestroyNotify function for @user_data
33017 * Create a binding between the @key in the @settings object
33018 * and the property @property of @object.
33020 * The binding uses the provided mapping functions to map between
33021 * settings and property values.
33023 * Note that the lifecycle of the binding is tied to @object,
33024 * and that you can have only one binding per object property.
33025 * If you bind the same property twice on the same object, the second
33026 * binding overrides the first one.
33033 * g_settings_bind_writable:
33034 * @settings: a #GSettings object
33035 * @key: the key to bind
33036 * @object: (type GObject.Object): a #GObject
33037 * @property: the name of a boolean property to bind
33038 * @inverted: whether to 'invert' the value
33040 * Create a binding between the writability of @key in the
33041 * @settings object and the property @property of @object.
33042 * The property must be boolean; "sensitive" or "visible"
33043 * properties of widgets are the most likely candidates.
33045 * Writable bindings are always uni-directional; changes of the
33046 * writability of the setting will be propagated to the object
33047 * property, not the other way.
33049 * When the @inverted argument is %TRUE, the binding inverts the
33050 * value as it passes from the setting to the object, i.e. @property
33051 * will be set to %TRUE if the key is not writable.
33053 * Note that the lifecycle of the binding is tied to @object,
33054 * and that you can have only one binding per object property.
33055 * If you bind the same property twice on the same object, the second
33056 * binding overrides the first one.
33063 * g_settings_create_action:
33064 * @settings: a #GSettings
33065 * @key: the name of a key in @settings
33067 * Creates a #GAction corresponding to a given #GSettings key.
33069 * The action has the same name as the key.
33071 * The value of the key becomes the state of the action and the action
33072 * is enabled when the key is writable. Changing the state of the
33073 * action results in the key being written to. Changes to the value or
33074 * writability of the key cause appropriate change notifications to be
33075 * emitted for the action.
33077 * For boolean-valued keys, action activations take no parameter and
33078 * result in the toggling of the value. For all other types,
33079 * activations take the new value for the key (which must have the
33082 * Returns: (transfer full): a new #GAction
33088 * g_settings_delay:
33089 * @settings: a #GSettings object
33091 * Changes the #GSettings object into 'delay-apply' mode. In this
33092 * mode, changes to @settings are not immediately propagated to the
33093 * backend, but kept locally until g_settings_apply() is called.
33101 * @settings: a #GSettings object
33102 * @key: the key to get the value for
33103 * @format: a #GVariant format string
33104 * @...: arguments as per @format
33106 * Gets the value that is stored at @key in @settings.
33108 * A convenience function that combines g_settings_get_value() with
33111 * It is a programmer error to give a @key that isn't contained in the
33112 * schema for @settings or for the #GVariantType of @format to mismatch
33113 * the type given in the schema.
33120 * g_settings_get_boolean:
33121 * @settings: a #GSettings object
33122 * @key: the key to get the value for
33124 * Gets the value that is stored at @key in @settings.
33126 * A convenience variant of g_settings_get() for booleans.
33128 * It is a programmer error to give a @key that isn't specified as
33129 * having a boolean type in the schema for @settings.
33131 * Returns: a boolean
33137 * g_settings_get_child:
33138 * @settings: a #GSettings object
33139 * @name: the name of the child schema
33141 * Creates a child settings object which has a base path of
33142 * `base-path/@name`, where `base-path` is the base path of
33145 * The schema for the child settings object must have been declared
33146 * in the schema of @settings using a <child> element.
33148 * Returns: (transfer full): a 'child' settings object
33154 * g_settings_get_default_value:
33155 * @settings: a #GSettings object
33156 * @key: the key to get the default value for
33158 * Gets the "default value" of a key.
33160 * This is the value that would be read if g_settings_reset() were to be
33161 * called on the key.
33163 * Note that this may be a different value than returned by
33164 * g_settings_schema_key_get_default_value() if the system administrator
33165 * has provided a default value.
33167 * Comparing the return values of g_settings_get_default_value() and
33168 * g_settings_get_value() is not sufficient for determining if a value
33169 * has been set because the user may have explicitly set the value to
33170 * something that happens to be equal to the default. The difference
33171 * here is that if the default changes in the future, the user's key
33172 * will still be set.
33174 * This function may be useful for adding an indication to a UI of what
33175 * the default value was before the user set it.
33177 * It is a programmer error to give a @key that isn't contained in the
33178 * schema for @settings.
33180 * Returns: (nullable) (transfer full): the default value
33186 * g_settings_get_double:
33187 * @settings: a #GSettings object
33188 * @key: the key to get the value for
33190 * Gets the value that is stored at @key in @settings.
33192 * A convenience variant of g_settings_get() for doubles.
33194 * It is a programmer error to give a @key that isn't specified as
33195 * having a 'double' type in the schema for @settings.
33197 * Returns: a double
33203 * g_settings_get_enum:
33204 * @settings: a #GSettings object
33205 * @key: the key to get the value for
33207 * Gets the value that is stored in @settings for @key and converts it
33208 * to the enum value that it represents.
33210 * In order to use this function the type of the value must be a string
33211 * and it must be marked in the schema file as an enumerated type.
33213 * It is a programmer error to give a @key that isn't contained in the
33214 * schema for @settings or is not marked as an enumerated type.
33216 * If the value stored in the configuration database is not a valid
33217 * value for the enumerated type then this function will return the
33220 * Returns: the enum value
33226 * g_settings_get_flags:
33227 * @settings: a #GSettings object
33228 * @key: the key to get the value for
33230 * Gets the value that is stored in @settings for @key and converts it
33231 * to the flags value that it represents.
33233 * In order to use this function the type of the value must be an array
33234 * of strings and it must be marked in the schema file as a flags type.
33236 * It is a programmer error to give a @key that isn't contained in the
33237 * schema for @settings or is not marked as a flags type.
33239 * If the value stored in the configuration database is not a valid
33240 * value for the flags type then this function will return the default
33243 * Returns: the flags value
33249 * g_settings_get_has_unapplied:
33250 * @settings: a #GSettings object
33252 * Returns whether the #GSettings object has any unapplied
33253 * changes. This can only be the case if it is in 'delayed-apply' mode.
33255 * Returns: %TRUE if @settings has unapplied changes
33261 * g_settings_get_int:
33262 * @settings: a #GSettings object
33263 * @key: the key to get the value for
33265 * Gets the value that is stored at @key in @settings.
33267 * A convenience variant of g_settings_get() for 32-bit integers.
33269 * It is a programmer error to give a @key that isn't specified as
33270 * having a int32 type in the schema for @settings.
33272 * Returns: an integer
33278 * g_settings_get_int64:
33279 * @settings: a #GSettings object
33280 * @key: the key to get the value for
33282 * Gets the value that is stored at @key in @settings.
33284 * A convenience variant of g_settings_get() for 64-bit integers.
33286 * It is a programmer error to give a @key that isn't specified as
33287 * having a int64 type in the schema for @settings.
33289 * Returns: a 64-bit integer
33295 * g_settings_get_mapped:
33296 * @settings: a #GSettings object
33297 * @key: the key to get the value for
33298 * @mapping: (scope call): the function to map the value in the
33299 * settings database to the value used by the application
33300 * @user_data: user data for @mapping
33302 * Gets the value that is stored at @key in @settings, subject to
33303 * application-level validation/mapping.
33305 * You should use this function when the application needs to perform
33306 * some processing on the value of the key (for example, parsing). The
33307 * @mapping function performs that processing. If the function
33308 * indicates that the processing was unsuccessful (due to a parse error,
33309 * for example) then the mapping is tried again with another value.
33311 * This allows a robust 'fall back to defaults' behaviour to be
33312 * implemented somewhat automatically.
33314 * The first value that is tried is the user's setting for the key. If
33315 * the mapping function fails to map this value, other values may be
33316 * tried in an unspecified order (system or site defaults, translated
33317 * schema default values, untranslated schema default values, etc).
33319 * If the mapping function fails for all possible values, one additional
33320 * attempt is made: the mapping function is called with a %NULL value.
33321 * If the mapping function still indicates failure at this point then
33322 * the application will be aborted.
33324 * The result parameter for the @mapping function is pointed to a
33325 * #gpointer which is initially set to %NULL. The same pointer is given
33326 * to each invocation of @mapping. The final value of that #gpointer is
33327 * what is returned by this function. %NULL is valid; it is returned
33328 * just as any other value would be.
33330 * Returns: (transfer full): the result, which may be %NULL
33335 * g_settings_get_range:
33336 * @settings: a #GSettings
33337 * @key: the key to query the range of
33339 * Queries the range of a key.
33342 * Deprecated: 2.40: Use g_settings_schema_key_get_range() instead.
33347 * g_settings_get_string:
33348 * @settings: a #GSettings object
33349 * @key: the key to get the value for
33351 * Gets the value that is stored at @key in @settings.
33353 * A convenience variant of g_settings_get() for strings.
33355 * It is a programmer error to give a @key that isn't specified as
33356 * having a string type in the schema for @settings.
33358 * Returns: a newly-allocated string
33364 * g_settings_get_strv:
33365 * @settings: a #GSettings object
33366 * @key: the key to get the value for
33368 * A convenience variant of g_settings_get() for string arrays.
33370 * It is a programmer error to give a @key that isn't specified as
33371 * having an array of strings type in the schema for @settings.
33373 * Returns: (array zero-terminated=1) (transfer full): a
33374 * newly-allocated, %NULL-terminated array of strings, the value that
33375 * is stored at @key in @settings.
33381 * g_settings_get_uint:
33382 * @settings: a #GSettings object
33383 * @key: the key to get the value for
33385 * Gets the value that is stored at @key in @settings.
33387 * A convenience variant of g_settings_get() for 32-bit unsigned
33390 * It is a programmer error to give a @key that isn't specified as
33391 * having a uint32 type in the schema for @settings.
33393 * Returns: an unsigned integer
33399 * g_settings_get_uint64:
33400 * @settings: a #GSettings object
33401 * @key: the key to get the value for
33403 * Gets the value that is stored at @key in @settings.
33405 * A convenience variant of g_settings_get() for 64-bit unsigned
33408 * It is a programmer error to give a @key that isn't specified as
33409 * having a uint64 type in the schema for @settings.
33411 * Returns: a 64-bit unsigned integer
33417 * g_settings_get_user_value:
33418 * @settings: a #GSettings object
33419 * @key: the key to get the user value for
33421 * Checks the "user value" of a key, if there is one.
33423 * The user value of a key is the last value that was set by the user.
33425 * After calling g_settings_reset() this function should always return
33426 * %NULL (assuming something is not wrong with the system
33429 * It is possible that g_settings_get_value() will return a different
33430 * value than this function. This can happen in the case that the user
33431 * set a value for a key that was subsequently locked down by the system
33432 * administrator -- this function will return the user's old value.
33434 * This function may be useful for adding a "reset" option to a UI or
33435 * for providing indication that a particular value has been changed.
33437 * It is a programmer error to give a @key that isn't contained in the
33438 * schema for @settings.
33440 * Returns: (nullable) (transfer full): the user's value, if set
33446 * g_settings_get_value:
33447 * @settings: a #GSettings object
33448 * @key: the key to get the value for
33450 * Gets the value that is stored in @settings for @key.
33452 * It is a programmer error to give a @key that isn't contained in the
33453 * schema for @settings.
33455 * Returns: a new #GVariant
33461 * g_settings_is_writable:
33462 * @settings: a #GSettings object
33463 * @name: the name of a key
33465 * Finds out if a key can be written or not
33467 * Returns: %TRUE if the key @name is writable
33473 * g_settings_list_children:
33474 * @settings: a #GSettings object
33476 * Gets the list of children on @settings.
33478 * The list is exactly the list of strings for which it is not an error
33479 * to call g_settings_get_child().
33481 * There is little reason to call this function from "normal" code, since
33482 * you should already know what children are in your schema. This function
33483 * may still be useful there for introspection reasons, however.
33485 * You should free the return value with g_strfreev() when you are done
33488 * Returns: (transfer full) (element-type utf8): a list of the children on
33489 * @settings, in no defined order
33494 * g_settings_list_keys:
33495 * @settings: a #GSettings object
33497 * Introspects the list of keys on @settings.
33499 * You should probably not be calling this function from "normal" code
33500 * (since you should already know what keys are in your schema). This
33501 * function is intended for introspection reasons.
33503 * You should free the return value with g_strfreev() when you are done
33506 * Returns: (transfer full) (element-type utf8): a list of the keys on
33507 * @settings, in no defined order
33508 * Deprecated: 2.46: Use g_settings_schema_list_keys() instead.
33513 * g_settings_list_relocatable_schemas:
33517 * Returns: (element-type utf8) (transfer none): a list of relocatable
33518 * #GSettings schemas that are available, in no defined order. The list must
33519 * not be modified or freed.
33521 * Deprecated: 2.40: Use g_settings_schema_source_list_schemas() instead
33526 * g_settings_list_schemas:
33530 * Returns: (element-type utf8) (transfer none): a list of #GSettings
33531 * schemas that are available, in no defined order. The list must not be
33532 * modified or freed.
33534 * Deprecated: 2.40: Use g_settings_schema_source_list_schemas() instead.
33535 * If you used g_settings_list_schemas() to check for the presence of
33536 * a particular schema, use g_settings_schema_source_lookup() instead
33537 * of your whole loop.
33543 * @schema_id: the id of the schema
33545 * Creates a new #GSettings object with the schema specified by
33548 * It is an error for the schema to not exist: schemas are an
33549 * essential part of a program, as they provide type information.
33550 * If schemas need to be dynamically loaded (for example, from an
33551 * optional runtime dependency), g_settings_schema_source_lookup()
33552 * can be used to test for their existence before loading them.
33554 * Signals on the newly created #GSettings object will be dispatched
33555 * via the thread-default #GMainContext in effect at the time of the
33556 * call to g_settings_new(). The new #GSettings will hold a reference
33557 * on the context. See g_main_context_push_thread_default().
33559 * Returns: a new #GSettings object
33565 * g_settings_new_full:
33566 * @schema: a #GSettingsSchema
33567 * @backend: (nullable): a #GSettingsBackend
33568 * @path: (nullable): the path to use
33570 * Creates a new #GSettings object with a given schema, backend and
33573 * It should be extremely rare that you ever want to use this function.
33574 * It is made available for advanced use-cases (such as plugin systems
33575 * that want to provide access to schemas loaded from custom locations,
33578 * At the most basic level, a #GSettings object is a pure composition of
33579 * 4 things: a #GSettingsSchema, a #GSettingsBackend, a path within that
33580 * backend, and a #GMainContext to which signals are dispatched.
33582 * This constructor therefore gives you full control over constructing
33583 * #GSettings instances. The first 3 parameters are given directly as
33584 * @schema, @backend and @path, and the main context is taken from the
33585 * thread-default (as per g_settings_new()).
33587 * If @backend is %NULL then the default backend is used.
33589 * If @path is %NULL then the path from the schema is used. It is an
33590 * error if @path is %NULL and the schema has no path of its own or if
33591 * @path is non-%NULL and not equal to the path that the schema does
33594 * Returns: a new #GSettings object
33600 * g_settings_new_with_backend:
33601 * @schema_id: the id of the schema
33602 * @backend: the #GSettingsBackend to use
33604 * Creates a new #GSettings object with the schema specified by
33605 * @schema_id and a given #GSettingsBackend.
33607 * Creating a #GSettings object with a different backend allows accessing
33608 * settings from a database other than the usual one. For example, it may make
33609 * sense to pass a backend corresponding to the "defaults" settings database on
33610 * the system to get a settings object that modifies the system default
33611 * settings instead of the settings for this user.
33613 * Returns: a new #GSettings object
33619 * g_settings_new_with_backend_and_path:
33620 * @schema_id: the id of the schema
33621 * @backend: the #GSettingsBackend to use
33622 * @path: the path to use
33624 * Creates a new #GSettings object with the schema specified by
33625 * @schema_id and a given #GSettingsBackend and path.
33627 * This is a mix of g_settings_new_with_backend() and
33628 * g_settings_new_with_path().
33630 * Returns: a new #GSettings object
33636 * g_settings_new_with_path:
33637 * @schema_id: the id of the schema
33638 * @path: the path to use
33640 * Creates a new #GSettings object with the relocatable schema specified
33641 * by @schema_id and a given path.
33643 * You only need to do this if you want to directly create a settings
33644 * object with a schema that doesn't have a specified path of its own.
33645 * That's quite rare.
33647 * It is a programmer error to call this function for a schema that
33648 * has an explicitly specified path.
33650 * It is a programmer error if @path is not a valid path. A valid path
33651 * begins and ends with '/' and does not contain two consecutive '/'
33654 * Returns: a new #GSettings object
33660 * g_settings_range_check:
33661 * @settings: a #GSettings
33662 * @key: the key to check
33663 * @value: the value to check
33665 * Checks if the given @value is of the correct type and within the
33666 * permitted range for @key.
33668 * Returns: %TRUE if @value is valid for @key
33670 * Deprecated: 2.40: Use g_settings_schema_key_range_check() instead.
33675 * g_settings_reset:
33676 * @settings: a #GSettings object
33677 * @key: the name of a key
33679 * Resets @key to its default value.
33681 * This call resets the key, as much as possible, to its default value.
33682 * That might be the value specified in the schema or the one set by the
33688 * g_settings_revert:
33689 * @settings: a #GSettings instance
33691 * Reverts all non-applied changes to the settings. This function
33692 * does nothing unless @settings is in 'delay-apply' mode; see
33693 * g_settings_delay(). In the normal case settings are always applied
33696 * Change notifications will be emitted for affected keys.
33701 * g_settings_schema_get_id:
33702 * @schema: a #GSettingsSchema
33704 * Get the ID of @schema.
33706 * Returns: (transfer none): the ID
33711 * g_settings_schema_get_key:
33712 * @schema: a #GSettingsSchema
33713 * @name: the name of a key
33715 * Gets the key named @name from @schema.
33717 * It is a programmer error to request a key that does not exist. See
33718 * g_settings_schema_list_keys().
33720 * Returns: (transfer full): the #GSettingsSchemaKey for @name
33726 * g_settings_schema_get_path:
33727 * @schema: a #GSettingsSchema
33729 * Gets the path associated with @schema, or %NULL.
33731 * Schemas may be single-instance or relocatable. Single-instance
33732 * schemas correspond to exactly one set of keys in the backend
33733 * database: those located at the path returned by this function.
33735 * Relocatable schemas can be referenced by other schemas and can
33736 * therefore describe multiple sets of keys at different locations. For
33737 * relocatable schemas, this function will return %NULL.
33739 * Returns: (nullable) (transfer none): the path of the schema, or %NULL
33745 * g_settings_schema_has_key:
33746 * @schema: a #GSettingsSchema
33747 * @name: the name of a key
33749 * Checks if @schema has a key named @name.
33751 * Returns: %TRUE if such a key exists
33757 * g_settings_schema_key_get_default_value:
33758 * @key: a #GSettingsSchemaKey
33760 * Gets the default value for @key.
33762 * Note that this is the default value according to the schema. System
33763 * administrator defaults and lockdown are not visible via this API.
33765 * Returns: (transfer full): the default value for the key
33771 * g_settings_schema_key_get_description:
33772 * @key: a #GSettingsSchemaKey
33774 * Gets the description for @key.
33776 * If no description has been provided in the schema for @key, returns
33779 * The description can be one sentence to several paragraphs in length.
33780 * Paragraphs are delimited with a double newline. Descriptions can be
33781 * translated and the value returned from this function is is the
33784 * This function is slow. The summary and description information for
33785 * the schemas is not stored in the compiled schema database so this
33786 * function has to parse all of the source XML files in the schema
33789 * Returns: (nullable): the description for @key, or %NULL
33795 * g_settings_schema_key_get_name:
33796 * @key: a #GSettingsSchemaKey
33798 * Gets the name of @key.
33800 * Returns: the name of @key.
33806 * g_settings_schema_key_get_range:
33807 * @key: a #GSettingsSchemaKey
33809 * Queries the range of a key.
33811 * This function will return a #GVariant that fully describes the range
33812 * of values that are valid for @key.
33814 * The type of #GVariant returned is `(sv)`. The string describes
33815 * the type of range restriction in effect. The type and meaning of
33816 * the value contained in the variant depends on the string.
33818 * If the string is `'type'` then the variant contains an empty array.
33819 * The element type of that empty array is the expected type of value
33820 * and all values of that type are valid.
33822 * If the string is `'enum'` then the variant contains an array
33823 * enumerating the possible values. Each item in the array is
33824 * a possible valid value and no other values are valid.
33826 * If the string is `'flags'` then the variant contains an array. Each
33827 * item in the array is a value that may appear zero or one times in an
33828 * array to be used as the value for this key. For example, if the
33829 * variant contained the array `['x', 'y']` then the valid values for
33830 * the key would be `[]`, `['x']`, `['y']`, `['x', 'y']` and
33833 * Finally, if the string is `'range'` then the variant contains a pair
33834 * of like-typed values -- the minimum and maximum permissible values
33837 * This information should not be used by normal programs. It is
33838 * considered to be a hint for introspection purposes. Normal programs
33839 * should already know what is permitted by their own schema. The
33840 * format may change in any way in the future -- but particularly, new
33841 * forms may be added to the possibilities described above.
33843 * You should free the returned value with g_variant_unref() when it is
33844 * no longer needed.
33846 * Returns: (transfer full): a #GVariant describing the range
33852 * g_settings_schema_key_get_summary:
33853 * @key: a #GSettingsSchemaKey
33855 * Gets the summary for @key.
33857 * If no summary has been provided in the schema for @key, returns
33860 * The summary is a short description of the purpose of the key; usually
33861 * one short sentence. Summaries can be translated and the value
33862 * returned from this function is is the current locale.
33864 * This function is slow. The summary and description information for
33865 * the schemas is not stored in the compiled schema database so this
33866 * function has to parse all of the source XML files in the schema
33869 * Returns: (nullable): the summary for @key, or %NULL
33875 * g_settings_schema_key_get_value_type:
33876 * @key: a #GSettingsSchemaKey
33878 * Gets the #GVariantType of @key.
33880 * Returns: (transfer none): the type of @key
33886 * g_settings_schema_key_range_check:
33887 * @key: a #GSettingsSchemaKey
33888 * @value: the value to check
33890 * Checks if the given @value is within the
33891 * permitted range for @key.
33893 * It is a programmer error if @value is not of the correct type — you
33894 * must check for this first.
33896 * Returns: %TRUE if @value is valid for @key
33902 * g_settings_schema_key_ref:
33903 * @key: a #GSettingsSchemaKey
33905 * Increase the reference count of @key, returning a new reference.
33907 * Returns: a new reference to @key
33913 * g_settings_schema_key_unref:
33914 * @key: a #GSettingsSchemaKey
33916 * Decrease the reference count of @key, possibly freeing it.
33923 * g_settings_schema_list_children:
33924 * @schema: a #GSettingsSchema
33926 * Gets the list of children in @schema.
33928 * You should free the return value with g_strfreev() when you are done
33931 * Returns: (transfer full) (element-type utf8): a list of the children on
33932 * @settings, in no defined order
33938 * g_settings_schema_list_keys:
33939 * @schema: a #GSettingsSchema
33941 * Introspects the list of keys on @schema.
33943 * You should probably not be calling this function from "normal" code
33944 * (since you should already know what keys are in your schema). This
33945 * function is intended for introspection reasons.
33947 * Returns: (transfer full) (element-type utf8): a list of the keys on
33948 * @schema, in no defined order
33954 * g_settings_schema_ref:
33955 * @schema: a #GSettingsSchema
33957 * Increase the reference count of @schema, returning a new reference.
33959 * Returns: a new reference to @schema
33965 * g_settings_schema_source_get_default:
33967 * Gets the default system schema source.
33969 * This function is not required for normal uses of #GSettings but it
33970 * may be useful to authors of plugin management systems or to those who
33971 * want to introspect the content of schemas.
33973 * If no schemas are installed, %NULL will be returned.
33975 * The returned source may actually consist of multiple schema sources
33976 * from different directories, depending on which directories were given
33977 * in `XDG_DATA_DIRS` and `GSETTINGS_SCHEMA_DIR`. For this reason, all
33978 * lookups performed against the default source should probably be done
33981 * Returns: (transfer none) (nullable): the default schema source
33987 * g_settings_schema_source_list_schemas:
33988 * @source: a #GSettingsSchemaSource
33989 * @recursive: if we should recurse
33990 * @non_relocatable: (out) (transfer full) (array zero-terminated=1): the
33991 * list of non-relocatable schemas, in no defined order
33992 * @relocatable: (out) (transfer full) (array zero-terminated=1): the list
33993 * of relocatable schemas, in no defined order
33995 * Lists the schemas in a given source.
33997 * If @recursive is %TRUE then include parent sources. If %FALSE then
33998 * only include the schemas from one source (ie: one directory). You
33999 * probably want %TRUE.
34001 * Non-relocatable schemas are those for which you can call
34002 * g_settings_new(). Relocatable schemas are those for which you must
34003 * use g_settings_new_with_path().
34005 * Do not call this function from normal programs. This is designed for
34006 * use by database editors, commandline tools, etc.
34013 * g_settings_schema_source_lookup:
34014 * @source: a #GSettingsSchemaSource
34015 * @schema_id: a schema ID
34016 * @recursive: %TRUE if the lookup should be recursive
34018 * Looks up a schema with the identifier @schema_id in @source.
34020 * This function is not required for normal uses of #GSettings but it
34021 * may be useful to authors of plugin management systems or to those who
34022 * want to introspect the content of schemas.
34024 * If the schema isn't found directly in @source and @recursive is %TRUE
34025 * then the parent sources will also be checked.
34027 * If the schema isn't found, %NULL is returned.
34029 * Returns: (nullable) (transfer full): a new #GSettingsSchema
34035 * g_settings_schema_source_new_from_directory:
34036 * @directory: (type filename): the filename of a directory
34037 * @parent: (nullable): a #GSettingsSchemaSource, or %NULL
34038 * @trusted: %TRUE, if the directory is trusted
34039 * @error: a pointer to a #GError pointer set to %NULL, or %NULL
34041 * Attempts to create a new schema source corresponding to the contents
34042 * of the given directory.
34044 * This function is not required for normal uses of #GSettings but it
34045 * may be useful to authors of plugin management systems.
34047 * The directory should contain a file called `gschemas.compiled` as
34048 * produced by the [glib-compile-schemas][glib-compile-schemas] tool.
34050 * If @trusted is %TRUE then `gschemas.compiled` is trusted not to be
34051 * corrupted. This assumption has a performance advantage, but can result
34052 * in crashes or inconsistent behaviour in the case of a corrupted file.
34053 * Generally, you should set @trusted to %TRUE for files installed by the
34054 * system and to %FALSE for files in the home directory.
34056 * In either case, an empty file or some types of corruption in the file will
34057 * result in %G_FILE_ERROR_INVAL being returned.
34059 * If @parent is non-%NULL then there are two effects.
34061 * First, if g_settings_schema_source_lookup() is called with the
34062 * @recursive flag set to %TRUE and the schema can not be found in the
34063 * source, the lookup will recurse to the parent.
34065 * Second, any references to other schemas specified within this
34066 * source (ie: `child` or `extends`) references may be resolved
34067 * from the @parent.
34069 * For this second reason, except in very unusual situations, the
34070 * @parent should probably be given as the default schema source, as
34071 * returned by g_settings_schema_source_get_default().
34078 * g_settings_schema_source_ref:
34079 * @source: a #GSettingsSchemaSource
34081 * Increase the reference count of @source, returning a new reference.
34083 * Returns: a new reference to @source
34089 * g_settings_schema_source_unref:
34090 * @source: a #GSettingsSchemaSource
34092 * Decrease the reference count of @source, possibly freeing it.
34099 * g_settings_schema_unref:
34100 * @schema: a #GSettingsSchema
34102 * Decrease the reference count of @schema, possibly freeing it.
34110 * @settings: a #GSettings object
34111 * @key: the name of the key to set
34112 * @format: a #GVariant format string
34113 * @...: arguments as per @format
34115 * Sets @key in @settings to @value.
34117 * A convenience function that combines g_settings_set_value() with
34120 * It is a programmer error to give a @key that isn't contained in the
34121 * schema for @settings or for the #GVariantType of @format to mismatch
34122 * the type given in the schema.
34124 * Returns: %TRUE if setting the key succeeded,
34125 * %FALSE if the key was not writable
34131 * g_settings_set_boolean:
34132 * @settings: a #GSettings object
34133 * @key: the name of the key to set
34134 * @value: the value to set it to
34136 * Sets @key in @settings to @value.
34138 * A convenience variant of g_settings_set() for booleans.
34140 * It is a programmer error to give a @key that isn't specified as
34141 * having a boolean type in the schema for @settings.
34143 * Returns: %TRUE if setting the key succeeded,
34144 * %FALSE if the key was not writable
34150 * g_settings_set_double:
34151 * @settings: a #GSettings object
34152 * @key: the name of the key to set
34153 * @value: the value to set it to
34155 * Sets @key in @settings to @value.
34157 * A convenience variant of g_settings_set() for doubles.
34159 * It is a programmer error to give a @key that isn't specified as
34160 * having a 'double' type in the schema for @settings.
34162 * Returns: %TRUE if setting the key succeeded,
34163 * %FALSE if the key was not writable
34169 * g_settings_set_enum:
34170 * @settings: a #GSettings object
34171 * @key: a key, within @settings
34172 * @value: an enumerated value
34174 * Looks up the enumerated type nick for @value and writes it to @key,
34175 * within @settings.
34177 * It is a programmer error to give a @key that isn't contained in the
34178 * schema for @settings or is not marked as an enumerated type, or for
34179 * @value not to be a valid value for the named type.
34181 * After performing the write, accessing @key directly with
34182 * g_settings_get_string() will return the 'nick' associated with
34185 * Returns: %TRUE, if the set succeeds
34190 * g_settings_set_flags:
34191 * @settings: a #GSettings object
34192 * @key: a key, within @settings
34193 * @value: a flags value
34195 * Looks up the flags type nicks for the bits specified by @value, puts
34196 * them in an array of strings and writes the array to @key, within
34199 * It is a programmer error to give a @key that isn't contained in the
34200 * schema for @settings or is not marked as a flags type, or for @value
34201 * to contain any bits that are not value for the named type.
34203 * After performing the write, accessing @key directly with
34204 * g_settings_get_strv() will return an array of 'nicks'; one for each
34207 * Returns: %TRUE, if the set succeeds
34212 * g_settings_set_int:
34213 * @settings: a #GSettings object
34214 * @key: the name of the key to set
34215 * @value: the value to set it to
34217 * Sets @key in @settings to @value.
34219 * A convenience variant of g_settings_set() for 32-bit integers.
34221 * It is a programmer error to give a @key that isn't specified as
34222 * having a int32 type in the schema for @settings.
34224 * Returns: %TRUE if setting the key succeeded,
34225 * %FALSE if the key was not writable
34231 * g_settings_set_int64:
34232 * @settings: a #GSettings object
34233 * @key: the name of the key to set
34234 * @value: the value to set it to
34236 * Sets @key in @settings to @value.
34238 * A convenience variant of g_settings_set() for 64-bit integers.
34240 * It is a programmer error to give a @key that isn't specified as
34241 * having a int64 type in the schema for @settings.
34243 * Returns: %TRUE if setting the key succeeded,
34244 * %FALSE if the key was not writable
34250 * g_settings_set_string:
34251 * @settings: a #GSettings object
34252 * @key: the name of the key to set
34253 * @value: the value to set it to
34255 * Sets @key in @settings to @value.
34257 * A convenience variant of g_settings_set() for strings.
34259 * It is a programmer error to give a @key that isn't specified as
34260 * having a string type in the schema for @settings.
34262 * Returns: %TRUE if setting the key succeeded,
34263 * %FALSE if the key was not writable
34269 * g_settings_set_strv:
34270 * @settings: a #GSettings object
34271 * @key: the name of the key to set
34272 * @value: (nullable) (array zero-terminated=1): the value to set it to, or %NULL
34274 * Sets @key in @settings to @value.
34276 * A convenience variant of g_settings_set() for string arrays. If
34277 * @value is %NULL, then @key is set to be the empty array.
34279 * It is a programmer error to give a @key that isn't specified as
34280 * having an array of strings type in the schema for @settings.
34282 * Returns: %TRUE if setting the key succeeded,
34283 * %FALSE if the key was not writable
34289 * g_settings_set_uint:
34290 * @settings: a #GSettings object
34291 * @key: the name of the key to set
34292 * @value: the value to set it to
34294 * Sets @key in @settings to @value.
34296 * A convenience variant of g_settings_set() for 32-bit unsigned
34299 * It is a programmer error to give a @key that isn't specified as
34300 * having a uint32 type in the schema for @settings.
34302 * Returns: %TRUE if setting the key succeeded,
34303 * %FALSE if the key was not writable
34309 * g_settings_set_uint64:
34310 * @settings: a #GSettings object
34311 * @key: the name of the key to set
34312 * @value: the value to set it to
34314 * Sets @key in @settings to @value.
34316 * A convenience variant of g_settings_set() for 64-bit unsigned
34319 * It is a programmer error to give a @key that isn't specified as
34320 * having a uint64 type in the schema for @settings.
34322 * Returns: %TRUE if setting the key succeeded,
34323 * %FALSE if the key was not writable
34329 * g_settings_set_value:
34330 * @settings: a #GSettings object
34331 * @key: the name of the key to set
34332 * @value: a #GVariant of the correct type
34334 * Sets @key in @settings to @value.
34336 * It is a programmer error to give a @key that isn't contained in the
34337 * schema for @settings or for @value to have the incorrect type, per
34340 * If @value is floating then this function consumes the reference.
34342 * Returns: %TRUE if setting the key succeeded,
34343 * %FALSE if the key was not writable
34351 * Ensures that all pending operations are complete for the default backend.
34353 * Writes made to a #GSettings are handled asynchronously. For this
34354 * reason, it is very unlikely that the changes have it to disk by the
34355 * time g_settings_set() returns.
34357 * This call will block until all of the writes have made it to the
34358 * backend. Since the mainloop is not running, no change notifications
34359 * will be dispatched during this call (but some may be queued by the
34360 * time the call is done).
34365 * g_settings_unbind:
34366 * @object: (type GObject.Object): the object
34367 * @property: the property whose binding is removed
34369 * Removes an existing binding for @property on @object.
34371 * Note that bindings are automatically removed when the
34372 * object is finalized, so it is rarely necessary to call this
34380 * g_simple_action_group_add_entries:
34381 * @simple: a #GSimpleActionGroup
34382 * @entries: (array length=n_entries): a pointer to the first item in
34383 * an array of #GActionEntry structs
34384 * @n_entries: the length of @entries, or -1
34385 * @user_data: the user data for signal connections
34387 * A convenience function for creating multiple #GSimpleAction instances
34388 * and adding them to the action group.
34391 * Deprecated: 2.38: Use g_action_map_add_action_entries()
34396 * g_simple_action_group_insert:
34397 * @simple: a #GSimpleActionGroup
34398 * @action: a #GAction
34400 * Adds an action to the action group.
34402 * If the action group already contains an action with the same name as
34403 * @action then the old action is dropped from the group.
34405 * The action group takes its own reference on @action.
34408 * Deprecated: 2.38: Use g_action_map_add_action()
34413 * g_simple_action_group_lookup:
34414 * @simple: a #GSimpleActionGroup
34415 * @action_name: the name of an action
34417 * Looks up the action with the name @action_name in the group.
34419 * If no such action exists, returns %NULL.
34421 * Returns: (transfer none): a #GAction, or %NULL
34423 * Deprecated: 2.38: Use g_action_map_lookup_action()
34428 * g_simple_action_group_new:
34430 * Creates a new, empty, #GSimpleActionGroup.
34432 * Returns: a new #GSimpleActionGroup
34438 * g_simple_action_group_remove:
34439 * @simple: a #GSimpleActionGroup
34440 * @action_name: the name of the action
34442 * Removes the named action from the action group.
34444 * If no action of this name is in the group then nothing happens.
34447 * Deprecated: 2.38: Use g_action_map_remove_action()
34452 * g_simple_action_new:
34453 * @name: the name of the action
34454 * @parameter_type: (nullable): the type of parameter that will be passed to
34455 * handlers for the #GSimpleAction::activate signal, or %NULL for no parameter
34457 * Creates a new action.
34459 * The created action is stateless. See g_simple_action_new_stateful() to create
34460 * an action that has state.
34462 * Returns: a new #GSimpleAction
34468 * g_simple_action_new_stateful:
34469 * @name: the name of the action
34470 * @parameter_type: (nullable): the type of the parameter that will be passed to
34471 * handlers for the #GSimpleAction::activate signal, or %NULL for no parameter
34472 * @state: the initial state of the action
34474 * Creates a new stateful action.
34476 * All future state values must have the same #GVariantType as the initial
34479 * If the @state #GVariant is floating, it is consumed.
34481 * Returns: a new #GSimpleAction
34487 * g_simple_action_set_enabled:
34488 * @simple: a #GSimpleAction
34489 * @enabled: whether the action is enabled
34491 * Sets the action as enabled or not.
34493 * An action must be enabled in order to be activated or in order to
34494 * have its state changed from outside callers.
34496 * This should only be called by the implementor of the action. Users
34497 * of the action should not attempt to modify its enabled flag.
34504 * g_simple_action_set_state:
34505 * @simple: a #GSimpleAction
34506 * @value: the new #GVariant for the state
34508 * Sets the state of the action.
34510 * This directly updates the 'state' property to the given value.
34512 * This should only be called by the implementor of the action. Users
34513 * of the action should not attempt to directly modify the 'state'
34514 * property. Instead, they should call g_action_change_state() to
34515 * request the change.
34517 * If the @value GVariant is floating, it is consumed.
34524 * g_simple_action_set_state_hint:
34525 * @simple: a #GSimpleAction
34526 * @state_hint: (nullable): a #GVariant representing the state hint
34528 * Sets the state hint for the action.
34530 * See g_action_get_state_hint() for more information about
34531 * action state hints.
34538 * g_simple_async_report_error_in_idle: (skip)
34539 * @object: (nullable): a #GObject, or %NULL.
34540 * @callback: a #GAsyncReadyCallback.
34541 * @user_data: user data passed to @callback.
34542 * @domain: a #GQuark containing the error domain (usually #G_IO_ERROR).
34543 * @code: a specific error code.
34544 * @format: a formatted error reporting string.
34545 * @...: a list of variables to fill in @format.
34547 * Reports an error in an asynchronous function in an idle function by
34548 * directly setting the contents of the #GAsyncResult with the given error
34551 * Deprecated: 2.46: Use g_task_report_error().
34556 * g_simple_async_report_gerror_in_idle:
34557 * @object: (nullable): a #GObject, or %NULL
34558 * @callback: (scope async): a #GAsyncReadyCallback.
34559 * @user_data: (closure): user data passed to @callback.
34560 * @error: the #GError to report
34562 * Reports an error in an idle function. Similar to
34563 * g_simple_async_report_error_in_idle(), but takes a #GError rather
34564 * than building a new one.
34566 * Deprecated: 2.46: Use g_task_report_error().
34571 * g_simple_async_report_take_gerror_in_idle: (skip)
34572 * @object: (nullable): a #GObject, or %NULL
34573 * @callback: a #GAsyncReadyCallback.
34574 * @user_data: user data passed to @callback.
34575 * @error: the #GError to report
34577 * Reports an error in an idle function. Similar to
34578 * g_simple_async_report_gerror_in_idle(), but takes over the caller's
34579 * ownership of @error, so the caller does not have to free it any more.
34582 * Deprecated: 2.46: Use g_task_report_error().
34587 * g_simple_async_result_complete:
34588 * @simple: a #GSimpleAsyncResult.
34590 * Completes an asynchronous I/O job immediately. Must be called in
34591 * the thread where the asynchronous result was to be delivered, as it
34592 * invokes the callback directly. If you are in a different thread use
34593 * g_simple_async_result_complete_in_idle().
34595 * Calling this function takes a reference to @simple for as long as
34596 * is needed to complete the call.
34598 * Deprecated: 2.46: Use #GTask instead.
34603 * g_simple_async_result_complete_in_idle:
34604 * @simple: a #GSimpleAsyncResult.
34606 * Completes an asynchronous function in an idle handler in the
34607 * [thread-default main context][g-main-context-push-thread-default]
34608 * of the thread that @simple was initially created in
34609 * (and re-pushes that context around the invocation of the callback).
34611 * Calling this function takes a reference to @simple for as long as
34612 * is needed to complete the call.
34614 * Deprecated: 2.46: Use #GTask instead.
34619 * g_simple_async_result_get_op_res_gboolean:
34620 * @simple: a #GSimpleAsyncResult.
34622 * Gets the operation result boolean from within the asynchronous result.
34624 * Returns: %TRUE if the operation's result was %TRUE, %FALSE
34625 * if the operation's result was %FALSE.
34626 * Deprecated: 2.46: Use #GTask and g_task_propagate_boolean() instead.
34631 * g_simple_async_result_get_op_res_gpointer: (skip)
34632 * @simple: a #GSimpleAsyncResult.
34634 * Gets a pointer result as returned by the asynchronous function.
34636 * Returns: a pointer from the result.
34637 * Deprecated: 2.46: Use #GTask and g_task_propagate_pointer() instead.
34642 * g_simple_async_result_get_op_res_gssize:
34643 * @simple: a #GSimpleAsyncResult.
34645 * Gets a gssize from the asynchronous result.
34647 * Returns: a gssize returned from the asynchronous function.
34648 * Deprecated: 2.46: Use #GTask and g_task_propagate_int() instead.
34653 * g_simple_async_result_get_source_tag: (skip)
34654 * @simple: a #GSimpleAsyncResult.
34656 * Gets the source tag for the #GSimpleAsyncResult.
34658 * Returns: a #gpointer to the source object for the #GSimpleAsyncResult.
34659 * Deprecated: 2.46.: Use #GTask and g_task_get_source_tag() instead.
34664 * g_simple_async_result_is_valid:
34665 * @result: the #GAsyncResult passed to the _finish function.
34666 * @source: (nullable): the #GObject passed to the _finish function.
34667 * @source_tag: (nullable): the asynchronous function.
34669 * Ensures that the data passed to the _finish function of an async
34670 * operation is consistent. Three checks are performed.
34672 * First, @result is checked to ensure that it is really a
34673 * #GSimpleAsyncResult. Second, @source is checked to ensure that it
34674 * matches the source object of @result. Third, @source_tag is
34675 * checked to ensure that it is equal to the @source_tag argument given
34676 * to g_simple_async_result_new() (which, by convention, is a pointer
34677 * to the _async function corresponding to the _finish function from
34678 * which this function is called). (Alternatively, if either
34679 * @source_tag or @result's source tag is %NULL, then the source tag
34680 * check is skipped.)
34682 * Returns: #TRUE if all checks passed or #FALSE if any failed.
34684 * Deprecated: 2.46: Use #GTask and g_task_is_valid() instead.
34689 * g_simple_async_result_new:
34690 * @source_object: (nullable): a #GObject, or %NULL.
34691 * @callback: (scope async): a #GAsyncReadyCallback.
34692 * @user_data: (closure): user data passed to @callback.
34693 * @source_tag: the asynchronous function.
34695 * Creates a #GSimpleAsyncResult.
34697 * The common convention is to create the #GSimpleAsyncResult in the
34698 * function that starts the asynchronous operation and use that same
34699 * function as the @source_tag.
34701 * If your operation supports cancellation with #GCancellable (which it
34702 * probably should) then you should provide the user's cancellable to
34703 * g_simple_async_result_set_check_cancellable() immediately after
34704 * this function returns.
34706 * Returns: a #GSimpleAsyncResult.
34707 * Deprecated: 2.46: Use g_task_new() instead.
34712 * g_simple_async_result_new_error:
34713 * @source_object: (nullable): a #GObject, or %NULL.
34714 * @callback: (scope async): a #GAsyncReadyCallback.
34715 * @user_data: (closure): user data passed to @callback.
34716 * @domain: a #GQuark.
34717 * @code: an error code.
34718 * @format: a string with format characters.
34719 * @...: a list of values to insert into @format.
34721 * Creates a new #GSimpleAsyncResult with a set error.
34723 * Returns: a #GSimpleAsyncResult.
34724 * Deprecated: 2.46: Use g_task_new() and g_task_return_new_error() instead.
34729 * g_simple_async_result_new_from_error:
34730 * @source_object: (nullable): a #GObject, or %NULL.
34731 * @callback: (scope async): a #GAsyncReadyCallback.
34732 * @user_data: (closure): user data passed to @callback.
34733 * @error: a #GError
34735 * Creates a #GSimpleAsyncResult from an error condition.
34737 * Returns: a #GSimpleAsyncResult.
34738 * Deprecated: 2.46: Use g_task_new() and g_task_return_error() instead.
34743 * g_simple_async_result_new_take_error: (skip)
34744 * @source_object: (nullable): a #GObject, or %NULL
34745 * @callback: (scope async): a #GAsyncReadyCallback
34746 * @user_data: (closure): user data passed to @callback
34747 * @error: a #GError
34749 * Creates a #GSimpleAsyncResult from an error condition, and takes over the
34750 * caller's ownership of @error, so the caller does not need to free it anymore.
34752 * Returns: a #GSimpleAsyncResult
34754 * Deprecated: 2.46: Use g_task_new() and g_task_return_error() instead.
34759 * g_simple_async_result_propagate_error:
34760 * @simple: a #GSimpleAsyncResult.
34761 * @dest: (out): a location to propagate the error to.
34763 * Propagates an error from within the simple asynchronous result to
34764 * a given destination.
34766 * If the #GCancellable given to a prior call to
34767 * g_simple_async_result_set_check_cancellable() is cancelled then this
34768 * function will return %TRUE with @dest set appropriately.
34770 * Returns: %TRUE if the error was propagated to @dest. %FALSE otherwise.
34771 * Deprecated: 2.46: Use #GTask instead.
34776 * g_simple_async_result_run_in_thread: (skip)
34777 * @simple: a #GSimpleAsyncResult.
34778 * @func: a #GSimpleAsyncThreadFunc.
34779 * @io_priority: the io priority of the request.
34780 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
34782 * Runs the asynchronous job in a separate thread and then calls
34783 * g_simple_async_result_complete_in_idle() on @simple to return
34784 * the result to the appropriate main loop.
34786 * Calling this function takes a reference to @simple for as long as
34787 * is needed to run the job and report its completion.
34789 * Deprecated: 2.46: Use #GTask and g_task_run_in_thread() instead.
34794 * g_simple_async_result_set_check_cancellable:
34795 * @simple: a #GSimpleAsyncResult
34796 * @check_cancellable: (nullable): a #GCancellable to check, or %NULL to unset
34798 * Sets a #GCancellable to check before dispatching results.
34800 * This function has one very specific purpose: the provided cancellable
34801 * is checked at the time of g_simple_async_result_propagate_error() If
34802 * it is cancelled, these functions will return an "Operation was
34803 * cancelled" error (%G_IO_ERROR_CANCELLED).
34805 * Implementors of cancellable asynchronous functions should use this in
34806 * order to provide a guarantee to their callers that cancelling an
34807 * async operation will reliably result in an error being returned for
34808 * that operation (even if a positive result for the operation has
34809 * already been sent as an idle to the main context to be dispatched).
34811 * The checking described above is done regardless of any call to the
34812 * unrelated g_simple_async_result_set_handle_cancellation() function.
34815 * Deprecated: 2.46: Use #GTask instead.
34820 * g_simple_async_result_set_error: (skip)
34821 * @simple: a #GSimpleAsyncResult.
34822 * @domain: a #GQuark (usually #G_IO_ERROR).
34823 * @code: an error code.
34824 * @format: a formatted error reporting string.
34825 * @...: a list of variables to fill in @format.
34827 * Sets an error within the asynchronous result without a #GError.
34829 * Deprecated: 2.46: Use #GTask and g_task_return_new_error() instead.
34834 * g_simple_async_result_set_error_va: (skip)
34835 * @simple: a #GSimpleAsyncResult.
34836 * @domain: a #GQuark (usually #G_IO_ERROR).
34837 * @code: an error code.
34838 * @format: a formatted error reporting string.
34839 * @args: va_list of arguments.
34841 * Sets an error within the asynchronous result without a #GError.
34842 * Unless writing a binding, see g_simple_async_result_set_error().
34844 * Deprecated: 2.46: Use #GTask and g_task_return_error() instead.
34849 * g_simple_async_result_set_from_error:
34850 * @simple: a #GSimpleAsyncResult.
34853 * Sets the result from a #GError.
34855 * Deprecated: 2.46: Use #GTask and g_task_return_error() instead.
34860 * g_simple_async_result_set_handle_cancellation:
34861 * @simple: a #GSimpleAsyncResult.
34862 * @handle_cancellation: a #gboolean.
34864 * Sets whether to handle cancellation within the asynchronous operation.
34866 * This function has nothing to do with
34867 * g_simple_async_result_set_check_cancellable(). It only refers to the
34868 * #GCancellable passed to g_simple_async_result_run_in_thread().
34875 * g_simple_async_result_set_op_res_gboolean:
34876 * @simple: a #GSimpleAsyncResult.
34877 * @op_res: a #gboolean.
34879 * Sets the operation result to a boolean within the asynchronous result.
34881 * Deprecated: 2.46: Use #GTask and g_task_return_boolean() instead.
34886 * g_simple_async_result_set_op_res_gpointer: (skip)
34887 * @simple: a #GSimpleAsyncResult.
34888 * @op_res: a pointer result from an asynchronous function.
34889 * @destroy_op_res: a #GDestroyNotify function.
34891 * Sets the operation result within the asynchronous result to a pointer.
34893 * Deprecated: 2.46: Use #GTask and g_task_return_pointer() instead.
34898 * g_simple_async_result_set_op_res_gssize:
34899 * @simple: a #GSimpleAsyncResult.
34900 * @op_res: a #gssize.
34902 * Sets the operation result within the asynchronous result to
34903 * the given @op_res.
34905 * Deprecated: 2.46: Use #GTask and g_task_return_int() instead.
34910 * g_simple_async_result_take_error: (skip)
34911 * @simple: a #GSimpleAsyncResult
34912 * @error: a #GError
34914 * Sets the result from @error, and takes over the caller's ownership
34915 * of @error, so the caller does not need to free it any more.
34918 * Deprecated: 2.46: Use #GTask and g_task_return_error() instead.
34923 * g_simple_io_stream_new:
34924 * @input_stream: a #GInputStream.
34925 * @output_stream: a #GOutputStream.
34927 * Creates a new #GSimpleIOStream wrapping @input_stream and @output_stream.
34928 * See also #GIOStream.
34930 * Returns: a new #GSimpleIOStream instance.
34936 * g_simple_permission_new:
34937 * @allowed: %TRUE if the action is allowed
34939 * Creates a new #GPermission instance that represents an action that is
34940 * either always or never allowed.
34942 * Returns: the #GSimplePermission, as a #GPermission
34948 * g_simple_proxy_resolver_new:
34949 * @default_proxy: (nullable): the default proxy to use, eg
34950 * "socks://192.168.1.1"
34951 * @ignore_hosts: (nullable): an optional list of hosts/IP addresses
34952 * to not use a proxy for.
34954 * Creates a new #GSimpleProxyResolver. See
34955 * #GSimpleProxyResolver:default-proxy and
34956 * #GSimpleProxyResolver:ignore-hosts for more details on how the
34957 * arguments are interpreted.
34959 * Returns: (transfer full): a new #GSimpleProxyResolver
34965 * g_simple_proxy_resolver_set_default_proxy:
34966 * @resolver: a #GSimpleProxyResolver
34967 * @default_proxy: the default proxy to use
34969 * Sets the default proxy on @resolver, to be used for any URIs that
34970 * don't match #GSimpleProxyResolver:ignore-hosts or a proxy set
34971 * via g_simple_proxy_resolver_set_uri_proxy().
34973 * If @default_proxy starts with "socks://",
34974 * #GSimpleProxyResolver will treat it as referring to all three of
34975 * the socks5, socks4a, and socks4 proxy types.
34982 * g_simple_proxy_resolver_set_ignore_hosts:
34983 * @resolver: a #GSimpleProxyResolver
34984 * @ignore_hosts: %NULL-terminated list of hosts/IP addresses
34985 * to not use a proxy for
34987 * Sets the list of ignored hosts.
34989 * See #GSimpleProxyResolver:ignore-hosts for more details on how the
34990 * @ignore_hosts argument is interpreted.
34997 * g_simple_proxy_resolver_set_uri_proxy:
34998 * @resolver: a #GSimpleProxyResolver
34999 * @uri_scheme: the URI scheme to add a proxy for
35000 * @proxy: the proxy to use for @uri_scheme
35002 * Adds a URI-scheme-specific proxy to @resolver; URIs whose scheme
35003 * matches @uri_scheme (and which don't match
35004 * #GSimpleProxyResolver:ignore-hosts) will be proxied via @proxy.
35006 * As with #GSimpleProxyResolver:default-proxy, if @proxy starts with
35007 * "socks://", #GSimpleProxyResolver will treat it
35008 * as referring to all three of the socks5, socks4a, and socks4 proxy
35017 * @socket: a #GSocket.
35018 * @cancellable: (nullable): a %GCancellable or %NULL
35019 * @error: #GError for error reporting, or %NULL to ignore.
35021 * Accept incoming connections on a connection-based socket. This removes
35022 * the first outstanding connection request from the listening socket and
35023 * creates a #GSocket object for it.
35025 * The @socket must be bound to a local address with g_socket_bind() and
35026 * must be listening for incoming connections (g_socket_listen()).
35028 * If there are no outstanding connections then the operation will block
35029 * or return %G_IO_ERROR_WOULD_BLOCK if non-blocking I/O is enabled.
35030 * To be notified of an incoming connection, wait for the %G_IO_IN condition.
35032 * Returns: (transfer full): a new #GSocket, or %NULL on error.
35033 * Free the returned object with g_object_unref().
35039 * g_socket_address_enumerator_next:
35040 * @enumerator: a #GSocketAddressEnumerator
35041 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
35042 * @error: a #GError.
35044 * Retrieves the next #GSocketAddress from @enumerator. Note that this
35045 * may block for some amount of time. (Eg, a #GNetworkAddress may need
35046 * to do a DNS lookup before it can return an address.) Use
35047 * g_socket_address_enumerator_next_async() if you need to avoid
35050 * If @enumerator is expected to yield addresses, but for some reason
35051 * is unable to (eg, because of a DNS error), then the first call to
35052 * g_socket_address_enumerator_next() will return an appropriate error
35053 * in *@error. However, if the first call to
35054 * g_socket_address_enumerator_next() succeeds, then any further
35055 * internal errors (other than @cancellable being triggered) will be
35058 * Returns: (transfer full): a #GSocketAddress (owned by the caller), or %NULL on
35059 * error (in which case *@error will be set) or if there are no
35065 * g_socket_address_enumerator_next_async:
35066 * @enumerator: a #GSocketAddressEnumerator
35067 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
35068 * @callback: (scope async): a #GAsyncReadyCallback to call when the request
35070 * @user_data: (closure): the data to pass to callback function
35072 * Asynchronously retrieves the next #GSocketAddress from @enumerator
35073 * and then calls @callback, which must call
35074 * g_socket_address_enumerator_next_finish() to get the result.
35076 * It is an error to call this multiple times before the previous callback has finished.
35081 * g_socket_address_enumerator_next_finish:
35082 * @enumerator: a #GSocketAddressEnumerator
35083 * @result: a #GAsyncResult
35084 * @error: a #GError
35086 * Retrieves the result of a completed call to
35087 * g_socket_address_enumerator_next_async(). See
35088 * g_socket_address_enumerator_next() for more information about
35091 * Returns: (transfer full): a #GSocketAddress (owned by the caller), or %NULL on
35092 * error (in which case *@error will be set) or if there are no
35098 * g_socket_address_get_family:
35099 * @address: a #GSocketAddress
35101 * Gets the socket family type of @address.
35103 * Returns: the socket family type of @address
35109 * g_socket_address_get_native_size:
35110 * @address: a #GSocketAddress
35112 * Gets the size of @address's native struct sockaddr.
35113 * You can use this to allocate memory to pass to
35114 * g_socket_address_to_native().
35116 * Returns: the size of the native struct sockaddr that
35117 * @address represents
35123 * g_socket_address_new_from_native:
35124 * @native: (not nullable): a pointer to a struct sockaddr
35125 * @len: the size of the memory location pointed to by @native
35127 * Creates a #GSocketAddress subclass corresponding to the native
35128 * struct sockaddr @native.
35130 * Returns: a new #GSocketAddress if @native could successfully
35131 * be converted, otherwise %NULL
35137 * g_socket_address_to_native:
35138 * @address: a #GSocketAddress
35139 * @dest: a pointer to a memory location that will contain the native
35141 * @destlen: the size of @dest. Must be at least as large as
35142 * g_socket_address_get_native_size()
35143 * @error: #GError for error reporting, or %NULL to ignore
35145 * Converts a #GSocketAddress to a native struct sockaddr, which can
35146 * be passed to low-level functions like connect() or bind().
35148 * If not enough space is available, a %G_IO_ERROR_NO_SPACE error
35149 * is returned. If the address type is not known on the system
35150 * then a %G_IO_ERROR_NOT_SUPPORTED error is returned.
35152 * Returns: %TRUE if @dest was filled in, %FALSE on error
35159 * @socket: a #GSocket.
35160 * @address: a #GSocketAddress specifying the local address.
35161 * @allow_reuse: whether to allow reusing this address
35162 * @error: #GError for error reporting, or %NULL to ignore.
35164 * When a socket is created it is attached to an address family, but it
35165 * doesn't have an address in this family. g_socket_bind() assigns the
35166 * address (sometimes called name) of the socket.
35168 * It is generally required to bind to a local address before you can
35169 * receive connections. (See g_socket_listen() and g_socket_accept() ).
35170 * In certain situations, you may also want to bind a socket that will be
35171 * used to initiate connections, though this is not normally required.
35173 * If @socket is a TCP socket, then @allow_reuse controls the setting
35174 * of the `SO_REUSEADDR` socket option; normally it should be %TRUE for
35175 * server sockets (sockets that you will eventually call
35176 * g_socket_accept() on), and %FALSE for client sockets. (Failing to
35177 * set this flag on a server socket may cause g_socket_bind() to return
35178 * %G_IO_ERROR_ADDRESS_IN_USE if the server program is stopped and then
35179 * immediately restarted.)
35181 * If @socket is a UDP socket, then @allow_reuse determines whether or
35182 * not other UDP sockets can be bound to the same address at the same
35183 * time. In particular, you can have several UDP sockets bound to the
35184 * same address, and they will all receive all of the multicast and
35185 * broadcast packets sent to that address. (The behavior of unicast
35186 * UDP packets to an address with multiple listeners is not defined.)
35188 * Returns: %TRUE on success, %FALSE on error.
35194 * g_socket_check_connect_result:
35195 * @socket: a #GSocket
35196 * @error: #GError for error reporting, or %NULL to ignore.
35198 * Checks and resets the pending connect error for the socket.
35199 * This is used to check for errors when g_socket_connect() is
35200 * used in non-blocking mode.
35202 * Returns: %TRUE if no error, %FALSE otherwise, setting @error to the error
35208 * g_socket_client_add_application_proxy:
35209 * @client: a #GSocketClient
35210 * @protocol: The proxy protocol
35212 * Enable proxy protocols to be handled by the application. When the
35213 * indicated proxy protocol is returned by the #GProxyResolver,
35214 * #GSocketClient will consider this protocol as supported but will
35215 * not try to find a #GProxy instance to handle handshaking. The
35216 * application must check for this case by calling
35217 * g_socket_connection_get_remote_address() on the returned
35218 * #GSocketConnection, and seeing if it's a #GProxyAddress of the
35219 * appropriate type, to determine whether or not it needs to handle
35220 * the proxy handshaking itself.
35222 * This should be used for proxy protocols that are dialects of
35223 * another protocol such as HTTP proxy. It also allows cohabitation of
35224 * proxy protocols that are reused between protocols. A good example
35225 * is HTTP. It can be used to proxy HTTP, FTP and Gopher and can also
35226 * be use as generic socket proxy through the HTTP CONNECT method.
35228 * When the proxy is detected as being an application proxy, TLS handshake
35229 * will be skipped. This is required to let the application do the proxy
35230 * specific handshake.
35235 * g_socket_client_connect:
35236 * @client: a #GSocketClient.
35237 * @connectable: a #GSocketConnectable specifying the remote address.
35238 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
35239 * @error: #GError for error reporting, or %NULL to ignore.
35241 * Tries to resolve the @connectable and make a network connection to it.
35243 * Upon a successful connection, a new #GSocketConnection is constructed
35244 * and returned. The caller owns this new object and must drop their
35245 * reference to it when finished with it.
35247 * The type of the #GSocketConnection object returned depends on the type of
35248 * the underlying socket that is used. For instance, for a TCP/IP connection
35249 * it will be a #GTcpConnection.
35251 * The socket created will be the same family as the address that the
35252 * @connectable resolves to, unless family is set with g_socket_client_set_family()
35253 * or indirectly via g_socket_client_set_local_address(). The socket type
35254 * defaults to %G_SOCKET_TYPE_STREAM but can be set with
35255 * g_socket_client_set_socket_type().
35257 * If a local address is specified with g_socket_client_set_local_address() the
35258 * socket will be bound to this address before connecting.
35260 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
35266 * g_socket_client_connect_async:
35267 * @client: a #GSocketClient
35268 * @connectable: a #GSocketConnectable specifying the remote address.
35269 * @cancellable: (nullable): a #GCancellable, or %NULL
35270 * @callback: (scope async): a #GAsyncReadyCallback
35271 * @user_data: (closure): user data for the callback
35273 * This is the asynchronous version of g_socket_client_connect().
35275 * You may wish to prefer the asynchronous version even in synchronous
35276 * command line programs because, since 2.60, it implements
35277 * [RFC 8305](https://tools.ietf.org/html/rfc8305) "Happy Eyeballs"
35278 * recommendations to work around long connection timeouts in networks
35279 * where IPv6 is broken by performing an IPv4 connection simultaneously
35280 * without waiting for IPv6 to time out, which is not supported by the
35281 * synchronous call. (This is not an API guarantee, and may change in
35284 * When the operation is finished @callback will be
35285 * called. You can then call g_socket_client_connect_finish() to get
35286 * the result of the operation.
35293 * g_socket_client_connect_finish:
35294 * @client: a #GSocketClient.
35295 * @result: a #GAsyncResult.
35296 * @error: a #GError location to store the error occurring, or %NULL to
35299 * Finishes an async connect operation. See g_socket_client_connect_async()
35301 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
35307 * g_socket_client_connect_to_host:
35308 * @client: a #GSocketClient
35309 * @host_and_port: the name and optionally port of the host to connect to
35310 * @default_port: the default port to connect to
35311 * @cancellable: (nullable): a #GCancellable, or %NULL
35312 * @error: a pointer to a #GError, or %NULL
35314 * This is a helper function for g_socket_client_connect().
35316 * Attempts to create a TCP connection to the named host.
35318 * @host_and_port may be in any of a number of recognized formats; an IPv6
35319 * address, an IPv4 address, or a domain name (in which case a DNS
35320 * lookup is performed). Quoting with [] is supported for all address
35321 * types. A port override may be specified in the usual way with a
35322 * colon. Ports may be given as decimal numbers or symbolic names (in
35323 * which case an /etc/services lookup is performed).
35325 * If no port override is given in @host_and_port then @default_port will be
35326 * used as the port number to connect to.
35328 * In general, @host_and_port is expected to be provided by the user (allowing
35329 * them to give the hostname, and a port override if necessary) and
35330 * @default_port is expected to be provided by the application.
35332 * In the case that an IP address is given, a single connection
35333 * attempt is made. In the case that a name is given, multiple
35334 * connection attempts may be made, in turn and according to the
35335 * number of address records in DNS, until a connection succeeds.
35337 * Upon a successful connection, a new #GSocketConnection is constructed
35338 * and returned. The caller owns this new object and must drop their
35339 * reference to it when finished with it.
35341 * In the event of any failure (DNS error, service not found, no hosts
35342 * connectable) %NULL is returned and @error (if non-%NULL) is set
35345 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
35351 * g_socket_client_connect_to_host_async:
35352 * @client: a #GSocketClient
35353 * @host_and_port: the name and optionally the port of the host to connect to
35354 * @default_port: the default port to connect to
35355 * @cancellable: (nullable): a #GCancellable, or %NULL
35356 * @callback: (scope async): a #GAsyncReadyCallback
35357 * @user_data: (closure): user data for the callback
35359 * This is the asynchronous version of g_socket_client_connect_to_host().
35361 * When the operation is finished @callback will be
35362 * called. You can then call g_socket_client_connect_to_host_finish() to get
35363 * the result of the operation.
35370 * g_socket_client_connect_to_host_finish:
35371 * @client: a #GSocketClient.
35372 * @result: a #GAsyncResult.
35373 * @error: a #GError location to store the error occurring, or %NULL to
35376 * Finishes an async connect operation. See g_socket_client_connect_to_host_async()
35378 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
35384 * g_socket_client_connect_to_service:
35385 * @client: a #GSocketConnection
35386 * @domain: a domain name
35387 * @service: the name of the service to connect to
35388 * @cancellable: (nullable): a #GCancellable, or %NULL
35389 * @error: a pointer to a #GError, or %NULL
35391 * Attempts to create a TCP connection to a service.
35393 * This call looks up the SRV record for @service at @domain for the
35394 * "tcp" protocol. It then attempts to connect, in turn, to each of
35395 * the hosts providing the service until either a connection succeeds
35396 * or there are no hosts remaining.
35398 * Upon a successful connection, a new #GSocketConnection is constructed
35399 * and returned. The caller owns this new object and must drop their
35400 * reference to it when finished with it.
35402 * In the event of any failure (DNS error, service not found, no hosts
35403 * connectable) %NULL is returned and @error (if non-%NULL) is set
35406 * Returns: (transfer full): a #GSocketConnection if successful, or %NULL on error
35411 * g_socket_client_connect_to_service_async:
35412 * @client: a #GSocketClient
35413 * @domain: a domain name
35414 * @service: the name of the service to connect to
35415 * @cancellable: (nullable): a #GCancellable, or %NULL
35416 * @callback: (scope async): a #GAsyncReadyCallback
35417 * @user_data: (closure): user data for the callback
35419 * This is the asynchronous version of
35420 * g_socket_client_connect_to_service().
35427 * g_socket_client_connect_to_service_finish:
35428 * @client: a #GSocketClient.
35429 * @result: a #GAsyncResult.
35430 * @error: a #GError location to store the error occurring, or %NULL to
35433 * Finishes an async connect operation. See g_socket_client_connect_to_service_async()
35435 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
35441 * g_socket_client_connect_to_uri:
35442 * @client: a #GSocketClient
35443 * @uri: A network URI
35444 * @default_port: the default port to connect to
35445 * @cancellable: (nullable): a #GCancellable, or %NULL
35446 * @error: a pointer to a #GError, or %NULL
35448 * This is a helper function for g_socket_client_connect().
35450 * Attempts to create a TCP connection with a network URI.
35452 * @uri may be any valid URI containing an "authority" (hostname/port)
35453 * component. If a port is not specified in the URI, @default_port
35454 * will be used. TLS will be negotiated if #GSocketClient:tls is %TRUE.
35455 * (#GSocketClient does not know to automatically assume TLS for
35456 * certain URI schemes.)
35458 * Using this rather than g_socket_client_connect() or
35459 * g_socket_client_connect_to_host() allows #GSocketClient to
35460 * determine when to use application-specific proxy protocols.
35462 * Upon a successful connection, a new #GSocketConnection is constructed
35463 * and returned. The caller owns this new object and must drop their
35464 * reference to it when finished with it.
35466 * In the event of any failure (DNS error, service not found, no hosts
35467 * connectable) %NULL is returned and @error (if non-%NULL) is set
35470 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
35476 * g_socket_client_connect_to_uri_async:
35477 * @client: a #GSocketClient
35478 * @uri: a network uri
35479 * @default_port: the default port to connect to
35480 * @cancellable: (nullable): a #GCancellable, or %NULL
35481 * @callback: (scope async): a #GAsyncReadyCallback
35482 * @user_data: (closure): user data for the callback
35484 * This is the asynchronous version of g_socket_client_connect_to_uri().
35486 * When the operation is finished @callback will be
35487 * called. You can then call g_socket_client_connect_to_uri_finish() to get
35488 * the result of the operation.
35495 * g_socket_client_connect_to_uri_finish:
35496 * @client: a #GSocketClient.
35497 * @result: a #GAsyncResult.
35498 * @error: a #GError location to store the error occurring, or %NULL to
35501 * Finishes an async connect operation. See g_socket_client_connect_to_uri_async()
35503 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
35509 * g_socket_client_get_enable_proxy:
35510 * @client: a #GSocketClient.
35512 * Gets the proxy enable state; see g_socket_client_set_enable_proxy()
35514 * Returns: whether proxying is enabled
35520 * g_socket_client_get_family:
35521 * @client: a #GSocketClient.
35523 * Gets the socket family of the socket client.
35525 * See g_socket_client_set_family() for details.
35527 * Returns: a #GSocketFamily
35533 * g_socket_client_get_local_address:
35534 * @client: a #GSocketClient.
35536 * Gets the local address of the socket client.
35538 * See g_socket_client_set_local_address() for details.
35540 * Returns: (nullable) (transfer none): a #GSocketAddress or %NULL. Do not free.
35546 * g_socket_client_get_protocol:
35547 * @client: a #GSocketClient
35549 * Gets the protocol name type of the socket client.
35551 * See g_socket_client_set_protocol() for details.
35553 * Returns: a #GSocketProtocol
35559 * g_socket_client_get_proxy_resolver:
35560 * @client: a #GSocketClient.
35562 * Gets the #GProxyResolver being used by @client. Normally, this will
35563 * be the resolver returned by g_proxy_resolver_get_default(), but you
35564 * can override it with g_socket_client_set_proxy_resolver().
35566 * Returns: (transfer none): The #GProxyResolver being used by
35573 * g_socket_client_get_socket_type:
35574 * @client: a #GSocketClient.
35576 * Gets the socket type of the socket client.
35578 * See g_socket_client_set_socket_type() for details.
35580 * Returns: a #GSocketFamily
35586 * g_socket_client_get_timeout:
35587 * @client: a #GSocketClient
35589 * Gets the I/O timeout time for sockets created by @client.
35591 * See g_socket_client_set_timeout() for details.
35593 * Returns: the timeout in seconds
35599 * g_socket_client_get_tls:
35600 * @client: a #GSocketClient.
35602 * Gets whether @client creates TLS connections. See
35603 * g_socket_client_set_tls() for details.
35605 * Returns: whether @client uses TLS
35611 * g_socket_client_get_tls_validation_flags:
35612 * @client: a #GSocketClient.
35614 * Gets the TLS validation flags used creating TLS connections via
35617 * Returns: the TLS validation flags
35623 * g_socket_client_new:
35625 * Creates a new #GSocketClient with the default options.
35627 * Returns: a #GSocketClient.
35628 * Free the returned object with g_object_unref().
35634 * g_socket_client_set_enable_proxy:
35635 * @client: a #GSocketClient.
35636 * @enable: whether to enable proxies
35638 * Sets whether or not @client attempts to make connections via a
35639 * proxy server. When enabled (the default), #GSocketClient will use a
35640 * #GProxyResolver to determine if a proxy protocol such as SOCKS is
35641 * needed, and automatically do the necessary proxy negotiation.
35643 * See also g_socket_client_set_proxy_resolver().
35650 * g_socket_client_set_family:
35651 * @client: a #GSocketClient.
35652 * @family: a #GSocketFamily
35654 * Sets the socket family of the socket client.
35655 * If this is set to something other than %G_SOCKET_FAMILY_INVALID
35656 * then the sockets created by this object will be of the specified
35659 * This might be useful for instance if you want to force the local
35660 * connection to be an ipv4 socket, even though the address might
35661 * be an ipv6 mapped to ipv4 address.
35668 * g_socket_client_set_local_address:
35669 * @client: a #GSocketClient.
35670 * @address: (nullable): a #GSocketAddress, or %NULL
35672 * Sets the local address of the socket client.
35673 * The sockets created by this object will bound to the
35674 * specified address (if not %NULL) before connecting.
35676 * This is useful if you want to ensure that the local
35677 * side of the connection is on a specific port, or on
35678 * a specific interface.
35685 * g_socket_client_set_protocol:
35686 * @client: a #GSocketClient.
35687 * @protocol: a #GSocketProtocol
35689 * Sets the protocol of the socket client.
35690 * The sockets created by this object will use of the specified
35693 * If @protocol is %G_SOCKET_PROTOCOL_DEFAULT that means to use the default
35694 * protocol for the socket family and type.
35701 * g_socket_client_set_proxy_resolver:
35702 * @client: a #GSocketClient.
35703 * @proxy_resolver: (nullable): a #GProxyResolver, or %NULL for the
35706 * Overrides the #GProxyResolver used by @client. You can call this if
35707 * you want to use specific proxies, rather than using the system
35708 * default proxy settings.
35710 * Note that whether or not the proxy resolver is actually used
35711 * depends on the setting of #GSocketClient:enable-proxy, which is not
35712 * changed by this function (but which is %TRUE by default)
35719 * g_socket_client_set_socket_type:
35720 * @client: a #GSocketClient.
35721 * @type: a #GSocketType
35723 * Sets the socket type of the socket client.
35724 * The sockets created by this object will be of the specified
35727 * It doesn't make sense to specify a type of %G_SOCKET_TYPE_DATAGRAM,
35728 * as GSocketClient is used for connection oriented services.
35735 * g_socket_client_set_timeout:
35736 * @client: a #GSocketClient.
35737 * @timeout: the timeout
35739 * Sets the I/O timeout for sockets created by @client. @timeout is a
35740 * time in seconds, or 0 for no timeout (the default).
35742 * The timeout value affects the initial connection attempt as well,
35743 * so setting this may cause calls to g_socket_client_connect(), etc,
35744 * to fail with %G_IO_ERROR_TIMED_OUT.
35751 * g_socket_client_set_tls:
35752 * @client: a #GSocketClient.
35753 * @tls: whether to use TLS
35755 * Sets whether @client creates TLS (aka SSL) connections. If @tls is
35756 * %TRUE, @client will wrap its connections in a #GTlsClientConnection
35757 * and perform a TLS handshake when connecting.
35759 * Note that since #GSocketClient must return a #GSocketConnection,
35760 * but #GTlsClientConnection is not a #GSocketConnection, this
35761 * actually wraps the resulting #GTlsClientConnection in a
35762 * #GTcpWrapperConnection when returning it. You can use
35763 * g_tcp_wrapper_connection_get_base_io_stream() on the return value
35764 * to extract the #GTlsClientConnection.
35766 * If you need to modify the behavior of the TLS handshake (eg, by
35767 * setting a client-side certificate to use, or connecting to the
35768 * #GTlsConnection::accept-certificate signal), you can connect to
35769 * @client's #GSocketClient::event signal and wait for it to be
35770 * emitted with %G_SOCKET_CLIENT_TLS_HANDSHAKING, which will give you
35771 * a chance to see the #GTlsClientConnection before the handshake
35779 * g_socket_client_set_tls_validation_flags:
35780 * @client: a #GSocketClient.
35781 * @flags: the validation flags
35783 * Sets the TLS validation flags used when creating TLS connections
35784 * via @client. The default value is %G_TLS_CERTIFICATE_VALIDATE_ALL.
35792 * @socket: a #GSocket
35793 * @error: #GError for error reporting, or %NULL to ignore.
35795 * Closes the socket, shutting down any active connection.
35797 * Closing a socket does not wait for all outstanding I/O operations
35798 * to finish, so the caller should not rely on them to be guaranteed
35799 * to complete even if the close returns with no error.
35801 * Once the socket is closed, all other operations will return
35802 * %G_IO_ERROR_CLOSED. Closing a socket multiple times will not
35805 * Sockets will be automatically closed when the last reference
35806 * is dropped, but you might want to call this function to make sure
35807 * resources are released as early as possible.
35809 * Beware that due to the way that TCP works, it is possible for
35810 * recently-sent data to be lost if either you close a socket while the
35811 * %G_IO_IN condition is set, or else if the remote connection tries to
35812 * send something to you after you close the socket but before it has
35813 * finished reading all of the data you sent. There is no easy generic
35814 * way to avoid this problem; the easiest fix is to design the network
35815 * protocol such that the client will never send data "out of turn".
35816 * Another solution is for the server to half-close the connection by
35817 * calling g_socket_shutdown() with only the @shutdown_write flag set,
35818 * and then wait for the client to notice this and close its side of the
35819 * connection, after which the server can safely call g_socket_close().
35820 * (This is what #GTcpConnection does if you call
35821 * g_tcp_connection_set_graceful_disconnect(). But of course, this
35822 * only works if the client will close its connection after the server
35825 * Returns: %TRUE on success, %FALSE on error
35831 * g_socket_condition_check:
35832 * @socket: a #GSocket
35833 * @condition: a #GIOCondition mask to check
35835 * Checks on the readiness of @socket to perform operations.
35836 * The operations specified in @condition are checked for and masked
35837 * against the currently-satisfied conditions on @socket. The result
35840 * Note that on Windows, it is possible for an operation to return
35841 * %G_IO_ERROR_WOULD_BLOCK even immediately after
35842 * g_socket_condition_check() has claimed that the socket is ready for
35843 * writing. Rather than calling g_socket_condition_check() and then
35844 * writing to the socket if it succeeds, it is generally better to
35845 * simply try writing to the socket right away, and try again later if
35846 * the initial attempt returns %G_IO_ERROR_WOULD_BLOCK.
35848 * It is meaningless to specify %G_IO_ERR or %G_IO_HUP in condition;
35849 * these conditions will always be set in the output if they are true.
35851 * This call never blocks.
35853 * Returns: the @GIOCondition mask of the current state
35859 * g_socket_condition_timed_wait:
35860 * @socket: a #GSocket
35861 * @condition: a #GIOCondition mask to wait for
35862 * @timeout_us: the maximum time (in microseconds) to wait, or -1
35863 * @cancellable: (nullable): a #GCancellable, or %NULL
35864 * @error: a #GError pointer, or %NULL
35866 * Waits for up to @timeout_us microseconds for @condition to become true
35867 * on @socket. If the condition is met, %TRUE is returned.
35869 * If @cancellable is cancelled before the condition is met, or if
35870 * @timeout_us (or the socket's #GSocket:timeout) is reached before the
35871 * condition is met, then %FALSE is returned and @error, if non-%NULL,
35872 * is set to the appropriate value (%G_IO_ERROR_CANCELLED or
35873 * %G_IO_ERROR_TIMED_OUT).
35875 * If you don't want a timeout, use g_socket_condition_wait().
35876 * (Alternatively, you can pass -1 for @timeout_us.)
35878 * Note that although @timeout_us is in microseconds for consistency with
35879 * other GLib APIs, this function actually only has millisecond
35880 * resolution, and the behavior is undefined if @timeout_us is not an
35881 * exact number of milliseconds.
35883 * Returns: %TRUE if the condition was met, %FALSE otherwise
35889 * g_socket_condition_wait:
35890 * @socket: a #GSocket
35891 * @condition: a #GIOCondition mask to wait for
35892 * @cancellable: (nullable): a #GCancellable, or %NULL
35893 * @error: a #GError pointer, or %NULL
35895 * Waits for @condition to become true on @socket. When the condition
35896 * is met, %TRUE is returned.
35898 * If @cancellable is cancelled before the condition is met, or if the
35899 * socket has a timeout set and it is reached before the condition is
35900 * met, then %FALSE is returned and @error, if non-%NULL, is set to
35901 * the appropriate value (%G_IO_ERROR_CANCELLED or
35902 * %G_IO_ERROR_TIMED_OUT).
35904 * See also g_socket_condition_timed_wait().
35906 * Returns: %TRUE if the condition was met, %FALSE otherwise
35912 * g_socket_connect:
35913 * @socket: a #GSocket.
35914 * @address: a #GSocketAddress specifying the remote address.
35915 * @cancellable: (nullable): a %GCancellable or %NULL
35916 * @error: #GError for error reporting, or %NULL to ignore.
35918 * Connect the socket to the specified remote address.
35920 * For connection oriented socket this generally means we attempt to make
35921 * a connection to the @address. For a connection-less socket it sets
35922 * the default address for g_socket_send() and discards all incoming datagrams
35923 * from other sources.
35925 * Generally connection oriented sockets can only connect once, but
35926 * connection-less sockets can connect multiple times to change the
35929 * If the connect call needs to do network I/O it will block, unless
35930 * non-blocking I/O is enabled. Then %G_IO_ERROR_PENDING is returned
35931 * and the user can be notified of the connection finishing by waiting
35932 * for the G_IO_OUT condition. The result of the connection must then be
35933 * checked with g_socket_check_connect_result().
35935 * Returns: %TRUE if connected, %FALSE on error.
35941 * g_socket_connectable_enumerate:
35942 * @connectable: a #GSocketConnectable
35944 * Creates a #GSocketAddressEnumerator for @connectable.
35946 * Returns: (transfer full): a new #GSocketAddressEnumerator.
35952 * g_socket_connectable_proxy_enumerate:
35953 * @connectable: a #GSocketConnectable
35955 * Creates a #GSocketAddressEnumerator for @connectable that will
35956 * return a #GProxyAddress for each of its addresses that you must connect
35959 * If @connectable does not implement
35960 * g_socket_connectable_proxy_enumerate(), this will fall back to
35961 * calling g_socket_connectable_enumerate().
35963 * Returns: (transfer full): a new #GSocketAddressEnumerator.
35969 * g_socket_connectable_to_string:
35970 * @connectable: a #GSocketConnectable
35972 * Format a #GSocketConnectable as a string. This is a human-readable format for
35973 * use in debugging output, and is not a stable serialization format. It is not
35974 * suitable for use in user interfaces as it exposes too much information for a
35977 * If the #GSocketConnectable implementation does not support string formatting,
35978 * the implementation’s type name will be returned as a fallback.
35980 * Returns: (transfer full): the formatted string
35986 * g_socket_connection_connect:
35987 * @connection: a #GSocketConnection
35988 * @address: a #GSocketAddress specifying the remote address.
35989 * @cancellable: (nullable): a %GCancellable or %NULL
35990 * @error: #GError for error reporting, or %NULL to ignore.
35992 * Connect @connection to the specified remote address.
35994 * Returns: %TRUE if the connection succeeded, %FALSE on error
36000 * g_socket_connection_connect_async:
36001 * @connection: a #GSocketConnection
36002 * @address: a #GSocketAddress specifying the remote address.
36003 * @cancellable: (nullable): a %GCancellable or %NULL
36004 * @callback: (scope async): a #GAsyncReadyCallback
36005 * @user_data: (closure): user data for the callback
36007 * Asynchronously connect @connection to the specified remote address.
36009 * This clears the #GSocket:blocking flag on @connection's underlying
36010 * socket if it is currently set.
36012 * Use g_socket_connection_connect_finish() to retrieve the result.
36019 * g_socket_connection_connect_finish:
36020 * @connection: a #GSocketConnection
36021 * @result: the #GAsyncResult
36022 * @error: #GError for error reporting, or %NULL to ignore.
36024 * Gets the result of a g_socket_connection_connect_async() call.
36026 * Returns: %TRUE if the connection succeeded, %FALSE on error
36032 * g_socket_connection_factory_create_connection:
36033 * @socket: a #GSocket
36035 * Creates a #GSocketConnection subclass of the right type for
36038 * Returns: (transfer full): a #GSocketConnection
36044 * g_socket_connection_factory_lookup_type:
36045 * @family: a #GSocketFamily
36046 * @type: a #GSocketType
36047 * @protocol_id: a protocol id
36049 * Looks up the #GType to be used when creating socket connections on
36050 * sockets with the specified @family, @type and @protocol_id.
36052 * If no type is registered, the #GSocketConnection base type is returned.
36054 * Returns: a #GType
36060 * g_socket_connection_factory_register_type:
36061 * @g_type: a #GType, inheriting from %G_TYPE_SOCKET_CONNECTION
36062 * @family: a #GSocketFamily
36063 * @type: a #GSocketType
36064 * @protocol: a protocol id
36066 * Looks up the #GType to be used when creating socket connections on
36067 * sockets with the specified @family, @type and @protocol.
36069 * If no type is registered, the #GSocketConnection base type is returned.
36076 * g_socket_connection_get_local_address:
36077 * @connection: a #GSocketConnection
36078 * @error: #GError for error reporting, or %NULL to ignore.
36080 * Try to get the local address of a socket connection.
36082 * Returns: (transfer full): a #GSocketAddress or %NULL on error.
36083 * Free the returned object with g_object_unref().
36089 * g_socket_connection_get_remote_address:
36090 * @connection: a #GSocketConnection
36091 * @error: #GError for error reporting, or %NULL to ignore.
36093 * Try to get the remote address of a socket connection.
36095 * Since GLib 2.40, when used with g_socket_client_connect() or
36096 * g_socket_client_connect_async(), during emission of
36097 * %G_SOCKET_CLIENT_CONNECTING, this function will return the remote
36098 * address that will be used for the connection. This allows
36099 * applications to print e.g. "Connecting to example.com
36100 * (10.42.77.3)...".
36102 * Returns: (transfer full): a #GSocketAddress or %NULL on error.
36103 * Free the returned object with g_object_unref().
36109 * g_socket_connection_get_socket:
36110 * @connection: a #GSocketConnection
36112 * Gets the underlying #GSocket object of the connection.
36113 * This can be useful if you want to do something unusual on it
36114 * not supported by the #GSocketConnection APIs.
36116 * Returns: (transfer none): a #GSocket or %NULL on error.
36122 * g_socket_connection_is_connected:
36123 * @connection: a #GSocketConnection
36125 * Checks if @connection is connected. This is equivalent to calling
36126 * g_socket_is_connected() on @connection's underlying #GSocket.
36128 * Returns: whether @connection is connected
36134 * g_socket_control_message_deserialize:
36135 * @level: a socket level
36136 * @type: a socket control message type for the given @level
36137 * @size: the size of the data in bytes
36138 * @data: (array length=size) (element-type guint8): pointer to the message data
36140 * Tries to deserialize a socket control message of a given
36141 * @level and @type. This will ask all known (to GType) subclasses
36142 * of #GSocketControlMessage if they can understand this kind
36143 * of message and if so deserialize it into a #GSocketControlMessage.
36145 * If there is no implementation for this kind of control message, %NULL
36146 * will be returned.
36148 * Returns: (transfer full): the deserialized message or %NULL
36154 * g_socket_control_message_get_level:
36155 * @message: a #GSocketControlMessage
36157 * Returns the "level" (i.e. the originating protocol) of the control message.
36158 * This is often SOL_SOCKET.
36160 * Returns: an integer describing the level
36166 * g_socket_control_message_get_msg_type:
36167 * @message: a #GSocketControlMessage
36169 * Returns the protocol specific type of the control message.
36170 * For instance, for UNIX fd passing this would be SCM_RIGHTS.
36172 * Returns: an integer describing the type of control message
36178 * g_socket_control_message_get_size:
36179 * @message: a #GSocketControlMessage
36181 * Returns the space required for the control message, not including
36182 * headers or alignment.
36184 * Returns: The number of bytes required.
36190 * g_socket_control_message_serialize:
36191 * @message: a #GSocketControlMessage
36192 * @data: (not nullable): A buffer to write data to
36194 * Converts the data in the message to bytes placed in the
36197 * @data is guaranteed to have enough space to fit the size
36198 * returned by g_socket_control_message_get_size() on this
36206 * g_socket_create_source: (skip)
36207 * @socket: a #GSocket
36208 * @condition: a #GIOCondition mask to monitor
36209 * @cancellable: (nullable): a %GCancellable or %NULL
36211 * Creates a #GSource that can be attached to a %GMainContext to monitor
36212 * for the availability of the specified @condition on the socket. The #GSource
36213 * keeps a reference to the @socket.
36215 * The callback on the source is of the #GSocketSourceFunc type.
36217 * It is meaningless to specify %G_IO_ERR or %G_IO_HUP in @condition;
36218 * these conditions will always be reported output if they are true.
36220 * @cancellable if not %NULL can be used to cancel the source, which will
36221 * cause the source to trigger, reporting the current condition (which
36222 * is likely 0 unless cancellation happened at the same time as a
36223 * condition change). You can check for this in the callback using
36224 * g_cancellable_is_cancelled().
36226 * If @socket has a timeout set, and it is reached before @condition
36227 * occurs, the source will then trigger anyway, reporting %G_IO_IN or
36228 * %G_IO_OUT depending on @condition. However, @socket will have been
36229 * marked as having had a timeout, and so the next #GSocket I/O method
36230 * you call will then fail with a %G_IO_ERROR_TIMED_OUT.
36232 * Returns: (transfer full): a newly allocated %GSource, free with g_source_unref().
36238 * g_socket_get_available_bytes:
36239 * @socket: a #GSocket
36241 * Get the amount of data pending in the OS input buffer, without blocking.
36243 * If @socket is a UDP or SCTP socket, this will return the size of
36244 * just the next packet, even if additional packets are buffered after
36247 * Note that on Windows, this function is rather inefficient in the
36248 * UDP case, and so if you know any plausible upper bound on the size
36249 * of the incoming packet, it is better to just do a
36250 * g_socket_receive() with a buffer of that size, rather than calling
36251 * g_socket_get_available_bytes() first and then doing a receive of
36252 * exactly the right size.
36254 * Returns: the number of bytes that can be read from the socket
36255 * without blocking or truncating, or -1 on error.
36261 * g_socket_get_blocking:
36262 * @socket: a #GSocket.
36264 * Gets the blocking mode of the socket. For details on blocking I/O,
36265 * see g_socket_set_blocking().
36267 * Returns: %TRUE if blocking I/O is used, %FALSE otherwise.
36273 * g_socket_get_broadcast:
36274 * @socket: a #GSocket.
36276 * Gets the broadcast setting on @socket; if %TRUE,
36277 * it is possible to send packets to broadcast
36280 * Returns: the broadcast setting on @socket
36286 * g_socket_get_credentials:
36287 * @socket: a #GSocket.
36288 * @error: #GError for error reporting, or %NULL to ignore.
36290 * Returns the credentials of the foreign process connected to this
36291 * socket, if any (e.g. it is only supported for %G_SOCKET_FAMILY_UNIX
36294 * If this operation isn't supported on the OS, the method fails with
36295 * the %G_IO_ERROR_NOT_SUPPORTED error. On Linux this is implemented
36296 * by reading the %SO_PEERCRED option on the underlying socket.
36298 * This method can be expected to be available on the following platforms:
36300 * - Linux since GLib 2.26
36301 * - OpenBSD since GLib 2.30
36302 * - Solaris, Illumos and OpenSolaris since GLib 2.40
36303 * - NetBSD since GLib 2.42
36304 * - macOS, tvOS, iOS since GLib 2.66
36306 * Other ways to obtain credentials from a foreign peer includes the
36307 * #GUnixCredentialsMessage type and
36308 * g_unix_connection_send_credentials() /
36309 * g_unix_connection_receive_credentials() functions.
36311 * Returns: (transfer full): %NULL if @error is set, otherwise a #GCredentials object
36312 * that must be freed with g_object_unref().
36318 * g_socket_get_family:
36319 * @socket: a #GSocket.
36321 * Gets the socket family of the socket.
36323 * Returns: a #GSocketFamily
36330 * @socket: a #GSocket.
36332 * Returns the underlying OS socket object. On unix this
36333 * is a socket file descriptor, and on Windows this is
36334 * a Winsock2 SOCKET handle. This may be useful for
36335 * doing platform specific or otherwise unusual operations
36338 * Returns: the file descriptor of the socket.
36344 * g_socket_get_keepalive:
36345 * @socket: a #GSocket.
36347 * Gets the keepalive mode of the socket. For details on this,
36348 * see g_socket_set_keepalive().
36350 * Returns: %TRUE if keepalive is active, %FALSE otherwise.
36356 * g_socket_get_listen_backlog:
36357 * @socket: a #GSocket.
36359 * Gets the listen backlog setting of the socket. For details on this,
36360 * see g_socket_set_listen_backlog().
36362 * Returns: the maximum number of pending connections.
36368 * g_socket_get_local_address:
36369 * @socket: a #GSocket.
36370 * @error: #GError for error reporting, or %NULL to ignore.
36372 * Try to get the local address of a bound socket. This is only
36373 * useful if the socket has been bound to a local address,
36374 * either explicitly or implicitly when connecting.
36376 * Returns: (transfer full): a #GSocketAddress or %NULL on error.
36377 * Free the returned object with g_object_unref().
36383 * g_socket_get_multicast_loopback:
36384 * @socket: a #GSocket.
36386 * Gets the multicast loopback setting on @socket; if %TRUE (the
36387 * default), outgoing multicast packets will be looped back to
36388 * multicast listeners on the same host.
36390 * Returns: the multicast loopback setting on @socket
36396 * g_socket_get_multicast_ttl:
36397 * @socket: a #GSocket.
36399 * Gets the multicast time-to-live setting on @socket; see
36400 * g_socket_set_multicast_ttl() for more details.
36402 * Returns: the multicast time-to-live setting on @socket
36408 * g_socket_get_option:
36409 * @socket: a #GSocket
36410 * @level: the "API level" of the option (eg, `SOL_SOCKET`)
36411 * @optname: the "name" of the option (eg, `SO_BROADCAST`)
36412 * @value: (out): return location for the option value
36413 * @error: #GError for error reporting, or %NULL to ignore.
36415 * Gets the value of an integer-valued option on @socket, as with
36416 * getsockopt(). (If you need to fetch a non-integer-valued option,
36417 * you will need to call getsockopt() directly.)
36419 * The [<gio/gnetworking.h>][gio-gnetworking.h]
36420 * header pulls in system headers that will define most of the
36421 * standard/portable socket options. For unusual socket protocols or
36422 * platform-dependent options, you may need to include additional
36425 * Note that even for socket options that are a single byte in size,
36426 * @value is still a pointer to a #gint variable, not a #guchar;
36427 * g_socket_get_option() will handle the conversion internally.
36429 * Returns: success or failure. On failure, @error will be set, and
36430 * the system error value (`errno` or WSAGetLastError()) will still
36431 * be set to the result of the getsockopt() call.
36437 * g_socket_get_protocol:
36438 * @socket: a #GSocket.
36440 * Gets the socket protocol id the socket was created with.
36441 * In case the protocol is unknown, -1 is returned.
36443 * Returns: a protocol id, or -1 if unknown
36449 * g_socket_get_remote_address:
36450 * @socket: a #GSocket.
36451 * @error: #GError for error reporting, or %NULL to ignore.
36453 * Try to get the remote address of a connected socket. This is only
36454 * useful for connection oriented sockets that have been connected.
36456 * Returns: (transfer full): a #GSocketAddress or %NULL on error.
36457 * Free the returned object with g_object_unref().
36463 * g_socket_get_socket_type:
36464 * @socket: a #GSocket.
36466 * Gets the socket type of the socket.
36468 * Returns: a #GSocketType
36474 * g_socket_get_timeout:
36475 * @socket: a #GSocket.
36477 * Gets the timeout setting of the socket. For details on this, see
36478 * g_socket_set_timeout().
36480 * Returns: the timeout in seconds
36486 * g_socket_get_ttl:
36487 * @socket: a #GSocket.
36489 * Gets the unicast time-to-live setting on @socket; see
36490 * g_socket_set_ttl() for more details.
36492 * Returns: the time-to-live setting on @socket
36498 * g_socket_is_closed:
36499 * @socket: a #GSocket
36501 * Checks whether a socket is closed.
36503 * Returns: %TRUE if socket is closed, %FALSE otherwise
36509 * g_socket_is_connected:
36510 * @socket: a #GSocket.
36512 * Check whether the socket is connected. This is only useful for
36513 * connection-oriented sockets.
36515 * If using g_socket_shutdown(), this function will return %TRUE until the
36516 * socket has been shut down for reading and writing. If you do a non-blocking
36517 * connect, this function will not return %TRUE until after you call
36518 * g_socket_check_connect_result().
36520 * Returns: %TRUE if socket is connected, %FALSE otherwise.
36526 * g_socket_join_multicast_group:
36527 * @socket: a #GSocket.
36528 * @group: a #GInetAddress specifying the group address to join.
36529 * @iface: (nullable): Name of the interface to use, or %NULL
36530 * @source_specific: %TRUE if source-specific multicast should be used
36531 * @error: #GError for error reporting, or %NULL to ignore.
36533 * Registers @socket to receive multicast messages sent to @group.
36534 * @socket must be a %G_SOCKET_TYPE_DATAGRAM socket, and must have
36535 * been bound to an appropriate interface and port with
36538 * If @iface is %NULL, the system will automatically pick an interface
36539 * to bind to based on @group.
36541 * If @source_specific is %TRUE, source-specific multicast as defined
36542 * in RFC 4604 is used. Note that on older platforms this may fail
36543 * with a %G_IO_ERROR_NOT_SUPPORTED error.
36545 * To bind to a given source-specific multicast address, use
36546 * g_socket_join_multicast_group_ssm() instead.
36548 * Returns: %TRUE on success, %FALSE on error.
36554 * g_socket_join_multicast_group_ssm:
36555 * @socket: a #GSocket.
36556 * @group: a #GInetAddress specifying the group address to join.
36557 * @source_specific: (nullable): a #GInetAddress specifying the
36558 * source-specific multicast address or %NULL to ignore.
36559 * @iface: (nullable): Name of the interface to use, or %NULL
36560 * @error: #GError for error reporting, or %NULL to ignore.
36562 * Registers @socket to receive multicast messages sent to @group.
36563 * @socket must be a %G_SOCKET_TYPE_DATAGRAM socket, and must have
36564 * been bound to an appropriate interface and port with
36567 * If @iface is %NULL, the system will automatically pick an interface
36568 * to bind to based on @group.
36570 * If @source_specific is not %NULL, use source-specific multicast as
36571 * defined in RFC 4604. Note that on older platforms this may fail
36572 * with a %G_IO_ERROR_NOT_SUPPORTED error.
36574 * Note that this function can be called multiple times for the same
36575 * @group with different @source_specific in order to receive multicast
36576 * packets from more than one source.
36578 * Returns: %TRUE on success, %FALSE on error.
36584 * g_socket_leave_multicast_group:
36585 * @socket: a #GSocket.
36586 * @group: a #GInetAddress specifying the group address to leave.
36587 * @iface: (nullable): Interface used
36588 * @source_specific: %TRUE if source-specific multicast was used
36589 * @error: #GError for error reporting, or %NULL to ignore.
36591 * Removes @socket from the multicast group defined by @group, @iface,
36592 * and @source_specific (which must all have the same values they had
36593 * when you joined the group).
36595 * @socket remains bound to its address and port, and can still receive
36596 * unicast messages after calling this.
36598 * To unbind to a given source-specific multicast address, use
36599 * g_socket_leave_multicast_group_ssm() instead.
36601 * Returns: %TRUE on success, %FALSE on error.
36607 * g_socket_leave_multicast_group_ssm:
36608 * @socket: a #GSocket.
36609 * @group: a #GInetAddress specifying the group address to leave.
36610 * @source_specific: (nullable): a #GInetAddress specifying the
36611 * source-specific multicast address or %NULL to ignore.
36612 * @iface: (nullable): Name of the interface to use, or %NULL
36613 * @error: #GError for error reporting, or %NULL to ignore.
36615 * Removes @socket from the multicast group defined by @group, @iface,
36616 * and @source_specific (which must all have the same values they had
36617 * when you joined the group).
36619 * @socket remains bound to its address and port, and can still receive
36620 * unicast messages after calling this.
36622 * Returns: %TRUE on success, %FALSE on error.
36629 * @socket: a #GSocket.
36630 * @error: #GError for error reporting, or %NULL to ignore.
36632 * Marks the socket as a server socket, i.e. a socket that is used
36633 * to accept incoming requests using g_socket_accept().
36635 * Before calling this the socket must be bound to a local address using
36638 * To set the maximum amount of outstanding clients, use
36639 * g_socket_set_listen_backlog().
36641 * Returns: %TRUE on success, %FALSE on error.
36647 * g_socket_listener_accept:
36648 * @listener: a #GSocketListener
36649 * @source_object: (out) (transfer none) (optional) (nullable): location where #GObject pointer will be stored, or %NULL
36650 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
36651 * @error: #GError for error reporting, or %NULL to ignore.
36653 * Blocks waiting for a client to connect to any of the sockets added
36654 * to the listener. Returns a #GSocketConnection for the socket that was
36657 * If @source_object is not %NULL it will be filled out with the source
36658 * object specified when the corresponding socket or address was added
36661 * If @cancellable is not %NULL, then the operation can be cancelled by
36662 * triggering the cancellable object from another thread. If the operation
36663 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
36665 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
36671 * g_socket_listener_accept_async:
36672 * @listener: a #GSocketListener
36673 * @cancellable: (nullable): a #GCancellable, or %NULL
36674 * @callback: (scope async): a #GAsyncReadyCallback
36675 * @user_data: (closure): user data for the callback
36677 * This is the asynchronous version of g_socket_listener_accept().
36679 * When the operation is finished @callback will be
36680 * called. You can then call g_socket_listener_accept_finish()
36681 * to get the result of the operation.
36688 * g_socket_listener_accept_finish:
36689 * @listener: a #GSocketListener
36690 * @result: a #GAsyncResult.
36691 * @source_object: (out) (transfer none) (optional) (nullable): Optional #GObject identifying this source
36692 * @error: a #GError location to store the error occurring, or %NULL to
36695 * Finishes an async accept operation. See g_socket_listener_accept_async()
36697 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
36703 * g_socket_listener_accept_socket:
36704 * @listener: a #GSocketListener
36705 * @source_object: (out) (transfer none) (optional) (nullable): location where #GObject pointer will be stored, or %NULL.
36706 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
36707 * @error: #GError for error reporting, or %NULL to ignore.
36709 * Blocks waiting for a client to connect to any of the sockets added
36710 * to the listener. Returns the #GSocket that was accepted.
36712 * If you want to accept the high-level #GSocketConnection, not a #GSocket,
36713 * which is often the case, then you should use g_socket_listener_accept()
36716 * If @source_object is not %NULL it will be filled out with the source
36717 * object specified when the corresponding socket or address was added
36720 * If @cancellable is not %NULL, then the operation can be cancelled by
36721 * triggering the cancellable object from another thread. If the operation
36722 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
36724 * Returns: (transfer full): a #GSocket on success, %NULL on error.
36730 * g_socket_listener_accept_socket_async:
36731 * @listener: a #GSocketListener
36732 * @cancellable: (nullable): a #GCancellable, or %NULL
36733 * @callback: (scope async): a #GAsyncReadyCallback
36734 * @user_data: (closure): user data for the callback
36736 * This is the asynchronous version of g_socket_listener_accept_socket().
36738 * When the operation is finished @callback will be
36739 * called. You can then call g_socket_listener_accept_socket_finish()
36740 * to get the result of the operation.
36747 * g_socket_listener_accept_socket_finish:
36748 * @listener: a #GSocketListener
36749 * @result: a #GAsyncResult.
36750 * @source_object: (out) (transfer none) (optional) (nullable): Optional #GObject identifying this source
36751 * @error: a #GError location to store the error occurring, or %NULL to
36754 * Finishes an async accept operation. See g_socket_listener_accept_socket_async()
36756 * Returns: (transfer full): a #GSocket on success, %NULL on error.
36762 * g_socket_listener_add_address:
36763 * @listener: a #GSocketListener
36764 * @address: a #GSocketAddress
36765 * @type: a #GSocketType
36766 * @protocol: a #GSocketProtocol
36767 * @source_object: (nullable): Optional #GObject identifying this source
36768 * @effective_address: (out) (optional): location to store the address that was bound to, or %NULL.
36769 * @error: #GError for error reporting, or %NULL to ignore.
36771 * Creates a socket of type @type and protocol @protocol, binds
36772 * it to @address and adds it to the set of sockets we're accepting
36775 * Note that adding an IPv6 address, depending on the platform,
36776 * may or may not result in a listener that also accepts IPv4
36777 * connections. For more deterministic behavior, see
36778 * g_socket_listener_add_inet_port().
36780 * @source_object will be passed out in the various calls
36781 * to accept to identify this particular source, which is
36782 * useful if you're listening on multiple addresses and do
36783 * different things depending on what address is connected to.
36785 * If successful and @effective_address is non-%NULL then it will
36786 * be set to the address that the binding actually occurred at. This
36787 * is helpful for determining the port number that was used for when
36788 * requesting a binding to port 0 (ie: "any port"). This address, if
36789 * requested, belongs to the caller and must be freed.
36791 * Call g_socket_listener_close() to stop listening on @address; this will not
36792 * be done automatically when you drop your final reference to @listener, as
36793 * references may be held internally.
36795 * Returns: %TRUE on success, %FALSE on error.
36801 * g_socket_listener_add_any_inet_port:
36802 * @listener: a #GSocketListener
36803 * @source_object: (nullable): Optional #GObject identifying this source
36804 * @error: a #GError location to store the error occurring, or %NULL to
36807 * Listens for TCP connections on any available port number for both
36808 * IPv6 and IPv4 (if each is available).
36810 * This is useful if you need to have a socket for incoming connections
36811 * but don't care about the specific port number.
36813 * @source_object will be passed out in the various calls
36814 * to accept to identify this particular source, which is
36815 * useful if you're listening on multiple addresses and do
36816 * different things depending on what address is connected to.
36818 * Returns: the port number, or 0 in case of failure.
36824 * g_socket_listener_add_inet_port:
36825 * @listener: a #GSocketListener
36826 * @port: an IP port number (non-zero)
36827 * @source_object: (nullable): Optional #GObject identifying this source
36828 * @error: #GError for error reporting, or %NULL to ignore.
36830 * Helper function for g_socket_listener_add_address() that
36831 * creates a TCP/IP socket listening on IPv4 and IPv6 (if
36832 * supported) on the specified port on all interfaces.
36834 * @source_object will be passed out in the various calls
36835 * to accept to identify this particular source, which is
36836 * useful if you're listening on multiple addresses and do
36837 * different things depending on what address is connected to.
36839 * Call g_socket_listener_close() to stop listening on @port; this will not
36840 * be done automatically when you drop your final reference to @listener, as
36841 * references may be held internally.
36843 * Returns: %TRUE on success, %FALSE on error.
36849 * g_socket_listener_add_socket:
36850 * @listener: a #GSocketListener
36851 * @socket: a listening #GSocket
36852 * @source_object: (nullable): Optional #GObject identifying this source
36853 * @error: #GError for error reporting, or %NULL to ignore.
36855 * Adds @socket to the set of sockets that we try to accept
36856 * new clients from. The socket must be bound to a local
36857 * address and listened to.
36859 * @source_object will be passed out in the various calls
36860 * to accept to identify this particular source, which is
36861 * useful if you're listening on multiple addresses and do
36862 * different things depending on what address is connected to.
36864 * The @socket will not be automatically closed when the @listener is finalized
36865 * unless the listener held the final reference to the socket. Before GLib 2.42,
36866 * the @socket was automatically closed on finalization of the @listener, even
36867 * if references to it were held elsewhere.
36869 * Returns: %TRUE on success, %FALSE on error.
36875 * g_socket_listener_close:
36876 * @listener: a #GSocketListener
36878 * Closes all the sockets in the listener.
36885 * g_socket_listener_new:
36887 * Creates a new #GSocketListener with no sockets to listen for.
36888 * New listeners can be added with e.g. g_socket_listener_add_address()
36889 * or g_socket_listener_add_inet_port().
36891 * Returns: a new #GSocketListener.
36897 * g_socket_listener_set_backlog:
36898 * @listener: a #GSocketListener
36899 * @listen_backlog: an integer
36901 * Sets the listen backlog on the sockets in the listener. This must be called
36902 * before adding any sockets, addresses or ports to the #GSocketListener (for
36903 * example, by calling g_socket_listener_add_inet_port()) to be effective.
36905 * See g_socket_set_listen_backlog() for details
36913 * @family: the socket family to use, e.g. %G_SOCKET_FAMILY_IPV4.
36914 * @type: the socket type to use.
36915 * @protocol: the id of the protocol to use, or 0 for default.
36916 * @error: #GError for error reporting, or %NULL to ignore.
36918 * Creates a new #GSocket with the defined family, type and protocol.
36919 * If @protocol is 0 (%G_SOCKET_PROTOCOL_DEFAULT) the default protocol type
36920 * for the family and type is used.
36922 * The @protocol is a family and type specific int that specifies what
36923 * kind of protocol to use. #GSocketProtocol lists several common ones.
36924 * Many families only support one protocol, and use 0 for this, others
36925 * support several and using 0 means to use the default protocol for
36926 * the family and type.
36928 * The protocol id is passed directly to the operating
36929 * system, so you can use protocols not listed in #GSocketProtocol if you
36930 * know the protocol number used for it.
36932 * Returns: a #GSocket or %NULL on error.
36933 * Free the returned object with g_object_unref().
36939 * g_socket_new_from_fd:
36940 * @fd: a native socket file descriptor.
36941 * @error: #GError for error reporting, or %NULL to ignore.
36943 * Creates a new #GSocket from a native file descriptor
36944 * or winsock SOCKET handle.
36946 * This reads all the settings from the file descriptor so that
36947 * all properties should work. Note that the file descriptor
36948 * will be set to non-blocking mode, independent on the blocking
36949 * mode of the #GSocket.
36951 * On success, the returned #GSocket takes ownership of @fd. On failure, the
36952 * caller must close @fd themselves.
36954 * Since GLib 2.46, it is no longer a fatal error to call this on a non-socket
36955 * descriptor. Instead, a GError will be set with code %G_IO_ERROR_FAILED
36957 * Returns: a #GSocket or %NULL on error.
36958 * Free the returned object with g_object_unref().
36964 * g_socket_receive:
36965 * @socket: a #GSocket
36966 * @buffer: (array length=size) (element-type guint8) (out caller-allocates):
36967 * a buffer to read data into (which should be at least @size bytes long).
36968 * @size: the number of bytes you want to read from the socket
36969 * @cancellable: (nullable): a %GCancellable or %NULL
36970 * @error: #GError for error reporting, or %NULL to ignore.
36972 * Receive data (up to @size bytes) from a socket. This is mainly used by
36973 * connection-oriented sockets; it is identical to g_socket_receive_from()
36974 * with @address set to %NULL.
36976 * For %G_SOCKET_TYPE_DATAGRAM and %G_SOCKET_TYPE_SEQPACKET sockets,
36977 * g_socket_receive() will always read either 0 or 1 complete messages from
36978 * the socket. If the received message is too large to fit in @buffer, then
36979 * the data beyond @size bytes will be discarded, without any explicit
36980 * indication that this has occurred.
36982 * For %G_SOCKET_TYPE_STREAM sockets, g_socket_receive() can return any
36983 * number of bytes, up to @size. If more than @size bytes have been
36984 * received, the additional data will be returned in future calls to
36985 * g_socket_receive().
36987 * If the socket is in blocking mode the call will block until there
36988 * is some data to receive, the connection is closed, or there is an
36989 * error. If there is no data available and the socket is in
36990 * non-blocking mode, a %G_IO_ERROR_WOULD_BLOCK error will be
36991 * returned. To be notified when data is available, wait for the
36992 * %G_IO_IN condition.
36994 * On error -1 is returned and @error is set accordingly.
36996 * Returns: Number of bytes read, or 0 if the connection was closed by
36997 * the peer, or -1 on error
37003 * g_socket_receive_from:
37004 * @socket: a #GSocket
37005 * @address: (out) (optional): a pointer to a #GSocketAddress
37006 * pointer, or %NULL
37007 * @buffer: (array length=size) (element-type guint8) (out caller-allocates):
37008 * a buffer to read data into (which should be at least @size bytes long).
37009 * @size: the number of bytes you want to read from the socket
37010 * @cancellable: (nullable): a %GCancellable or %NULL
37011 * @error: #GError for error reporting, or %NULL to ignore.
37013 * Receive data (up to @size bytes) from a socket.
37015 * If @address is non-%NULL then @address will be set equal to the
37016 * source address of the received packet.
37017 * @address is owned by the caller.
37019 * See g_socket_receive() for additional information.
37021 * Returns: Number of bytes read, or 0 if the connection was closed by
37022 * the peer, or -1 on error
37028 * g_socket_receive_message:
37029 * @socket: a #GSocket
37030 * @address: (out) (optional): a pointer to a #GSocketAddress
37031 * pointer, or %NULL
37032 * @vectors: (array length=num_vectors): an array of #GInputVector structs
37033 * @num_vectors: the number of elements in @vectors, or -1
37034 * @messages: (array length=num_messages) (out) (optional) (nullable): a pointer
37035 * which may be filled with an array of #GSocketControlMessages, or %NULL
37036 * @num_messages: (out): a pointer which will be filled with the number of
37037 * elements in @messages, or %NULL
37038 * @flags: (inout): a pointer to an int containing #GSocketMsgFlags flags,
37039 * which may additionally contain
37040 * [other platform specific flags](http://man7.org/linux/man-pages/man2/recv.2.html)
37041 * @cancellable: a %GCancellable or %NULL
37042 * @error: a #GError pointer, or %NULL
37044 * Receive data from a socket. For receiving multiple messages, see
37045 * g_socket_receive_messages(); for easier use, see
37046 * g_socket_receive() and g_socket_receive_from().
37048 * If @address is non-%NULL then @address will be set equal to the
37049 * source address of the received packet.
37050 * @address is owned by the caller.
37052 * @vector must point to an array of #GInputVector structs and
37053 * @num_vectors must be the length of this array. These structs
37054 * describe the buffers that received data will be scattered into.
37055 * If @num_vectors is -1, then @vectors is assumed to be terminated
37056 * by a #GInputVector with a %NULL buffer pointer.
37058 * As a special case, if @num_vectors is 0 (in which case, @vectors
37059 * may of course be %NULL), then a single byte is received and
37060 * discarded. This is to facilitate the common practice of sending a
37061 * single '\0' byte for the purposes of transferring ancillary data.
37063 * @messages, if non-%NULL, will be set to point to a newly-allocated
37064 * array of #GSocketControlMessage instances or %NULL if no such
37065 * messages was received. These correspond to the control messages
37066 * received from the kernel, one #GSocketControlMessage per message
37067 * from the kernel. This array is %NULL-terminated and must be freed
37068 * by the caller using g_free() after calling g_object_unref() on each
37069 * element. If @messages is %NULL, any control messages received will
37072 * @num_messages, if non-%NULL, will be set to the number of control
37073 * messages received.
37075 * If both @messages and @num_messages are non-%NULL, then
37076 * @num_messages gives the number of #GSocketControlMessage instances
37077 * in @messages (ie: not including the %NULL terminator).
37079 * @flags is an in/out parameter. The commonly available arguments
37080 * for this are available in the #GSocketMsgFlags enum, but the
37081 * values there are the same as the system values, and the flags
37082 * are passed in as-is, so you can pass in system-specific flags too
37083 * (and g_socket_receive_message() may pass system-specific flags out).
37084 * Flags passed in to the parameter affect the receive operation; flags returned
37085 * out of it are relevant to the specific returned message.
37087 * As with g_socket_receive(), data may be discarded if @socket is
37088 * %G_SOCKET_TYPE_DATAGRAM or %G_SOCKET_TYPE_SEQPACKET and you do not
37089 * provide enough buffer space to read a complete message. You can pass
37090 * %G_SOCKET_MSG_PEEK in @flags to peek at the current message without
37091 * removing it from the receive queue, but there is no portable way to find
37092 * out the length of the message other than by reading it into a
37093 * sufficiently-large buffer.
37095 * If the socket is in blocking mode the call will block until there
37096 * is some data to receive, the connection is closed, or there is an
37097 * error. If there is no data available and the socket is in
37098 * non-blocking mode, a %G_IO_ERROR_WOULD_BLOCK error will be
37099 * returned. To be notified when data is available, wait for the
37100 * %G_IO_IN condition.
37102 * On error -1 is returned and @error is set accordingly.
37104 * Returns: Number of bytes read, or 0 if the connection was closed by
37105 * the peer, or -1 on error
37111 * g_socket_receive_messages:
37112 * @socket: a #GSocket
37113 * @messages: (array length=num_messages): an array of #GInputMessage structs
37114 * @num_messages: the number of elements in @messages
37115 * @flags: an int containing #GSocketMsgFlags flags for the overall operation,
37116 * which may additionally contain
37117 * [other platform specific flags](http://man7.org/linux/man-pages/man2/recv.2.html)
37118 * @cancellable: (nullable): a %GCancellable or %NULL
37119 * @error: #GError for error reporting, or %NULL to ignore
37121 * Receive multiple data messages from @socket in one go. This is the most
37122 * complicated and fully-featured version of this call. For easier use, see
37123 * g_socket_receive(), g_socket_receive_from(), and g_socket_receive_message().
37125 * @messages must point to an array of #GInputMessage structs and
37126 * @num_messages must be the length of this array. Each #GInputMessage
37127 * contains a pointer to an array of #GInputVector structs describing the
37128 * buffers that the data received in each message will be written to. Using
37129 * multiple #GInputVectors is more memory-efficient than manually copying data
37130 * out of a single buffer to multiple sources, and more system-call-efficient
37131 * than making multiple calls to g_socket_receive(), such as in scenarios where
37132 * a lot of data packets need to be received (e.g. high-bandwidth video
37133 * streaming over RTP/UDP).
37135 * @flags modify how all messages are received. The commonly available
37136 * arguments for this are available in the #GSocketMsgFlags enum, but the
37137 * values there are the same as the system values, and the flags
37138 * are passed in as-is, so you can pass in system-specific flags too. These
37139 * flags affect the overall receive operation. Flags affecting individual
37140 * messages are returned in #GInputMessage.flags.
37142 * The other members of #GInputMessage are treated as described in its
37145 * If #GSocket:blocking is %TRUE the call will block until @num_messages have
37146 * been received, or the end of the stream is reached.
37148 * If #GSocket:blocking is %FALSE the call will return up to @num_messages
37149 * without blocking, or %G_IO_ERROR_WOULD_BLOCK if no messages are queued in the
37150 * operating system to be received.
37152 * In blocking mode, if #GSocket:timeout is positive and is reached before any
37153 * messages are received, %G_IO_ERROR_TIMED_OUT is returned, otherwise up to
37154 * @num_messages are returned. (Note: This is effectively the
37155 * behaviour of `MSG_WAITFORONE` with recvmmsg().)
37157 * To be notified when messages are available, wait for the
37158 * %G_IO_IN condition. Note though that you may still receive
37159 * %G_IO_ERROR_WOULD_BLOCK from g_socket_receive_messages() even if you were
37160 * previously notified of a %G_IO_IN condition.
37162 * If the remote peer closes the connection, any messages queued in the
37163 * operating system will be returned, and subsequent calls to
37164 * g_socket_receive_messages() will return 0 (with no error set).
37166 * On error -1 is returned and @error is set accordingly. An error will only
37167 * be returned if zero messages could be received; otherwise the number of
37168 * messages successfully received before the error will be returned.
37170 * Returns: number of messages received, or -1 on error. Note that the number
37171 * of messages received may be smaller than @num_messages if in non-blocking
37172 * mode, if the peer closed the connection, or if @num_messages
37173 * was larger than `UIO_MAXIOV` (1024), in which case the caller may re-try
37174 * to receive the remaining messages.
37180 * g_socket_receive_with_blocking:
37181 * @socket: a #GSocket
37182 * @buffer: (array length=size) (element-type guint8) (out caller-allocates):
37183 * a buffer to read data into (which should be at least @size bytes long).
37184 * @size: the number of bytes you want to read from the socket
37185 * @blocking: whether to do blocking or non-blocking I/O
37186 * @cancellable: (nullable): a %GCancellable or %NULL
37187 * @error: #GError for error reporting, or %NULL to ignore.
37189 * This behaves exactly the same as g_socket_receive(), except that
37190 * the choice of blocking or non-blocking behavior is determined by
37191 * the @blocking argument rather than by @socket's properties.
37193 * Returns: Number of bytes read, or 0 if the connection was closed by
37194 * the peer, or -1 on error
37201 * @socket: a #GSocket
37202 * @buffer: (array length=size) (element-type guint8): the buffer
37203 * containing the data to send.
37204 * @size: the number of bytes to send
37205 * @cancellable: (nullable): a %GCancellable or %NULL
37206 * @error: #GError for error reporting, or %NULL to ignore.
37208 * Tries to send @size bytes from @buffer on the socket. This is
37209 * mainly used by connection-oriented sockets; it is identical to
37210 * g_socket_send_to() with @address set to %NULL.
37212 * If the socket is in blocking mode the call will block until there is
37213 * space for the data in the socket queue. If there is no space available
37214 * and the socket is in non-blocking mode a %G_IO_ERROR_WOULD_BLOCK error
37215 * will be returned. To be notified when space is available, wait for the
37216 * %G_IO_OUT condition. Note though that you may still receive
37217 * %G_IO_ERROR_WOULD_BLOCK from g_socket_send() even if you were previously
37218 * notified of a %G_IO_OUT condition. (On Windows in particular, this is
37219 * very common due to the way the underlying APIs work.)
37221 * On error -1 is returned and @error is set accordingly.
37223 * Returns: Number of bytes written (which may be less than @size), or -1
37230 * g_socket_send_message:
37231 * @socket: a #GSocket
37232 * @address: (nullable): a #GSocketAddress, or %NULL
37233 * @vectors: (array length=num_vectors): an array of #GOutputVector structs
37234 * @num_vectors: the number of elements in @vectors, or -1
37235 * @messages: (array length=num_messages) (nullable): a pointer to an
37236 * array of #GSocketControlMessages, or %NULL.
37237 * @num_messages: number of elements in @messages, or -1.
37238 * @flags: an int containing #GSocketMsgFlags flags, which may additionally
37239 * contain [other platform specific flags](http://man7.org/linux/man-pages/man2/recv.2.html)
37240 * @cancellable: (nullable): a %GCancellable or %NULL
37241 * @error: #GError for error reporting, or %NULL to ignore.
37243 * Send data to @address on @socket. For sending multiple messages see
37244 * g_socket_send_messages(); for easier use, see
37245 * g_socket_send() and g_socket_send_to().
37247 * If @address is %NULL then the message is sent to the default receiver
37248 * (set by g_socket_connect()).
37250 * @vectors must point to an array of #GOutputVector structs and
37251 * @num_vectors must be the length of this array. (If @num_vectors is -1,
37252 * then @vectors is assumed to be terminated by a #GOutputVector with a
37253 * %NULL buffer pointer.) The #GOutputVector structs describe the buffers
37254 * that the sent data will be gathered from. Using multiple
37255 * #GOutputVectors is more memory-efficient than manually copying
37256 * data from multiple sources into a single buffer, and more
37257 * network-efficient than making multiple calls to g_socket_send().
37259 * @messages, if non-%NULL, is taken to point to an array of @num_messages
37260 * #GSocketControlMessage instances. These correspond to the control
37261 * messages to be sent on the socket.
37262 * If @num_messages is -1 then @messages is treated as a %NULL-terminated
37265 * @flags modify how the message is sent. The commonly available arguments
37266 * for this are available in the #GSocketMsgFlags enum, but the
37267 * values there are the same as the system values, and the flags
37268 * are passed in as-is, so you can pass in system-specific flags too.
37270 * If the socket is in blocking mode the call will block until there is
37271 * space for the data in the socket queue. If there is no space available
37272 * and the socket is in non-blocking mode a %G_IO_ERROR_WOULD_BLOCK error
37273 * will be returned. To be notified when space is available, wait for the
37274 * %G_IO_OUT condition. Note though that you may still receive
37275 * %G_IO_ERROR_WOULD_BLOCK from g_socket_send() even if you were previously
37276 * notified of a %G_IO_OUT condition. (On Windows in particular, this is
37277 * very common due to the way the underlying APIs work.)
37279 * The sum of the sizes of each #GOutputVector in vectors must not be
37280 * greater than %G_MAXSSIZE. If the message can be larger than this,
37281 * then it is mandatory to use the g_socket_send_message_with_timeout()
37284 * On error -1 is returned and @error is set accordingly.
37286 * Returns: Number of bytes written (which may be less than @size), or -1
37293 * g_socket_send_message_with_timeout:
37294 * @socket: a #GSocket
37295 * @address: (nullable): a #GSocketAddress, or %NULL
37296 * @vectors: (array length=num_vectors): an array of #GOutputVector structs
37297 * @num_vectors: the number of elements in @vectors, or -1
37298 * @messages: (array length=num_messages) (nullable): a pointer to an
37299 * array of #GSocketControlMessages, or %NULL.
37300 * @num_messages: number of elements in @messages, or -1.
37301 * @flags: an int containing #GSocketMsgFlags flags, which may additionally
37302 * contain [other platform specific flags](http://man7.org/linux/man-pages/man2/recv.2.html)
37303 * @timeout_us: the maximum time (in microseconds) to wait, or -1
37304 * @bytes_written: (out) (optional): location to store the number of bytes that were written to the socket
37305 * @cancellable: (nullable): a %GCancellable or %NULL
37306 * @error: #GError for error reporting, or %NULL to ignore.
37308 * This behaves exactly the same as g_socket_send_message(), except that
37309 * the choice of timeout behavior is determined by the @timeout_us argument
37310 * rather than by @socket's properties.
37312 * On error %G_POLLABLE_RETURN_FAILED is returned and @error is set accordingly, or
37313 * if the socket is currently not writable %G_POLLABLE_RETURN_WOULD_BLOCK is
37314 * returned. @bytes_written will contain 0 in both cases.
37316 * Returns: %G_POLLABLE_RETURN_OK if all data was successfully written,
37317 * %G_POLLABLE_RETURN_WOULD_BLOCK if the socket is currently not writable, or
37318 * %G_POLLABLE_RETURN_FAILED if an error happened and @error is set.
37324 * g_socket_send_messages:
37325 * @socket: a #GSocket
37326 * @messages: (array length=num_messages): an array of #GOutputMessage structs
37327 * @num_messages: the number of elements in @messages
37328 * @flags: an int containing #GSocketMsgFlags flags, which may additionally
37329 * contain [other platform specific flags](http://man7.org/linux/man-pages/man2/recv.2.html)
37330 * @cancellable: (nullable): a %GCancellable or %NULL
37331 * @error: #GError for error reporting, or %NULL to ignore.
37333 * Send multiple data messages from @socket in one go. This is the most
37334 * complicated and fully-featured version of this call. For easier use, see
37335 * g_socket_send(), g_socket_send_to(), and g_socket_send_message().
37337 * @messages must point to an array of #GOutputMessage structs and
37338 * @num_messages must be the length of this array. Each #GOutputMessage
37339 * contains an address to send the data to, and a pointer to an array of
37340 * #GOutputVector structs to describe the buffers that the data to be sent
37341 * for each message will be gathered from. Using multiple #GOutputVectors is
37342 * more memory-efficient than manually copying data from multiple sources
37343 * into a single buffer, and more network-efficient than making multiple
37344 * calls to g_socket_send(). Sending multiple messages in one go avoids the
37345 * overhead of making a lot of syscalls in scenarios where a lot of data
37346 * packets need to be sent (e.g. high-bandwidth video streaming over RTP/UDP),
37347 * or where the same data needs to be sent to multiple recipients.
37349 * @flags modify how the message is sent. The commonly available arguments
37350 * for this are available in the #GSocketMsgFlags enum, but the
37351 * values there are the same as the system values, and the flags
37352 * are passed in as-is, so you can pass in system-specific flags too.
37354 * If the socket is in blocking mode the call will block until there is
37355 * space for all the data in the socket queue. If there is no space available
37356 * and the socket is in non-blocking mode a %G_IO_ERROR_WOULD_BLOCK error
37357 * will be returned if no data was written at all, otherwise the number of
37358 * messages sent will be returned. To be notified when space is available,
37359 * wait for the %G_IO_OUT condition. Note though that you may still receive
37360 * %G_IO_ERROR_WOULD_BLOCK from g_socket_send() even if you were previously
37361 * notified of a %G_IO_OUT condition. (On Windows in particular, this is
37362 * very common due to the way the underlying APIs work.)
37364 * On error -1 is returned and @error is set accordingly. An error will only
37365 * be returned if zero messages could be sent; otherwise the number of messages
37366 * successfully sent before the error will be returned.
37368 * Returns: number of messages sent, or -1 on error. Note that the number of
37369 * messages sent may be smaller than @num_messages if the socket is
37370 * non-blocking or if @num_messages was larger than UIO_MAXIOV (1024),
37371 * in which case the caller may re-try to send the remaining messages.
37377 * g_socket_send_to:
37378 * @socket: a #GSocket
37379 * @address: (nullable): a #GSocketAddress, or %NULL
37380 * @buffer: (array length=size) (element-type guint8): the buffer
37381 * containing the data to send.
37382 * @size: the number of bytes to send
37383 * @cancellable: (nullable): a %GCancellable or %NULL
37384 * @error: #GError for error reporting, or %NULL to ignore.
37386 * Tries to send @size bytes from @buffer to @address. If @address is
37387 * %NULL then the message is sent to the default receiver (set by
37388 * g_socket_connect()).
37390 * See g_socket_send() for additional information.
37392 * Returns: Number of bytes written (which may be less than @size), or -1
37399 * g_socket_send_with_blocking:
37400 * @socket: a #GSocket
37401 * @buffer: (array length=size) (element-type guint8): the buffer
37402 * containing the data to send.
37403 * @size: the number of bytes to send
37404 * @blocking: whether to do blocking or non-blocking I/O
37405 * @cancellable: (nullable): a %GCancellable or %NULL
37406 * @error: #GError for error reporting, or %NULL to ignore.
37408 * This behaves exactly the same as g_socket_send(), except that
37409 * the choice of blocking or non-blocking behavior is determined by
37410 * the @blocking argument rather than by @socket's properties.
37412 * Returns: Number of bytes written (which may be less than @size), or -1
37419 * g_socket_service_is_active:
37420 * @service: a #GSocketService
37422 * Check whether the service is active or not. An active
37423 * service will accept new clients that connect, while
37424 * a non-active service will let connecting clients queue
37425 * up until the service is started.
37427 * Returns: %TRUE if the service is active, %FALSE otherwise
37433 * g_socket_service_new:
37435 * Creates a new #GSocketService with no sockets to listen for.
37436 * New listeners can be added with e.g. g_socket_listener_add_address()
37437 * or g_socket_listener_add_inet_port().
37439 * New services are created active, there is no need to call
37440 * g_socket_service_start(), unless g_socket_service_stop() has been
37443 * Returns: a new #GSocketService.
37449 * g_socket_service_start:
37450 * @service: a #GSocketService
37452 * Restarts the service, i.e. start accepting connections
37453 * from the added sockets when the mainloop runs. This only needs
37454 * to be called after the service has been stopped from
37455 * g_socket_service_stop().
37457 * This call is thread-safe, so it may be called from a thread
37458 * handling an incoming client request.
37465 * g_socket_service_stop:
37466 * @service: a #GSocketService
37468 * Stops the service, i.e. stops accepting connections
37469 * from the added sockets when the mainloop runs.
37471 * This call is thread-safe, so it may be called from a thread
37472 * handling an incoming client request.
37474 * Note that this only stops accepting new connections; it does not
37475 * close the listening sockets, and you can call
37476 * g_socket_service_start() again later to begin listening again. To
37477 * close the listening sockets, call g_socket_listener_close(). (This
37478 * will happen automatically when the #GSocketService is finalized.)
37480 * This must be called before calling g_socket_listener_close() as
37481 * the socket service will start accepting connections immediately
37482 * when a new socket is added.
37489 * g_socket_set_blocking:
37490 * @socket: a #GSocket.
37491 * @blocking: Whether to use blocking I/O or not.
37493 * Sets the blocking mode of the socket. In blocking mode
37494 * all operations (which don’t take an explicit blocking parameter) block until
37495 * they succeed or there is an error. In
37496 * non-blocking mode all functions return results immediately or
37497 * with a %G_IO_ERROR_WOULD_BLOCK error.
37499 * All sockets are created in blocking mode. However, note that the
37500 * platform level socket is always non-blocking, and blocking mode
37501 * is a GSocket level feature.
37508 * g_socket_set_broadcast:
37509 * @socket: a #GSocket.
37510 * @broadcast: whether @socket should allow sending to broadcast
37513 * Sets whether @socket should allow sending to broadcast addresses.
37514 * This is %FALSE by default.
37521 * g_socket_set_keepalive:
37522 * @socket: a #GSocket.
37523 * @keepalive: Value for the keepalive flag
37525 * Sets or unsets the %SO_KEEPALIVE flag on the underlying socket. When
37526 * this flag is set on a socket, the system will attempt to verify that the
37527 * remote socket endpoint is still present if a sufficiently long period of
37528 * time passes with no data being exchanged. If the system is unable to
37529 * verify the presence of the remote endpoint, it will automatically close
37532 * This option is only functional on certain kinds of sockets. (Notably,
37533 * %G_SOCKET_PROTOCOL_TCP sockets.)
37535 * The exact time between pings is system- and protocol-dependent, but will
37536 * normally be at least two hours. Most commonly, you would set this flag
37537 * on a server socket if you want to allow clients to remain idle for long
37538 * periods of time, but also want to ensure that connections are eventually
37539 * garbage-collected if clients crash or become unreachable.
37546 * g_socket_set_listen_backlog:
37547 * @socket: a #GSocket.
37548 * @backlog: the maximum number of pending connections.
37550 * Sets the maximum number of outstanding connections allowed
37551 * when listening on this socket. If more clients than this are
37552 * connecting to the socket and the application is not handling them
37553 * on time then the new connections will be refused.
37555 * Note that this must be called before g_socket_listen() and has no
37556 * effect if called after that.
37563 * g_socket_set_multicast_loopback:
37564 * @socket: a #GSocket.
37565 * @loopback: whether @socket should receive messages sent to its
37566 * multicast groups from the local host
37568 * Sets whether outgoing multicast packets will be received by sockets
37569 * listening on that multicast address on the same host. This is %TRUE
37577 * g_socket_set_multicast_ttl:
37578 * @socket: a #GSocket.
37579 * @ttl: the time-to-live value for all multicast datagrams on @socket
37581 * Sets the time-to-live for outgoing multicast datagrams on @socket.
37582 * By default, this is 1, meaning that multicast packets will not leave
37583 * the local network.
37590 * g_socket_set_option:
37591 * @socket: a #GSocket
37592 * @level: the "API level" of the option (eg, `SOL_SOCKET`)
37593 * @optname: the "name" of the option (eg, `SO_BROADCAST`)
37594 * @value: the value to set the option to
37595 * @error: #GError for error reporting, or %NULL to ignore.
37597 * Sets the value of an integer-valued option on @socket, as with
37598 * setsockopt(). (If you need to set a non-integer-valued option,
37599 * you will need to call setsockopt() directly.)
37601 * The [<gio/gnetworking.h>][gio-gnetworking.h]
37602 * header pulls in system headers that will define most of the
37603 * standard/portable socket options. For unusual socket protocols or
37604 * platform-dependent options, you may need to include additional
37607 * Returns: success or failure. On failure, @error will be set, and
37608 * the system error value (`errno` or WSAGetLastError()) will still
37609 * be set to the result of the setsockopt() call.
37615 * g_socket_set_timeout:
37616 * @socket: a #GSocket.
37617 * @timeout: the timeout for @socket, in seconds, or 0 for none
37619 * Sets the time in seconds after which I/O operations on @socket will
37620 * time out if they have not yet completed.
37622 * On a blocking socket, this means that any blocking #GSocket
37623 * operation will time out after @timeout seconds of inactivity,
37624 * returning %G_IO_ERROR_TIMED_OUT.
37626 * On a non-blocking socket, calls to g_socket_condition_wait() will
37627 * also fail with %G_IO_ERROR_TIMED_OUT after the given time. Sources
37628 * created with g_socket_create_source() will trigger after
37629 * @timeout seconds of inactivity, with the requested condition
37630 * set, at which point calling g_socket_receive(), g_socket_send(),
37631 * g_socket_check_connect_result(), etc, will fail with
37632 * %G_IO_ERROR_TIMED_OUT.
37634 * If @timeout is 0 (the default), operations will never time out
37637 * Note that if an I/O operation is interrupted by a signal, this may
37638 * cause the timeout to be reset.
37645 * g_socket_set_ttl:
37646 * @socket: a #GSocket.
37647 * @ttl: the time-to-live value for all unicast packets on @socket
37649 * Sets the time-to-live for outgoing unicast packets on @socket.
37650 * By default the platform-specific default value is used.
37657 * g_socket_shutdown:
37658 * @socket: a #GSocket
37659 * @shutdown_read: whether to shut down the read side
37660 * @shutdown_write: whether to shut down the write side
37661 * @error: #GError for error reporting, or %NULL to ignore.
37663 * Shut down part or all of a full-duplex connection.
37665 * If @shutdown_read is %TRUE then the receiving side of the connection
37666 * is shut down, and further reading is disallowed.
37668 * If @shutdown_write is %TRUE then the sending side of the connection
37669 * is shut down, and further writing is disallowed.
37671 * It is allowed for both @shutdown_read and @shutdown_write to be %TRUE.
37673 * One example where it is useful to shut down only one side of a connection is
37674 * graceful disconnect for TCP connections where you close the sending side,
37675 * then wait for the other side to close the connection, thus ensuring that the
37676 * other side saw all sent data.
37678 * Returns: %TRUE on success, %FALSE on error
37684 * g_socket_speaks_ipv4:
37685 * @socket: a #GSocket
37687 * Checks if a socket is capable of speaking IPv4.
37689 * IPv4 sockets are capable of speaking IPv4. On some operating systems
37690 * and under some combinations of circumstances IPv6 sockets are also
37691 * capable of speaking IPv4. See RFC 3493 section 3.7 for more
37694 * No other types of sockets are currently considered as being capable
37695 * of speaking IPv4.
37697 * Returns: %TRUE if this socket can be used with IPv4.
37703 * g_srv_target_copy:
37704 * @target: a #GSrvTarget
37708 * Returns: a copy of @target
37714 * g_srv_target_free:
37715 * @target: a #GSrvTarget
37724 * g_srv_target_get_hostname:
37725 * @target: a #GSrvTarget
37727 * Gets @target's hostname (in ASCII form; if you are going to present
37728 * this to the user, you should use g_hostname_is_ascii_encoded() to
37729 * check if it contains encoded Unicode segments, and use
37730 * g_hostname_to_unicode() to convert it if it does.)
37732 * Returns: @target's hostname
37738 * g_srv_target_get_port:
37739 * @target: a #GSrvTarget
37741 * Gets @target's port
37743 * Returns: @target's port
37749 * g_srv_target_get_priority:
37750 * @target: a #GSrvTarget
37752 * Gets @target's priority. You should not need to look at this;
37753 * #GResolver already sorts the targets according to the algorithm in
37756 * Returns: @target's priority
37762 * g_srv_target_get_weight:
37763 * @target: a #GSrvTarget
37765 * Gets @target's weight. You should not need to look at this;
37766 * #GResolver already sorts the targets according to the algorithm in
37769 * Returns: @target's weight
37775 * g_srv_target_list_sort: (skip)
37776 * @targets: a #GList of #GSrvTarget
37778 * Sorts @targets in place according to the algorithm in RFC 2782.
37780 * Returns: (transfer full): the head of the sorted list.
37786 * g_srv_target_new:
37787 * @hostname: the host that the service is running on
37788 * @port: the port that the service is running on
37789 * @priority: the target's priority
37790 * @weight: the target's weight
37792 * Creates a new #GSrvTarget with the given parameters.
37794 * You should not need to use this; normally #GSrvTargets are
37795 * created by #GResolver.
37797 * Returns: a new #GSrvTarget.
37803 * g_static_resource_fini:
37804 * @static_resource: pointer to a static #GStaticResource
37806 * Finalized a GResource initialized by g_static_resource_init().
37808 * This is normally used by code generated by
37809 * [glib-compile-resources][glib-compile-resources]
37810 * and is not typically used by other code.
37817 * g_static_resource_get_resource:
37818 * @static_resource: pointer to a static #GStaticResource
37820 * Gets the GResource that was registered by a call to g_static_resource_init().
37822 * This is normally used by code generated by
37823 * [glib-compile-resources][glib-compile-resources]
37824 * and is not typically used by other code.
37826 * Returns: (transfer none): a #GResource
37832 * g_static_resource_init:
37833 * @static_resource: pointer to a static #GStaticResource
37835 * Initializes a GResource from static data using a
37838 * This is normally used by code generated by
37839 * [glib-compile-resources][glib-compile-resources]
37840 * and is not typically used by other code.
37847 * g_subprocess_communicate:
37848 * @subprocess: a #GSubprocess
37849 * @stdin_buf: (nullable): data to send to the stdin of the subprocess, or %NULL
37850 * @cancellable: a #GCancellable
37851 * @stdout_buf: (out) (nullable) (optional) (transfer full): data read from the subprocess stdout
37852 * @stderr_buf: (out) (nullable) (optional) (transfer full): data read from the subprocess stderr
37853 * @error: a pointer to a %NULL #GError pointer, or %NULL
37855 * Communicate with the subprocess until it terminates, and all input
37856 * and output has been completed.
37858 * If @stdin_buf is given, the subprocess must have been created with
37859 * %G_SUBPROCESS_FLAGS_STDIN_PIPE. The given data is fed to the
37860 * stdin of the subprocess and the pipe is closed (ie: EOF).
37862 * At the same time (as not to cause blocking when dealing with large
37863 * amounts of data), if %G_SUBPROCESS_FLAGS_STDOUT_PIPE or
37864 * %G_SUBPROCESS_FLAGS_STDERR_PIPE were used, reads from those
37865 * streams. The data that was read is returned in @stdout and/or
37868 * If the subprocess was created with %G_SUBPROCESS_FLAGS_STDOUT_PIPE,
37869 * @stdout_buf will contain the data read from stdout. Otherwise, for
37870 * subprocesses not created with %G_SUBPROCESS_FLAGS_STDOUT_PIPE,
37871 * @stdout_buf will be set to %NULL. Similar provisions apply to
37872 * @stderr_buf and %G_SUBPROCESS_FLAGS_STDERR_PIPE.
37874 * As usual, any output variable may be given as %NULL to ignore it.
37876 * If you desire the stdout and stderr data to be interleaved, create
37877 * the subprocess with %G_SUBPROCESS_FLAGS_STDOUT_PIPE and
37878 * %G_SUBPROCESS_FLAGS_STDERR_MERGE. The merged result will be returned
37879 * in @stdout_buf and @stderr_buf will be set to %NULL.
37881 * In case of any error (including cancellation), %FALSE will be
37882 * returned with @error set. Some or all of the stdin data may have
37883 * been written. Any stdout or stderr data that has been read will be
37884 * discarded. None of the out variables (aside from @error) will have
37885 * been set to anything in particular and should not be inspected.
37887 * In the case that %TRUE is returned, the subprocess has exited and the
37888 * exit status inspection APIs (eg: g_subprocess_get_if_exited(),
37889 * g_subprocess_get_exit_status()) may be used.
37891 * You should not attempt to use any of the subprocess pipes after
37892 * starting this function, since they may be left in strange states,
37893 * even if the operation was cancelled. You should especially not
37894 * attempt to interact with the pipes while the operation is in progress
37895 * (either from another thread or if using the asynchronous version).
37897 * Returns: %TRUE if successful
37903 * g_subprocess_communicate_async:
37904 * @subprocess: Self
37905 * @stdin_buf: (nullable): Input data, or %NULL
37906 * @cancellable: (nullable): Cancellable
37907 * @callback: Callback
37908 * @user_data: User data
37910 * Asynchronous version of g_subprocess_communicate(). Complete
37911 * invocation with g_subprocess_communicate_finish().
37916 * g_subprocess_communicate_finish:
37917 * @subprocess: Self
37919 * @stdout_buf: (out) (nullable) (optional) (transfer full): Return location for stdout data
37920 * @stderr_buf: (out) (nullable) (optional) (transfer full): Return location for stderr data
37923 * Complete an invocation of g_subprocess_communicate_async().
37928 * g_subprocess_communicate_utf8:
37929 * @subprocess: a #GSubprocess
37930 * @stdin_buf: (nullable): data to send to the stdin of the subprocess, or %NULL
37931 * @cancellable: a #GCancellable
37932 * @stdout_buf: (out) (nullable) (optional) (transfer full): data read from the subprocess stdout
37933 * @stderr_buf: (out) (nullable) (optional) (transfer full): data read from the subprocess stderr
37934 * @error: a pointer to a %NULL #GError pointer, or %NULL
37936 * Like g_subprocess_communicate(), but validates the output of the
37937 * process as UTF-8, and returns it as a regular NUL terminated string.
37939 * On error, @stdout_buf and @stderr_buf will be set to undefined values and
37940 * should not be used.
37945 * g_subprocess_communicate_utf8_async:
37946 * @subprocess: Self
37947 * @stdin_buf: (nullable): Input data, or %NULL
37948 * @cancellable: Cancellable
37949 * @callback: Callback
37950 * @user_data: User data
37952 * Asynchronous version of g_subprocess_communicate_utf8(). Complete
37953 * invocation with g_subprocess_communicate_utf8_finish().
37958 * g_subprocess_communicate_utf8_finish:
37959 * @subprocess: Self
37961 * @stdout_buf: (out) (nullable) (optional) (transfer full): Return location for stdout data
37962 * @stderr_buf: (out) (nullable) (optional) (transfer full): Return location for stderr data
37965 * Complete an invocation of g_subprocess_communicate_utf8_async().
37970 * g_subprocess_force_exit:
37971 * @subprocess: a #GSubprocess
37973 * Use an operating-system specific method to attempt an immediate,
37974 * forceful termination of the process. There is no mechanism to
37975 * determine whether or not the request itself was successful;
37976 * however, you can use g_subprocess_wait() to monitor the status of
37977 * the process after calling this function.
37979 * On Unix, this function sends %SIGKILL.
37986 * g_subprocess_get_exit_status:
37987 * @subprocess: a #GSubprocess
37989 * Check the exit status of the subprocess, given that it exited
37990 * normally. This is the value passed to the exit() system call or the
37991 * return value from main.
37993 * This is equivalent to the system WEXITSTATUS macro.
37995 * It is an error to call this function before g_subprocess_wait() and
37996 * unless g_subprocess_get_if_exited() returned %TRUE.
37998 * Returns: the exit status
38004 * g_subprocess_get_identifier:
38005 * @subprocess: a #GSubprocess
38007 * On UNIX, returns the process ID as a decimal string.
38008 * On Windows, returns the result of GetProcessId() also as a string.
38009 * If the subprocess has terminated, this will return %NULL.
38011 * Returns: (nullable): the subprocess identifier, or %NULL if the subprocess
38018 * g_subprocess_get_if_exited:
38019 * @subprocess: a #GSubprocess
38021 * Check if the given subprocess exited normally (ie: by way of exit()
38022 * or return from main()).
38024 * This is equivalent to the system WIFEXITED macro.
38026 * It is an error to call this function before g_subprocess_wait() has
38029 * Returns: %TRUE if the case of a normal exit
38035 * g_subprocess_get_if_signaled:
38036 * @subprocess: a #GSubprocess
38038 * Check if the given subprocess terminated in response to a signal.
38040 * This is equivalent to the system WIFSIGNALED macro.
38042 * It is an error to call this function before g_subprocess_wait() has
38045 * Returns: %TRUE if the case of termination due to a signal
38051 * g_subprocess_get_status:
38052 * @subprocess: a #GSubprocess
38054 * Gets the raw status code of the process, as from waitpid().
38056 * This value has no particular meaning, but it can be used with the
38057 * macros defined by the system headers such as WIFEXITED. It can also
38058 * be used with g_spawn_check_wait_status().
38060 * It is more likely that you want to use g_subprocess_get_if_exited()
38061 * followed by g_subprocess_get_exit_status().
38063 * It is an error to call this function before g_subprocess_wait() has
38066 * Returns: the (meaningless) waitpid() exit status from the kernel
38072 * g_subprocess_get_stderr_pipe:
38073 * @subprocess: a #GSubprocess
38075 * Gets the #GInputStream from which to read the stderr output of
38078 * The process must have been created with %G_SUBPROCESS_FLAGS_STDERR_PIPE,
38079 * otherwise %NULL will be returned.
38081 * Returns: (nullable) (transfer none): the stderr pipe
38087 * g_subprocess_get_stdin_pipe:
38088 * @subprocess: a #GSubprocess
38090 * Gets the #GOutputStream that you can write to in order to give data
38091 * to the stdin of @subprocess.
38093 * The process must have been created with %G_SUBPROCESS_FLAGS_STDIN_PIPE and
38094 * not %G_SUBPROCESS_FLAGS_STDIN_INHERIT, otherwise %NULL will be returned.
38096 * Returns: (nullable) (transfer none): the stdout pipe
38102 * g_subprocess_get_stdout_pipe:
38103 * @subprocess: a #GSubprocess
38105 * Gets the #GInputStream from which to read the stdout output of
38108 * The process must have been created with %G_SUBPROCESS_FLAGS_STDOUT_PIPE,
38109 * otherwise %NULL will be returned.
38111 * Returns: (nullable) (transfer none): the stdout pipe
38117 * g_subprocess_get_successful:
38118 * @subprocess: a #GSubprocess
38120 * Checks if the process was "successful". A process is considered
38121 * successful if it exited cleanly with an exit status of 0, either by
38122 * way of the exit() system call or return from main().
38124 * It is an error to call this function before g_subprocess_wait() has
38127 * Returns: %TRUE if the process exited cleanly with a exit status of 0
38133 * g_subprocess_get_term_sig:
38134 * @subprocess: a #GSubprocess
38136 * Get the signal number that caused the subprocess to terminate, given
38137 * that it terminated due to a signal.
38139 * This is equivalent to the system WTERMSIG macro.
38141 * It is an error to call this function before g_subprocess_wait() and
38142 * unless g_subprocess_get_if_signaled() returned %TRUE.
38144 * Returns: the signal causing termination
38150 * g_subprocess_launcher_close:
38151 * @self: a #GSubprocessLauncher
38153 * Closes all the file descriptors previously passed to the object with
38154 * g_subprocess_launcher_take_fd(), g_subprocess_launcher_take_stderr_fd(), etc.
38156 * After calling this method, any subsequent calls to g_subprocess_launcher_spawn() or g_subprocess_launcher_spawnv() will
38157 * return %G_IO_ERROR_CLOSED. This method is idempotent if
38158 * called more than once.
38160 * This function is called automatically when the #GSubprocessLauncher
38161 * is disposed, but is provided separately so that garbage collected
38162 * language bindings can call it earlier to guarantee when FDs are closed.
38169 * g_subprocess_launcher_getenv:
38170 * @self: a #GSubprocessLauncher
38171 * @variable: (type filename): the environment variable to get
38173 * Returns the value of the environment variable @variable in the
38174 * environment of processes launched from this launcher.
38176 * On UNIX, the returned string can be an arbitrary byte string.
38177 * On Windows, it will be UTF-8.
38179 * Returns: (nullable) (type filename): the value of the environment variable,
38186 * g_subprocess_launcher_new:
38187 * @flags: #GSubprocessFlags
38189 * Creates a new #GSubprocessLauncher.
38191 * The launcher is created with the default options. A copy of the
38192 * environment of the calling process is made at the time of this call
38193 * and will be used as the environment that the process is launched in.
38200 * g_subprocess_launcher_set_child_setup: (skip)
38201 * @self: a #GSubprocessLauncher
38202 * @child_setup: a #GSpawnChildSetupFunc to use as the child setup function
38203 * @user_data: user data for @child_setup
38204 * @destroy_notify: a #GDestroyNotify for @user_data
38206 * Sets up a child setup function.
38208 * The child setup function will be called after fork() but before
38209 * exec() on the child's side.
38211 * @destroy_notify will not be automatically called on the child's side
38212 * of the fork(). It will only be called when the last reference on the
38213 * #GSubprocessLauncher is dropped or when a new child setup function is
38216 * %NULL can be given as @child_setup to disable the functionality.
38218 * Child setup functions are only available on UNIX.
38225 * g_subprocess_launcher_set_cwd:
38226 * @self: a #GSubprocessLauncher
38227 * @cwd: (type filename): the cwd for launched processes
38229 * Sets the current working directory that processes will be launched
38232 * By default processes are launched with the current working directory
38233 * of the launching process at the time of launch.
38240 * g_subprocess_launcher_set_environ:
38241 * @self: a #GSubprocessLauncher
38242 * @env: (array zero-terminated=1) (element-type filename) (transfer none):
38243 * the replacement environment
38245 * Replace the entire environment of processes launched from this
38246 * launcher with the given 'environ' variable.
38248 * Typically you will build this variable by using g_listenv() to copy
38249 * the process 'environ' and using the functions g_environ_setenv(),
38250 * g_environ_unsetenv(), etc.
38252 * As an alternative, you can use g_subprocess_launcher_setenv(),
38253 * g_subprocess_launcher_unsetenv(), etc.
38255 * Pass an empty array to set an empty environment. Pass %NULL to inherit the
38256 * parent process’ environment. As of GLib 2.54, the parent process’ environment
38257 * will be copied when g_subprocess_launcher_set_environ() is called.
38258 * Previously, it was copied when the subprocess was executed. This means the
38259 * copied environment may now be modified (using g_subprocess_launcher_setenv(),
38260 * etc.) before launching the subprocess.
38262 * On UNIX, all strings in this array can be arbitrary byte strings.
38263 * On Windows, they should be in UTF-8.
38270 * g_subprocess_launcher_set_flags:
38271 * @self: a #GSubprocessLauncher
38272 * @flags: #GSubprocessFlags
38274 * Sets the flags on the launcher.
38276 * The default flags are %G_SUBPROCESS_FLAGS_NONE.
38278 * You may not set flags that specify conflicting options for how to
38279 * handle a particular stdio stream (eg: specifying both
38280 * %G_SUBPROCESS_FLAGS_STDIN_PIPE and
38281 * %G_SUBPROCESS_FLAGS_STDIN_INHERIT).
38283 * You may also not set a flag that conflicts with a previous call to a
38284 * function like g_subprocess_launcher_set_stdin_file_path() or
38285 * g_subprocess_launcher_take_stdout_fd().
38292 * g_subprocess_launcher_set_stderr_file_path:
38293 * @self: a #GSubprocessLauncher
38294 * @path: (type filename) (nullable): a filename or %NULL
38296 * Sets the file path to use as the stderr for spawned processes.
38298 * If @path is %NULL then any previously given path is unset.
38300 * The file will be created or truncated when the process is spawned, as
38301 * would be the case if using '2>' at the shell.
38303 * If you want to send both stdout and stderr to the same file then use
38304 * %G_SUBPROCESS_FLAGS_STDERR_MERGE.
38306 * You may not set a stderr file path if a stderr fd is already set or
38307 * if the launcher flags contain any flags directing stderr elsewhere.
38309 * This feature is only available on UNIX.
38316 * g_subprocess_launcher_set_stdin_file_path:
38317 * @self: a #GSubprocessLauncher
38320 * Sets the file path to use as the stdin for spawned processes.
38322 * If @path is %NULL then any previously given path is unset.
38324 * The file must exist or spawning the process will fail.
38326 * You may not set a stdin file path if a stdin fd is already set or if
38327 * the launcher flags contain any flags directing stdin elsewhere.
38329 * This feature is only available on UNIX.
38336 * g_subprocess_launcher_set_stdout_file_path:
38337 * @self: a #GSubprocessLauncher
38338 * @path: (type filename) (nullable): a filename or %NULL
38340 * Sets the file path to use as the stdout for spawned processes.
38342 * If @path is %NULL then any previously given path is unset.
38344 * The file will be created or truncated when the process is spawned, as
38345 * would be the case if using '>' at the shell.
38347 * You may not set a stdout file path if a stdout fd is already set or
38348 * if the launcher flags contain any flags directing stdout elsewhere.
38350 * This feature is only available on UNIX.
38357 * g_subprocess_launcher_setenv:
38358 * @self: a #GSubprocessLauncher
38359 * @variable: (type filename): the environment variable to set,
38360 * must not contain '='
38361 * @value: (type filename): the new value for the variable
38362 * @overwrite: whether to change the variable if it already exists
38364 * Sets the environment variable @variable in the environment of
38365 * processes launched from this launcher.
38367 * On UNIX, both the variable's name and value can be arbitrary byte
38368 * strings, except that the variable's name cannot contain '='.
38369 * On Windows, they should be in UTF-8.
38376 * g_subprocess_launcher_spawn:
38377 * @self: a #GSubprocessLauncher
38379 * @argv0: Command line arguments
38380 * @...: Continued arguments, %NULL terminated
38382 * Creates a #GSubprocess given a provided varargs list of arguments.
38385 * Returns: (transfer full): A new #GSubprocess, or %NULL on error (and @error will be set)
38390 * g_subprocess_launcher_spawnv:
38391 * @self: a #GSubprocessLauncher
38392 * @argv: (array zero-terminated=1) (element-type filename): Command line arguments
38395 * Creates a #GSubprocess given a provided array of arguments.
38398 * Returns: (transfer full): A new #GSubprocess, or %NULL on error (and @error will be set)
38403 * g_subprocess_launcher_take_fd:
38404 * @self: a #GSubprocessLauncher
38405 * @source_fd: File descriptor in parent process
38406 * @target_fd: Target descriptor for child process
38408 * Transfer an arbitrary file descriptor from parent process to the
38409 * child. This function takes ownership of the @source_fd; it will be closed
38410 * in the parent when @self is freed.
38412 * By default, all file descriptors from the parent will be closed.
38413 * This function allows you to create (for example) a custom `pipe()` or
38414 * `socketpair()` before launching the process, and choose the target
38415 * descriptor in the child.
38417 * An example use case is GNUPG, which has a command line argument
38418 * `--passphrase-fd` providing a file descriptor number where it expects
38419 * the passphrase to be written.
38424 * g_subprocess_launcher_take_stderr_fd:
38425 * @self: a #GSubprocessLauncher
38426 * @fd: a file descriptor, or -1
38428 * Sets the file descriptor to use as the stderr for spawned processes.
38430 * If @fd is -1 then any previously given fd is unset.
38432 * Note that the default behaviour is to pass stderr through to the
38433 * stderr of the parent process.
38435 * The passed @fd belongs to the #GSubprocessLauncher. It will be
38436 * automatically closed when the launcher is finalized. The file
38437 * descriptor will also be closed on the child side when executing the
38440 * You may not set a stderr fd if a stderr file path is already set or
38441 * if the launcher flags contain any flags directing stderr elsewhere.
38443 * This feature is only available on UNIX.
38450 * g_subprocess_launcher_take_stdin_fd:
38451 * @self: a #GSubprocessLauncher
38452 * @fd: a file descriptor, or -1
38454 * Sets the file descriptor to use as the stdin for spawned processes.
38456 * If @fd is -1 then any previously given fd is unset.
38458 * Note that if your intention is to have the stdin of the calling
38459 * process inherited by the child then %G_SUBPROCESS_FLAGS_STDIN_INHERIT
38460 * is a better way to go about doing that.
38462 * The passed @fd is noted but will not be touched in the current
38463 * process. It is therefore necessary that it be kept open by the
38464 * caller until the subprocess is spawned. The file descriptor will
38465 * also not be explicitly closed on the child side, so it must be marked
38466 * O_CLOEXEC if that's what you want.
38468 * You may not set a stdin fd if a stdin file path is already set or if
38469 * the launcher flags contain any flags directing stdin elsewhere.
38471 * This feature is only available on UNIX.
38478 * g_subprocess_launcher_take_stdout_fd:
38479 * @self: a #GSubprocessLauncher
38480 * @fd: a file descriptor, or -1
38482 * Sets the file descriptor to use as the stdout for spawned processes.
38484 * If @fd is -1 then any previously given fd is unset.
38486 * Note that the default behaviour is to pass stdout through to the
38487 * stdout of the parent process.
38489 * The passed @fd is noted but will not be touched in the current
38490 * process. It is therefore necessary that it be kept open by the
38491 * caller until the subprocess is spawned. The file descriptor will
38492 * also not be explicitly closed on the child side, so it must be marked
38493 * O_CLOEXEC if that's what you want.
38495 * You may not set a stdout fd if a stdout file path is already set or
38496 * if the launcher flags contain any flags directing stdout elsewhere.
38498 * This feature is only available on UNIX.
38505 * g_subprocess_launcher_unsetenv:
38506 * @self: a #GSubprocessLauncher
38507 * @variable: (type filename): the environment variable to unset,
38508 * must not contain '='
38510 * Removes the environment variable @variable from the environment of
38511 * processes launched from this launcher.
38513 * On UNIX, the variable's name can be an arbitrary byte string not
38514 * containing '='. On Windows, it should be in UTF-8.
38521 * g_subprocess_new: (skip)
38522 * @flags: flags that define the behaviour of the subprocess
38523 * @error: (nullable): return location for an error, or %NULL
38524 * @argv0: first commandline argument to pass to the subprocess
38525 * @...: more commandline arguments, followed by %NULL
38527 * Create a new process with the given flags and varargs argument
38528 * list. By default, matching the g_spawn_async() defaults, the
38529 * child's stdin will be set to the system null device, and
38530 * stdout/stderr will be inherited from the parent. You can use
38531 * @flags to control this behavior.
38533 * The argument list must be terminated with %NULL.
38535 * Returns: A newly created #GSubprocess, or %NULL on error (and @error
38542 * g_subprocess_newv: (rename-to g_subprocess_new)
38543 * @argv: (array zero-terminated=1) (element-type filename): commandline arguments for the subprocess
38544 * @flags: flags that define the behaviour of the subprocess
38545 * @error: (nullable): return location for an error, or %NULL
38547 * Create a new process with the given flags and argument list.
38549 * The argument list is expected to be %NULL-terminated.
38551 * Returns: A newly created #GSubprocess, or %NULL on error (and @error
38558 * g_subprocess_send_signal:
38559 * @subprocess: a #GSubprocess
38560 * @signal_num: the signal number to send
38562 * Sends the UNIX signal @signal_num to the subprocess, if it is still
38565 * This API is race-free. If the subprocess has terminated, it will not
38568 * This API is not available on Windows.
38575 * g_subprocess_wait:
38576 * @subprocess: a #GSubprocess
38577 * @cancellable: a #GCancellable
38578 * @error: a #GError
38580 * Synchronously wait for the subprocess to terminate.
38582 * After the process terminates you can query its exit status with
38583 * functions such as g_subprocess_get_if_exited() and
38584 * g_subprocess_get_exit_status().
38586 * This function does not fail in the case of the subprocess having
38587 * abnormal termination. See g_subprocess_wait_check() for that.
38589 * Cancelling @cancellable doesn't kill the subprocess. Call
38590 * g_subprocess_force_exit() if it is desirable.
38592 * Returns: %TRUE on success, %FALSE if @cancellable was cancelled
38598 * g_subprocess_wait_async:
38599 * @subprocess: a #GSubprocess
38600 * @cancellable: a #GCancellable, or %NULL
38601 * @callback: a #GAsyncReadyCallback to call when the operation is complete
38602 * @user_data: user_data for @callback
38604 * Wait for the subprocess to terminate.
38606 * This is the asynchronous version of g_subprocess_wait().
38613 * g_subprocess_wait_check:
38614 * @subprocess: a #GSubprocess
38615 * @cancellable: a #GCancellable
38616 * @error: a #GError
38618 * Combines g_subprocess_wait() with g_spawn_check_wait_status().
38620 * Returns: %TRUE on success, %FALSE if process exited abnormally, or
38621 * @cancellable was cancelled
38627 * g_subprocess_wait_check_async:
38628 * @subprocess: a #GSubprocess
38629 * @cancellable: a #GCancellable, or %NULL
38630 * @callback: a #GAsyncReadyCallback to call when the operation is complete
38631 * @user_data: user_data for @callback
38633 * Combines g_subprocess_wait_async() with g_spawn_check_wait_status().
38635 * This is the asynchronous version of g_subprocess_wait_check().
38642 * g_subprocess_wait_check_finish:
38643 * @subprocess: a #GSubprocess
38644 * @result: the #GAsyncResult passed to your #GAsyncReadyCallback
38645 * @error: a pointer to a %NULL #GError, or %NULL
38647 * Collects the result of a previous call to
38648 * g_subprocess_wait_check_async().
38650 * Returns: %TRUE if successful, or %FALSE with @error set
38656 * g_subprocess_wait_finish:
38657 * @subprocess: a #GSubprocess
38658 * @result: the #GAsyncResult passed to your #GAsyncReadyCallback
38659 * @error: a pointer to a %NULL #GError, or %NULL
38661 * Collects the result of a previous call to
38662 * g_subprocess_wait_async().
38664 * Returns: %TRUE if successful, or %FALSE with @error set
38670 * g_task_attach_source:
38672 * @source: the source to attach
38673 * @callback: the callback to invoke when @source triggers
38675 * A utility function for dealing with async operations where you need
38676 * to wait for a #GSource to trigger. Attaches @source to @task's
38677 * #GMainContext with @task's [priority][io-priority], and sets @source's
38678 * callback to @callback, with @task as the callback's `user_data`.
38680 * It will set the @source’s name to the task’s name (as set with
38681 * g_task_set_name()), if one has been set.
38683 * This takes a reference on @task until @source is destroyed.
38690 * g_task_get_cancellable:
38693 * Gets @task's #GCancellable
38695 * Returns: (transfer none): @task's #GCancellable
38701 * g_task_get_check_cancellable:
38702 * @task: the #GTask
38704 * Gets @task's check-cancellable flag. See
38705 * g_task_set_check_cancellable() for more details.
38712 * g_task_get_completed:
38715 * Gets the value of #GTask:completed. This changes from %FALSE to %TRUE after
38716 * the task’s callback is invoked, and will return %FALSE if called from inside
38719 * Returns: %TRUE if the task has completed, %FALSE otherwise.
38725 * g_task_get_context:
38728 * Gets the #GMainContext that @task will return its result in (that
38729 * is, the context that was the
38730 * [thread-default main context][g-main-context-push-thread-default]
38731 * at the point when @task was created).
38733 * This will always return a non-%NULL value, even if the task's
38734 * context is the default #GMainContext.
38736 * Returns: (transfer none): @task's #GMainContext
38745 * Gets @task’s name. See g_task_set_name().
38747 * Returns: (nullable) (transfer none): @task’s name, or %NULL
38753 * g_task_get_priority:
38756 * Gets @task's priority
38758 * Returns: @task's priority
38764 * g_task_get_return_on_cancel:
38765 * @task: the #GTask
38767 * Gets @task's return-on-cancel flag. See
38768 * g_task_set_return_on_cancel() for more details.
38775 * g_task_get_source_object:
38778 * Gets the source object from @task. Like
38779 * g_async_result_get_source_object(), but does not ref the object.
38781 * Returns: (transfer none) (nullable) (type GObject): @task's source object, or %NULL
38787 * g_task_get_source_tag:
38790 * Gets @task's source tag. See g_task_set_source_tag().
38792 * Returns: (transfer none): @task's source tag
38798 * g_task_get_task_data:
38801 * Gets @task's `task_data`.
38803 * Returns: (transfer none): @task's `task_data`.
38809 * g_task_had_error:
38812 * Tests if @task resulted in an error.
38814 * Returns: %TRUE if the task resulted in an error, %FALSE otherwise.
38821 * @result: (type Gio.AsyncResult): A #GAsyncResult
38822 * @source_object: (nullable) (type GObject): the source object
38823 * expected to be associated with the task
38825 * Checks that @result is a #GTask, and that @source_object is its
38826 * source object (or that @source_object is %NULL and @result has no
38827 * source object). This can be used in g_return_if_fail() checks.
38829 * Returns: %TRUE if @result and @source_object are valid, %FALSE
38837 * @source_object: (nullable) (type GObject): the #GObject that owns
38838 * this task, or %NULL.
38839 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
38840 * @callback: (scope async): a #GAsyncReadyCallback.
38841 * @callback_data: (closure): user data passed to @callback.
38843 * Creates a #GTask acting on @source_object, which will eventually be
38844 * used to invoke @callback in the current
38845 * [thread-default main context][g-main-context-push-thread-default].
38847 * Call this in the "start" method of your asynchronous method, and
38848 * pass the #GTask around throughout the asynchronous operation. You
38849 * can use g_task_set_task_data() to attach task-specific data to the
38850 * object, which you can retrieve later via g_task_get_task_data().
38852 * By default, if @cancellable is cancelled, then the return value of
38853 * the task will always be %G_IO_ERROR_CANCELLED, even if the task had
38854 * already completed before the cancellation. This allows for
38855 * simplified handling in cases where cancellation may imply that
38856 * other objects that the task depends on have been destroyed. If you
38857 * do not want this behavior, you can use
38858 * g_task_set_check_cancellable() to change it.
38860 * Returns: a #GTask.
38866 * g_task_propagate_boolean:
38868 * @error: return location for a #GError
38870 * Gets the result of @task as a #gboolean.
38872 * If the task resulted in an error, or was cancelled, then this will
38873 * instead return %FALSE and set @error.
38875 * Since this method transfers ownership of the return value (or
38876 * error) to the caller, you may only call it once.
38878 * Returns: the task result, or %FALSE on error
38884 * g_task_propagate_int:
38886 * @error: return location for a #GError
38888 * Gets the result of @task as an integer (#gssize).
38890 * If the task resulted in an error, or was cancelled, then this will
38891 * instead return -1 and set @error.
38893 * Since this method transfers ownership of the return value (or
38894 * error) to the caller, you may only call it once.
38896 * Returns: the task result, or -1 on error
38902 * g_task_propagate_pointer:
38904 * @error: return location for a #GError
38906 * Gets the result of @task as a pointer, and transfers ownership
38907 * of that value to the caller.
38909 * If the task resulted in an error, or was cancelled, then this will
38910 * instead return %NULL and set @error.
38912 * Since this method transfers ownership of the return value (or
38913 * error) to the caller, you may only call it once.
38915 * Returns: (transfer full): the task result, or %NULL on error
38921 * g_task_propagate_value:
38923 * @value: (out caller-allocates): return location for the #GValue
38924 * @error: return location for a #GError
38926 * Gets the result of @task as a #GValue, and transfers ownership of
38927 * that value to the caller. As with g_task_return_value(), this is
38928 * a generic low-level method; g_task_propagate_pointer() and the like
38929 * will usually be more useful for C code.
38931 * If the task resulted in an error, or was cancelled, then this will
38932 * instead set @error and return %FALSE.
38934 * Since this method transfers ownership of the return value (or
38935 * error) to the caller, you may only call it once.
38937 * Returns: %TRUE if @task succeeded, %FALSE on error.
38943 * g_task_report_error:
38944 * @source_object: (nullable) (type GObject): the #GObject that owns
38945 * this task, or %NULL.
38946 * @callback: (scope async): a #GAsyncReadyCallback.
38947 * @callback_data: (closure): user data passed to @callback.
38948 * @source_tag: an opaque pointer indicating the source of this task
38949 * @error: (transfer full): error to report
38951 * Creates a #GTask and then immediately calls g_task_return_error()
38952 * on it. Use this in the wrapper function of an asynchronous method
38953 * when you want to avoid even calling the virtual method. You can
38954 * then use g_async_result_is_tagged() in the finish method wrapper to
38955 * check if the result there is tagged as having been created by the
38956 * wrapper method, and deal with it appropriately if so.
38958 * See also g_task_report_new_error().
38965 * g_task_report_new_error:
38966 * @source_object: (nullable) (type GObject): the #GObject that owns
38967 * this task, or %NULL.
38968 * @callback: (scope async): a #GAsyncReadyCallback.
38969 * @callback_data: (closure): user data passed to @callback.
38970 * @source_tag: an opaque pointer indicating the source of this task
38971 * @domain: a #GQuark.
38972 * @code: an error code.
38973 * @format: a string with format characters.
38974 * @...: a list of values to insert into @format.
38976 * Creates a #GTask and then immediately calls
38977 * g_task_return_new_error() on it. Use this in the wrapper function
38978 * of an asynchronous method when you want to avoid even calling the
38979 * virtual method. You can then use g_async_result_is_tagged() in the
38980 * finish method wrapper to check if the result there is tagged as
38981 * having been created by the wrapper method, and deal with it
38982 * appropriately if so.
38984 * See also g_task_report_error().
38991 * g_task_return_boolean:
38993 * @result: the #gboolean result of a task function.
38995 * Sets @task's result to @result and completes the task (see
38996 * g_task_return_pointer() for more discussion of exactly what this
39004 * g_task_return_error:
39006 * @error: (transfer full): the #GError result of a task function.
39008 * Sets @task's result to @error (which @task assumes ownership of)
39009 * and completes the task (see g_task_return_pointer() for more
39010 * discussion of exactly what this means).
39012 * Note that since the task takes ownership of @error, and since the
39013 * task may be completed before returning from g_task_return_error(),
39014 * you cannot assume that @error is still valid after calling this.
39015 * Call g_error_copy() on the error if you need to keep a local copy
39018 * See also g_task_return_new_error().
39025 * g_task_return_error_if_cancelled:
39028 * Checks if @task's #GCancellable has been cancelled, and if so, sets
39029 * @task's error accordingly and completes the task (see
39030 * g_task_return_pointer() for more discussion of exactly what this
39033 * Returns: %TRUE if @task has been cancelled, %FALSE if not
39039 * g_task_return_int:
39041 * @result: the integer (#gssize) result of a task function.
39043 * Sets @task's result to @result and completes the task (see
39044 * g_task_return_pointer() for more discussion of exactly what this
39052 * g_task_return_new_error:
39054 * @domain: a #GQuark.
39055 * @code: an error code.
39056 * @format: a string with format characters.
39057 * @...: a list of values to insert into @format.
39059 * Sets @task's result to a new #GError created from @domain, @code,
39060 * @format, and the remaining arguments, and completes the task (see
39061 * g_task_return_pointer() for more discussion of exactly what this
39064 * See also g_task_return_error().
39071 * g_task_return_pointer:
39073 * @result: (nullable) (transfer full): the pointer result of a task
39075 * @result_destroy: (nullable): a #GDestroyNotify function.
39077 * Sets @task's result to @result and completes the task. If @result
39078 * is not %NULL, then @result_destroy will be used to free @result if
39079 * the caller does not take ownership of it with
39080 * g_task_propagate_pointer().
39082 * "Completes the task" means that for an ordinary asynchronous task
39083 * it will either invoke the task's callback, or else queue that
39084 * callback to be invoked in the proper #GMainContext, or in the next
39085 * iteration of the current #GMainContext. For a task run via
39086 * g_task_run_in_thread() or g_task_run_in_thread_sync(), calling this
39087 * method will save @result to be returned to the caller later, but
39088 * the task will not actually be completed until the #GTaskThreadFunc
39091 * Note that since the task may be completed before returning from
39092 * g_task_return_pointer(), you cannot assume that @result is still
39093 * valid after calling this, unless you are still holding another
39101 * g_task_return_value:
39103 * @result: (nullable) (transfer none): the #GValue result of
39106 * Sets @task's result to @result (by copying it) and completes the task.
39108 * If @result is %NULL then a #GValue of type #G_TYPE_POINTER
39109 * with a value of %NULL will be used for the result.
39111 * This is a very generic low-level method intended primarily for use
39112 * by language bindings; for C code, g_task_return_pointer() and the
39113 * like will normally be much easier to use.
39120 * g_task_run_in_thread:
39122 * @task_func: (scope async): a #GTaskThreadFunc
39124 * Runs @task_func in another thread. When @task_func returns, @task's
39125 * #GAsyncReadyCallback will be invoked in @task's #GMainContext.
39127 * This takes a ref on @task until the task completes.
39129 * See #GTaskThreadFunc for more details about how @task_func is handled.
39131 * Although GLib currently rate-limits the tasks queued via
39132 * g_task_run_in_thread(), you should not assume that it will always
39133 * do this. If you have a very large number of tasks to run (several tens of
39134 * tasks), but don't want them to all run at once, you should only queue a
39135 * limited number of them (around ten) at a time.
39142 * g_task_run_in_thread_sync:
39144 * @task_func: (scope async): a #GTaskThreadFunc
39146 * Runs @task_func in another thread, and waits for it to return or be
39147 * cancelled. You can use g_task_propagate_pointer(), etc, afterward
39148 * to get the result of @task_func.
39150 * See #GTaskThreadFunc for more details about how @task_func is handled.
39152 * Normally this is used with tasks created with a %NULL
39153 * `callback`, but note that even if the task does
39154 * have a callback, it will not be invoked when @task_func returns.
39155 * #GTask:completed will be set to %TRUE just before this function returns.
39157 * Although GLib currently rate-limits the tasks queued via
39158 * g_task_run_in_thread_sync(), you should not assume that it will
39159 * always do this. If you have a very large number of tasks to run,
39160 * but don't want them to all run at once, you should only queue a
39161 * limited number of them at a time.
39168 * g_task_set_check_cancellable:
39169 * @task: the #GTask
39170 * @check_cancellable: whether #GTask will check the state of
39171 * its #GCancellable for you.
39173 * Sets or clears @task's check-cancellable flag. If this is %TRUE
39174 * (the default), then g_task_propagate_pointer(), etc, and
39175 * g_task_had_error() will check the task's #GCancellable first, and
39176 * if it has been cancelled, then they will consider the task to have
39177 * returned an "Operation was cancelled" error
39178 * (%G_IO_ERROR_CANCELLED), regardless of any other error or return
39179 * value the task may have had.
39181 * If @check_cancellable is %FALSE, then the #GTask will not check the
39182 * cancellable itself, and it is up to @task's owner to do this (eg,
39183 * via g_task_return_error_if_cancelled()).
39185 * If you are using g_task_set_return_on_cancel() as well, then
39186 * you must leave check-cancellable set %TRUE.
39195 * @name: (nullable): a human readable name for the task, or %NULL to unset it
39197 * Sets @task’s name, used in debugging and profiling. The name defaults to
39200 * The task name should describe in a human readable way what the task does.
39201 * For example, ‘Open file’ or ‘Connect to network host’. It is used to set the
39202 * name of the #GSource used for idle completion of the task.
39204 * This function may only be called before the @task is first used in a thread
39205 * other than the one it was constructed in.
39212 * g_task_set_priority:
39213 * @task: the #GTask
39214 * @priority: the [priority][io-priority] of the request
39216 * Sets @task's priority. If you do not call this, it will default to
39217 * %G_PRIORITY_DEFAULT.
39219 * This will affect the priority of #GSources created with
39220 * g_task_attach_source() and the scheduling of tasks run in threads,
39221 * and can also be explicitly retrieved later via
39222 * g_task_get_priority().
39229 * g_task_set_return_on_cancel:
39230 * @task: the #GTask
39231 * @return_on_cancel: whether the task returns automatically when
39234 * Sets or clears @task's return-on-cancel flag. This is only
39235 * meaningful for tasks run via g_task_run_in_thread() or
39236 * g_task_run_in_thread_sync().
39238 * If @return_on_cancel is %TRUE, then cancelling @task's
39239 * #GCancellable will immediately cause it to return, as though the
39240 * task's #GTaskThreadFunc had called
39241 * g_task_return_error_if_cancelled() and then returned.
39243 * This allows you to create a cancellable wrapper around an
39244 * uninterruptible function. The #GTaskThreadFunc just needs to be
39245 * careful that it does not modify any externally-visible state after
39246 * it has been cancelled. To do that, the thread should call
39247 * g_task_set_return_on_cancel() again to (atomically) set
39248 * return-on-cancel %FALSE before making externally-visible changes;
39249 * if the task gets cancelled before the return-on-cancel flag could
39250 * be changed, g_task_set_return_on_cancel() will indicate this by
39251 * returning %FALSE.
39253 * You can disable and re-enable this flag multiple times if you wish.
39254 * If the task's #GCancellable is cancelled while return-on-cancel is
39255 * %FALSE, then calling g_task_set_return_on_cancel() to set it %TRUE
39256 * again will cause the task to be cancelled at that point.
39258 * If the task's #GCancellable is already cancelled before you call
39259 * g_task_run_in_thread()/g_task_run_in_thread_sync(), then the
39260 * #GTaskThreadFunc will still be run (for consistency), but the task
39261 * will also be completed right away.
39263 * Returns: %TRUE if @task's return-on-cancel flag was changed to
39264 * match @return_on_cancel. %FALSE if @task has already been
39271 * g_task_set_source_tag:
39272 * @task: the #GTask
39273 * @source_tag: an opaque pointer indicating the source of this task
39275 * Sets @task's source tag. You can use this to tag a task return
39276 * value with a particular pointer (usually a pointer to the function
39277 * doing the tagging) and then later check it using
39278 * g_task_get_source_tag() (or g_async_result_is_tagged()) in the
39279 * task's "finish" function, to figure out if the response came from a
39280 * particular place.
39287 * g_task_set_task_data:
39288 * @task: the #GTask
39289 * @task_data: (nullable): task-specific data
39290 * @task_data_destroy: (nullable): #GDestroyNotify for @task_data
39292 * Sets @task's task data (freeing the existing task data, if any).
39299 * g_tcp_connection_get_graceful_disconnect:
39300 * @connection: a #GTcpConnection
39302 * Checks if graceful disconnects are used. See
39303 * g_tcp_connection_set_graceful_disconnect().
39305 * Returns: %TRUE if graceful disconnect is used on close, %FALSE otherwise
39311 * g_tcp_connection_set_graceful_disconnect:
39312 * @connection: a #GTcpConnection
39313 * @graceful_disconnect: Whether to do graceful disconnects or not
39315 * This enables graceful disconnects on close. A graceful disconnect
39316 * means that we signal the receiving end that the connection is terminated
39317 * and wait for it to close the connection before closing the connection.
39319 * A graceful disconnect means that we can be sure that we successfully sent
39320 * all the outstanding data to the other end, or get an error reported.
39321 * However, it also means we have to wait for all the data to reach the
39322 * other side and for it to acknowledge this by closing the socket, which may
39323 * take a while. For this reason it is disabled by default.
39330 * g_tcp_wrapper_connection_get_base_io_stream:
39331 * @conn: a #GTcpWrapperConnection
39333 * Gets @conn's base #GIOStream
39335 * Returns: (transfer none): @conn's base #GIOStream
39340 * g_tcp_wrapper_connection_new:
39341 * @base_io_stream: the #GIOStream to wrap
39342 * @socket: the #GSocket associated with @base_io_stream
39344 * Wraps @base_io_stream and @socket together as a #GSocketConnection.
39346 * Returns: the new #GSocketConnection.
39352 * g_test_dbus_add_service_dir:
39353 * @self: a #GTestDBus
39354 * @path: path to a directory containing .service files
39356 * Add a path where dbus-daemon will look up .service files. This can't be
39357 * called after g_test_dbus_up().
39362 * g_test_dbus_down:
39363 * @self: a #GTestDBus
39365 * Stop the session bus started by g_test_dbus_up().
39367 * This will wait for the singleton returned by g_bus_get() or g_bus_get_sync()
39368 * to be destroyed. This is done to ensure that the next unit test won't get a
39369 * leaked singleton from this test.
39374 * g_test_dbus_get_bus_address:
39375 * @self: a #GTestDBus
39377 * Get the address on which dbus-daemon is running. If g_test_dbus_up() has not
39378 * been called yet, %NULL is returned. This can be used with
39379 * g_dbus_connection_new_for_address().
39381 * Returns: (nullable): the address of the bus, or %NULL.
39386 * g_test_dbus_get_flags:
39387 * @self: a #GTestDBus
39389 * Get the flags of the #GTestDBus object.
39391 * Returns: the value of #GTestDBus:flags property
39397 * @flags: a #GTestDBusFlags
39399 * Create a new #GTestDBus object.
39401 * Returns: (transfer full): a new #GTestDBus.
39406 * g_test_dbus_stop:
39407 * @self: a #GTestDBus
39409 * Stop the session bus started by g_test_dbus_up().
39411 * Unlike g_test_dbus_down(), this won't verify the #GDBusConnection
39412 * singleton returned by g_bus_get() or g_bus_get_sync() is destroyed. Unit
39413 * tests wanting to verify behaviour after the session bus has been stopped
39414 * can use this function but should still call g_test_dbus_down() when done.
39419 * g_test_dbus_unset:
39421 * Unset DISPLAY and DBUS_SESSION_BUS_ADDRESS env variables to ensure the test
39422 * won't use user's session bus.
39424 * This is useful for unit tests that want to verify behaviour when no session
39425 * bus is running. It is not necessary to call this if unit test already calls
39426 * g_test_dbus_up() before acquiring the session bus.
39432 * @self: a #GTestDBus
39434 * Start a dbus-daemon instance and set DBUS_SESSION_BUS_ADDRESS. After this
39435 * call, it is safe for unit tests to start sending messages on the session bus.
39437 * If this function is called from setup callback of g_test_add(),
39438 * g_test_dbus_down() must be called in its teardown callback.
39440 * If this function is called from unit test's main(), then g_test_dbus_down()
39441 * must be called after g_test_run().
39446 * g_themed_icon_append_name:
39447 * @icon: a #GThemedIcon
39448 * @iconname: name of icon to append to list of icons from within @icon.
39450 * Append a name to the list of icons from within @icon.
39452 * Note that doing so invalidates the hash computed by prior calls
39453 * to g_icon_hash().
39458 * g_themed_icon_get_names:
39459 * @icon: a #GThemedIcon.
39461 * Gets the names of icons from within @icon.
39463 * Returns: (transfer none): a list of icon names.
39468 * g_themed_icon_new:
39469 * @iconname: a string containing an icon name.
39471 * Creates a new themed icon for @iconname.
39473 * Returns: (transfer full) (type GThemedIcon): a new #GThemedIcon.
39478 * g_themed_icon_new_from_names:
39479 * @iconnames: (array length=len): an array of strings containing icon names.
39480 * @len: the length of the @iconnames array, or -1 if @iconnames is
39483 * Creates a new themed icon for @iconnames.
39485 * Returns: (transfer full) (type GThemedIcon): a new #GThemedIcon
39490 * g_themed_icon_new_with_default_fallbacks:
39491 * @iconname: a string containing an icon name
39493 * Creates a new themed icon for @iconname, and all the names
39494 * that can be created by shortening @iconname at '-' characters.
39496 * In the following example, @icon1 and @icon2 are equivalent:
39497 * |[<!-- language="C" -->
39498 * const char *names[] = {
39499 * "gnome-dev-cdrom-audio",
39500 * "gnome-dev-cdrom",
39505 * icon1 = g_themed_icon_new_from_names (names, 4);
39506 * icon2 = g_themed_icon_new_with_default_fallbacks ("gnome-dev-cdrom-audio");
39509 * Returns: (transfer full) (type GThemedIcon): a new #GThemedIcon.
39514 * g_themed_icon_prepend_name:
39515 * @icon: a #GThemedIcon
39516 * @iconname: name of icon to prepend to list of icons from within @icon.
39518 * Prepend a name to the list of icons from within @icon.
39520 * Note that doing so invalidates the hash computed by prior calls
39521 * to g_icon_hash().
39528 * g_themed_icon_update_names:
39529 * @themed: a #GThemedIcon.
39531 * Update the actual icon name list, based on the requested names (from
39532 * construction, or later added with g_themed_icon_prepend_name() and
39533 * g_themed_icon_append_name()).
39534 * The order of the list matters, indicating priority:
39535 * - The first requested icon is first in priority.
39536 * - If "use-default-fallbacks" is #TRUE, then it is followed by all its
39537 * fallbacks (starting from top to lower context levels).
39538 * - Then next requested icons, and optionally their fallbacks, follow.
39539 * - Finally all the style variants (symbolic or regular, opposite to whatever
39540 * is the requested style) follow in the same order.
39542 * An icon is not added twice in the list if it was previously added.
39544 * For instance, if requested names are:
39545 * [ "some-icon-symbolic", "some-other-icon" ]
39546 * and use-default-fallbacks is TRUE, the final name list shall be:
39547 * [ "some-icon-symbolic", "some-symbolic", "some-other-icon",
39548 * "some-other", "some", "some-icon", "some-other-icon-symbolic",
39549 * "some-other-symbolic" ]
39551 * Returns: (transfer full) (type GThemedIcon): a new #GThemedIcon
39556 * g_threaded_socket_service_new:
39557 * @max_threads: the maximal number of threads to execute concurrently
39558 * handling incoming clients, -1 means no limit
39560 * Creates a new #GThreadedSocketService with no listeners. Listeners
39561 * must be added with one of the #GSocketListener "add" methods.
39563 * Returns: a new #GSocketService.
39569 * g_tls_backend_get_certificate_type:
39570 * @backend: the #GTlsBackend
39572 * Gets the #GType of @backend's #GTlsCertificate implementation.
39574 * Returns: the #GType of @backend's #GTlsCertificate
39581 * g_tls_backend_get_client_connection_type:
39582 * @backend: the #GTlsBackend
39584 * Gets the #GType of @backend's #GTlsClientConnection implementation.
39586 * Returns: the #GType of @backend's #GTlsClientConnection
39593 * g_tls_backend_get_default:
39595 * Gets the default #GTlsBackend for the system.
39597 * Returns: (not nullable) (transfer none): a #GTlsBackend, which will be a
39598 * dummy object if no TLS backend is available
39604 * g_tls_backend_get_default_database:
39605 * @backend: the #GTlsBackend
39607 * Gets the default #GTlsDatabase used to verify TLS connections.
39609 * Returns: (transfer full): the default database, which should be
39610 * unreffed when done.
39616 * g_tls_backend_get_dtls_client_connection_type:
39617 * @backend: the #GTlsBackend
39619 * Gets the #GType of @backend’s #GDtlsClientConnection implementation.
39621 * Returns: the #GType of @backend’s #GDtlsClientConnection
39622 * implementation, or %G_TYPE_INVALID if this backend doesn’t support DTLS.
39628 * g_tls_backend_get_dtls_server_connection_type:
39629 * @backend: the #GTlsBackend
39631 * Gets the #GType of @backend’s #GDtlsServerConnection implementation.
39633 * Returns: the #GType of @backend’s #GDtlsServerConnection
39634 * implementation, or %G_TYPE_INVALID if this backend doesn’t support DTLS.
39640 * g_tls_backend_get_file_database_type:
39641 * @backend: the #GTlsBackend
39643 * Gets the #GType of @backend's #GTlsFileDatabase implementation.
39645 * Returns: the #GType of backend's #GTlsFileDatabase implementation.
39651 * g_tls_backend_get_server_connection_type:
39652 * @backend: the #GTlsBackend
39654 * Gets the #GType of @backend's #GTlsServerConnection implementation.
39656 * Returns: the #GType of @backend's #GTlsServerConnection
39663 * g_tls_backend_set_default_database:
39664 * @backend: the #GTlsBackend
39665 * @database: (nullable): the #GTlsDatabase
39667 * Set the default #GTlsDatabase used to verify TLS connections
39669 * Any subsequent call to g_tls_backend_get_default_database() will return
39670 * the database set in this call. Existing databases and connections are not
39673 * Setting a %NULL default database will reset to using the system default
39674 * database as if g_tls_backend_set_default_database() had never been called.
39681 * g_tls_backend_supports_dtls:
39682 * @backend: the #GTlsBackend
39684 * Checks if DTLS is supported. DTLS support may not be available even if TLS
39685 * support is available, and vice-versa.
39687 * Returns: whether DTLS is supported
39693 * g_tls_backend_supports_tls:
39694 * @backend: the #GTlsBackend
39696 * Checks if TLS is supported; if this returns %FALSE for the default
39697 * #GTlsBackend, it means no "real" TLS backend is available.
39699 * Returns: whether or not TLS is supported
39705 * g_tls_certificate_get_dns_names:
39706 * @cert: a #GTlsCertificate
39708 * Gets the value of #GTlsCertificate:dns-names.
39710 * Returns: (nullable) (element-type GBytes) (transfer container): A #GPtrArray of
39711 * #GBytes elements, or %NULL if it's not available.
39717 * g_tls_certificate_get_ip_addresses:
39718 * @cert: a #GTlsCertificate
39720 * Gets the value of #GTlsCertificate:ip-addresses.
39722 * Returns: (nullable) (element-type GInetAddress) (transfer container): A #GPtrArray
39723 * of #GInetAddress elements, or %NULL if it's not available.
39729 * g_tls_certificate_get_issuer:
39730 * @cert: a #GTlsCertificate
39732 * Gets the #GTlsCertificate representing @cert's issuer, if known
39734 * Returns: (nullable) (transfer none): The certificate of @cert's issuer,
39735 * or %NULL if @cert is self-signed or signed with an unknown
39742 * g_tls_certificate_get_issuer_name:
39743 * @cert: a #GTlsCertificate
39745 * Returns the issuer name from the certificate.
39747 * Returns: (nullable) (transfer full): The issuer name, or %NULL if it's not available.
39753 * g_tls_certificate_get_not_valid_after:
39754 * @cert: a #GTlsCertificate
39756 * Returns the time at which the certificate became or will become invalid.
39758 * Returns: (nullable) (transfer full): The not-valid-after date, or %NULL if it's not available.
39764 * g_tls_certificate_get_not_valid_before:
39765 * @cert: a #GTlsCertificate
39767 * Returns the time at which the certificate became or will become valid.
39769 * Returns: (nullable) (transfer full): The not-valid-before date, or %NULL if it's not available.
39775 * g_tls_certificate_get_subject_name:
39776 * @cert: a #GTlsCertificate
39778 * Returns the subject name from the certificate.
39780 * Returns: (nullable) (transfer full): The subject name, or %NULL if it's not available.
39786 * g_tls_certificate_is_same:
39787 * @cert_one: first certificate to compare
39788 * @cert_two: second certificate to compare
39790 * Check if two #GTlsCertificate objects represent the same certificate.
39791 * The raw DER byte data of the two certificates are checked for equality.
39792 * This has the effect that two certificates may compare equal even if
39793 * their #GTlsCertificate:issuer, #GTlsCertificate:private-key, or
39794 * #GTlsCertificate:private-key-pem properties differ.
39796 * Returns: whether the same or not
39802 * g_tls_certificate_list_new_from_file:
39803 * @file: (type filename): file containing PEM-encoded certificates to import
39804 * @error: #GError for error reporting, or %NULL to ignore.
39806 * Creates one or more #GTlsCertificates from the PEM-encoded
39807 * data in @file. If @file cannot be read or parsed, the function will
39808 * return %NULL and set @error. If @file does not contain any
39809 * PEM-encoded certificates, this will return an empty list and not
39812 * Returns: (element-type Gio.TlsCertificate) (transfer full): a
39813 * #GList containing #GTlsCertificate objects. You must free the list
39814 * and its contents when you are done with it.
39820 * g_tls_certificate_new_from_file:
39821 * @file: (type filename): file containing a PEM-encoded certificate to import
39822 * @error: #GError for error reporting, or %NULL to ignore.
39824 * Creates a #GTlsCertificate from the PEM-encoded data in @file. The
39825 * returned certificate will be the first certificate found in @file. As
39826 * of GLib 2.44, if @file contains more certificates it will try to load
39827 * a certificate chain. All certificates will be verified in the order
39828 * found (top-level certificate should be the last one in the file) and
39829 * the #GTlsCertificate:issuer property of each certificate will be set
39830 * accordingly if the verification succeeds. If any certificate in the
39831 * chain cannot be verified, the first certificate in the file will
39832 * still be returned.
39834 * If @file cannot be read or parsed, the function will return %NULL and
39835 * set @error. Otherwise, this behaves like
39836 * g_tls_certificate_new_from_pem().
39838 * Returns: the new certificate, or %NULL on error
39844 * g_tls_certificate_new_from_files:
39845 * @cert_file: (type filename): file containing one or more PEM-encoded
39846 * certificates to import
39847 * @key_file: (type filename): file containing a PEM-encoded private key
39849 * @error: #GError for error reporting, or %NULL to ignore.
39851 * Creates a #GTlsCertificate from the PEM-encoded data in @cert_file
39852 * and @key_file. The returned certificate will be the first certificate
39853 * found in @cert_file. As of GLib 2.44, if @cert_file contains more
39854 * certificates it will try to load a certificate chain. All
39855 * certificates will be verified in the order found (top-level
39856 * certificate should be the last one in the file) and the
39857 * #GTlsCertificate:issuer property of each certificate will be set
39858 * accordingly if the verification succeeds. If any certificate in the
39859 * chain cannot be verified, the first certificate in the file will
39860 * still be returned.
39862 * If either file cannot be read or parsed, the function will return
39863 * %NULL and set @error. Otherwise, this behaves like
39864 * g_tls_certificate_new_from_pem().
39866 * Returns: the new certificate, or %NULL on error
39872 * g_tls_certificate_new_from_pem:
39873 * @data: PEM-encoded certificate data
39874 * @length: the length of @data, or -1 if it's 0-terminated.
39875 * @error: #GError for error reporting, or %NULL to ignore.
39877 * Creates a #GTlsCertificate from the PEM-encoded data in @data. If
39878 * @data includes both a certificate and a private key, then the
39879 * returned certificate will include the private key data as well. (See
39880 * the #GTlsCertificate:private-key-pem property for information about
39881 * supported formats.)
39883 * The returned certificate will be the first certificate found in
39884 * @data. As of GLib 2.44, if @data contains more certificates it will
39885 * try to load a certificate chain. All certificates will be verified in
39886 * the order found (top-level certificate should be the last one in the
39887 * file) and the #GTlsCertificate:issuer property of each certificate
39888 * will be set accordingly if the verification succeeds. If any
39889 * certificate in the chain cannot be verified, the first certificate in
39890 * the file will still be returned.
39892 * Returns: the new certificate, or %NULL if @data is invalid
39898 * g_tls_certificate_new_from_pkcs11_uris:
39899 * @pkcs11_uri: A PKCS \#11 URI
39900 * @private_key_pkcs11_uri: (nullable): A PKCS \#11 URI
39901 * @error: #GError for error reporting, or %NULL to ignore.
39903 * Creates a #GTlsCertificate from a
39904 * [PKCS \#11](https://docs.oasis-open.org/pkcs11/pkcs11-base/v3.0/os/pkcs11-base-v3.0-os.html) URI.
39906 * An example @pkcs11_uri would be `pkcs11:model=Model;manufacturer=Manufacture;serial=1;token=My%20Client%20Certificate;id=%01`
39908 * Where the token’s layout is:
39912 * URL: pkcs11:model=Model;manufacturer=Manufacture;serial=1;token=My%20Client%20Certificate;id=%01;object=private%20key;type=private
39913 * Type: Private key (RSA-2048)
39917 * URL: pkcs11:model=Model;manufacturer=Manufacture;serial=1;token=My%20Client%20Certificate;id=%01;object=Certificate%20for%20Authentication;type=cert
39918 * Type: X.509 Certificate (RSA-2048)
39922 * In this case the certificate and private key would both be detected and used as expected.
39923 * @pkcs_uri may also just reference an X.509 certificate object and then optionally
39924 * @private_key_pkcs11_uri allows using a private key exposed under a different URI.
39926 * Note that the private key is not accessed until usage and may fail or require a PIN later.
39928 * Returns: (transfer full): the new certificate, or %NULL on error
39934 * g_tls_certificate_verify:
39935 * @cert: a #GTlsCertificate
39936 * @identity: (nullable): the expected peer identity
39937 * @trusted_ca: (nullable): the certificate of a trusted authority
39939 * This verifies @cert and returns a set of #GTlsCertificateFlags
39940 * indicating any problems found with it. This can be used to verify a
39941 * certificate outside the context of making a connection, or to
39942 * check a certificate against a CA that is not part of the system
39945 * If @identity is not %NULL, @cert's name(s) will be compared against
39946 * it, and %G_TLS_CERTIFICATE_BAD_IDENTITY will be set in the return
39947 * value if it does not match. If @identity is %NULL, that bit will
39948 * never be set in the return value.
39950 * If @trusted_ca is not %NULL, then @cert (or one of the certificates
39951 * in its chain) must be signed by it, or else
39952 * %G_TLS_CERTIFICATE_UNKNOWN_CA will be set in the return value. If
39953 * @trusted_ca is %NULL, that bit will never be set in the return
39956 * (All other #GTlsCertificateFlags values will always be set or unset
39959 * Because TLS session context is not used, #GTlsCertificate may not
39960 * perform as many checks on the certificates as #GTlsConnection would.
39961 * For example, certificate constraints cannot be honored, and some
39962 * revocation checks cannot be performed. The best way to verify TLS
39963 * certificates used by a TLS connection is to let #GTlsConnection
39964 * handle the verification.
39966 * Returns: the appropriate #GTlsCertificateFlags
39972 * g_tls_channel_binding_error_quark:
39974 * Gets the TLS channel binding error quark.
39976 * Returns: a #GQuark.
39982 * g_tls_client_connection_copy_session_state:
39983 * @conn: a #GTlsClientConnection
39984 * @source: a #GTlsClientConnection
39986 * Possibly copies session state from one connection to another, for use
39987 * in TLS session resumption. This is not normally needed, but may be
39988 * used when the same session needs to be used between different
39989 * endpoints, as is required by some protocols, such as FTP over TLS.
39990 * @source should have already completed a handshake and, since TLS 1.3,
39991 * it should have been used to read data at least once. @conn should not
39992 * have completed a handshake.
39994 * It is not possible to know whether a call to this function will
39995 * actually do anything. Because session resumption is normally used
39996 * only for performance benefit, the TLS backend might not implement
39997 * this function. Even if implemented, it may not actually succeed in
39998 * allowing @conn to resume @source's TLS session, because the server
39999 * may not have sent a session resumption token to @source, or it may
40000 * refuse to accept the token from @conn. There is no way to know
40001 * whether a call to this function is actually successful.
40003 * Using this function is not required to benefit from session
40004 * resumption. If the TLS backend supports session resumption, the
40005 * session will be resumed automatically if it is possible to do so
40006 * without weakening the privacy guarantees normally provided by TLS,
40007 * without need to call this function. For example, with TLS 1.3,
40008 * a session ticket will be automatically copied from any
40009 * #GTlsClientConnection that has previously received session tickets
40010 * from the server, provided a ticket is available that has not
40011 * previously been used for session resumption, since session ticket
40012 * reuse would be a privacy weakness. Using this function causes the
40013 * ticket to be copied without regard for privacy considerations.
40020 * g_tls_client_connection_get_accepted_cas:
40021 * @conn: the #GTlsClientConnection
40023 * Gets the list of distinguished names of the Certificate Authorities
40024 * that the server will accept certificates from. This will be set
40025 * during the TLS handshake if the server requests a certificate.
40026 * Otherwise, it will be %NULL.
40028 * Each item in the list is a #GByteArray which contains the complete
40029 * subject DN of the certificate authority.
40031 * Returns: (element-type GByteArray) (transfer full): the list of
40032 * CA DNs. You should unref each element with g_byte_array_unref() and then
40033 * the free the list with g_list_free().
40039 * g_tls_client_connection_get_server_identity:
40040 * @conn: the #GTlsClientConnection
40042 * Gets @conn's expected server identity
40044 * Returns: (nullable) (transfer none): a #GSocketConnectable describing the
40045 * expected server identity, or %NULL if the expected identity is not
40052 * g_tls_client_connection_get_use_ssl3:
40053 * @conn: the #GTlsClientConnection
40055 * SSL 3.0 is no longer supported. See
40056 * g_tls_client_connection_set_use_ssl3() for details.
40060 * Deprecated: 2.56: SSL 3.0 is insecure.
40065 * g_tls_client_connection_get_validation_flags:
40066 * @conn: the #GTlsClientConnection
40068 * Gets @conn's validation flags
40070 * Returns: the validation flags
40076 * g_tls_client_connection_new:
40077 * @base_io_stream: the #GIOStream to wrap
40078 * @server_identity: (nullable): the expected identity of the server
40079 * @error: #GError for error reporting, or %NULL to ignore.
40081 * Creates a new #GTlsClientConnection wrapping @base_io_stream (which
40082 * must have pollable input and output streams) which is assumed to
40083 * communicate with the server identified by @server_identity.
40085 * See the documentation for #GTlsConnection:base-io-stream for restrictions
40086 * on when application code can run operations on the @base_io_stream after
40087 * this function has returned.
40089 * Returns: (transfer full) (type GTlsClientConnection): the new
40090 * #GTlsClientConnection, or %NULL on error
40096 * g_tls_client_connection_set_server_identity:
40097 * @conn: the #GTlsClientConnection
40098 * @identity: a #GSocketConnectable describing the expected server identity
40100 * Sets @conn's expected server identity, which is used both to tell
40101 * servers on virtual hosts which certificate to present, and also
40102 * to let @conn know what name to look for in the certificate when
40103 * performing %G_TLS_CERTIFICATE_BAD_IDENTITY validation, if enabled.
40110 * g_tls_client_connection_set_use_ssl3:
40111 * @conn: the #GTlsClientConnection
40112 * @use_ssl3: a #gboolean, ignored
40114 * Since GLib 2.42.1, SSL 3.0 is no longer supported.
40116 * From GLib 2.42.1 through GLib 2.62, this function could be used to
40117 * force use of TLS 1.0, the lowest-supported TLS protocol version at
40118 * the time. In the past, this was needed to connect to broken TLS
40119 * servers that exhibited protocol version intolerance. Such servers
40120 * are no longer common, and using TLS 1.0 is no longer considered
40123 * Since GLib 2.64, this function does nothing.
40126 * Deprecated: 2.56: SSL 3.0 is insecure.
40131 * g_tls_client_connection_set_validation_flags:
40132 * @conn: the #GTlsClientConnection
40133 * @flags: the #GTlsCertificateFlags to use
40135 * Sets @conn's validation flags, to override the default set of
40136 * checks performed when validating a server certificate. By default,
40137 * %G_TLS_CERTIFICATE_VALIDATE_ALL is used.
40144 * g_tls_connection_emit_accept_certificate:
40145 * @conn: a #GTlsConnection
40146 * @peer_cert: the peer's #GTlsCertificate
40147 * @errors: the problems with @peer_cert
40149 * Used by #GTlsConnection implementations to emit the
40150 * #GTlsConnection::accept-certificate signal.
40152 * Returns: %TRUE if one of the signal handlers has returned
40153 * %TRUE to accept @peer_cert
40159 * g_tls_connection_get_certificate:
40160 * @conn: a #GTlsConnection
40162 * Gets @conn's certificate, as set by
40163 * g_tls_connection_set_certificate().
40165 * Returns: (transfer none) (nullable): @conn's certificate, or %NULL
40171 * g_tls_connection_get_channel_binding_data:
40172 * @conn: a #GTlsConnection
40173 * @type: #GTlsChannelBindingType type of data to fetch
40174 * @data: (out callee-allocates) (optional) (transfer none): #GByteArray is
40175 * filled with the binding data, or %NULL
40176 * @error: a #GError pointer, or %NULL
40178 * Query the TLS backend for TLS channel binding data of @type for @conn.
40180 * This call retrieves TLS channel binding data as specified in RFC
40181 * [5056](https://tools.ietf.org/html/rfc5056), RFC
40182 * [5929](https://tools.ietf.org/html/rfc5929), and related RFCs. The
40183 * binding data is returned in @data. The @data is resized by the callee
40184 * using #GByteArray buffer management and will be freed when the @data
40185 * is destroyed by g_byte_array_unref(). If @data is %NULL, it will only
40186 * check whether TLS backend is able to fetch the data (e.g. whether @type
40187 * is supported by the TLS backend). It does not guarantee that the data
40188 * will be available though. That could happen if TLS connection does not
40189 * support @type or the binding data is not available yet due to additional
40190 * negotiation or input required.
40192 * Returns: %TRUE on success, %FALSE otherwise
40198 * g_tls_connection_get_ciphersuite_name:
40199 * @conn: a #GTlsConnection
40201 * Returns the name of the current TLS ciphersuite, or %NULL if the
40202 * connection has not handshaked or has been closed. Beware that the TLS
40203 * backend may use any of multiple different naming conventions, because
40204 * OpenSSL and GnuTLS have their own ciphersuite naming conventions that
40205 * are different from each other and different from the standard, IANA-
40206 * registered ciphersuite names. The ciphersuite name is intended to be
40207 * displayed to the user for informative purposes only, and parsing it
40208 * is not recommended.
40210 * Returns: (nullable): The name of the current TLS ciphersuite, or %NULL
40216 * g_tls_connection_get_database:
40217 * @conn: a #GTlsConnection
40219 * Gets the certificate database that @conn uses to verify
40220 * peer certificates. See g_tls_connection_set_database().
40222 * Returns: (transfer none) (nullable): the certificate database that @conn uses or %NULL
40228 * g_tls_connection_get_interaction:
40229 * @conn: a connection
40231 * Get the object that will be used to interact with the user. It will be used
40232 * for things like prompting the user for passwords. If %NULL is returned, then
40233 * no user interaction will occur for this connection.
40235 * Returns: (transfer none) (nullable): The interaction object.
40241 * g_tls_connection_get_negotiated_protocol:
40242 * @conn: a #GTlsConnection
40244 * Gets the name of the application-layer protocol negotiated during
40247 * If the peer did not use the ALPN extension, or did not advertise a
40248 * protocol that matched one of @conn's protocols, or the TLS backend
40249 * does not support ALPN, then this will be %NULL. See
40250 * g_tls_connection_set_advertised_protocols().
40252 * Returns: (nullable): the negotiated protocol, or %NULL
40258 * g_tls_connection_get_peer_certificate:
40259 * @conn: a #GTlsConnection
40261 * Gets @conn's peer's certificate after the handshake has completed
40262 * or failed. (It is not set during the emission of
40263 * #GTlsConnection::accept-certificate.)
40265 * Returns: (transfer none) (nullable): @conn's peer's certificate, or %NULL
40271 * g_tls_connection_get_peer_certificate_errors:
40272 * @conn: a #GTlsConnection
40274 * Gets the errors associated with validating @conn's peer's
40275 * certificate, after the handshake has completed or failed. (It is
40276 * not set during the emission of #GTlsConnection::accept-certificate.)
40278 * Returns: @conn's peer's certificate errors
40284 * g_tls_connection_get_protocol_version:
40285 * @conn: a #GTlsConnection
40287 * Returns the current TLS protocol version, which may be
40288 * %G_TLS_PROTOCOL_VERSION_UNKNOWN if the connection has not handshaked, or
40289 * has been closed, or if the TLS backend has implemented a protocol version
40290 * that is not a recognized #GTlsProtocolVersion.
40292 * Returns: The current TLS protocol version
40298 * g_tls_connection_get_rehandshake_mode:
40299 * @conn: a #GTlsConnection
40301 * Gets @conn rehandshaking mode. See
40302 * g_tls_connection_set_rehandshake_mode() for details.
40304 * Returns: %G_TLS_REHANDSHAKE_SAFELY
40306 * Deprecated: 2.60.: Changing the rehandshake mode is no longer
40307 * required for compatibility. Also, rehandshaking has been removed
40308 * from the TLS protocol in TLS 1.3.
40313 * g_tls_connection_get_require_close_notify:
40314 * @conn: a #GTlsConnection
40316 * Tests whether or not @conn expects a proper TLS close notification
40317 * when the connection is closed. See
40318 * g_tls_connection_set_require_close_notify() for details.
40320 * Returns: %TRUE if @conn requires a proper TLS close
40327 * g_tls_connection_get_use_system_certdb:
40328 * @conn: a #GTlsConnection
40330 * Gets whether @conn uses the system certificate database to verify
40331 * peer certificates. See g_tls_connection_set_use_system_certdb().
40333 * Returns: whether @conn uses the system certificate database
40334 * Deprecated: 2.30: Use g_tls_connection_get_database() instead
40339 * g_tls_connection_handshake:
40340 * @conn: a #GTlsConnection
40341 * @cancellable: (nullable): a #GCancellable, or %NULL
40342 * @error: a #GError, or %NULL
40344 * Attempts a TLS handshake on @conn.
40346 * On the client side, it is never necessary to call this method;
40347 * although the connection needs to perform a handshake after
40348 * connecting (or after sending a "STARTTLS"-type command),
40349 * #GTlsConnection will handle this for you automatically when you try
40350 * to send or receive data on the connection. You can call
40351 * g_tls_connection_handshake() manually if you want to know whether
40352 * the initial handshake succeeded or failed (as opposed to just
40353 * immediately trying to use @conn to read or write, in which case,
40354 * if it fails, it may not be possible to tell if it failed before or
40355 * after completing the handshake), but beware that servers may reject
40356 * client authentication after the handshake has completed, so a
40357 * successful handshake does not indicate the connection will be usable.
40359 * Likewise, on the server side, although a handshake is necessary at
40360 * the beginning of the communication, you do not need to call this
40361 * function explicitly unless you want clearer error reporting.
40363 * Previously, calling g_tls_connection_handshake() after the initial
40364 * handshake would trigger a rehandshake; however, this usage was
40365 * deprecated in GLib 2.60 because rehandshaking was removed from the
40366 * TLS protocol in TLS 1.3. Since GLib 2.64, calling this function after
40367 * the initial handshake will no longer do anything.
40369 * When using a #GTlsConnection created by #GSocketClient, the
40370 * #GSocketClient performs the initial handshake, so calling this
40371 * function manually is not recommended.
40373 * #GTlsConnection::accept_certificate may be emitted during the
40376 * Returns: success or failure
40382 * g_tls_connection_handshake_async:
40383 * @conn: a #GTlsConnection
40384 * @io_priority: the [I/O priority][io-priority] of the request
40385 * @cancellable: (nullable): a #GCancellable, or %NULL
40386 * @callback: callback to call when the handshake is complete
40387 * @user_data: the data to pass to the callback function
40389 * Asynchronously performs a TLS handshake on @conn. See
40390 * g_tls_connection_handshake() for more information.
40397 * g_tls_connection_handshake_finish:
40398 * @conn: a #GTlsConnection
40399 * @result: a #GAsyncResult.
40400 * @error: a #GError pointer, or %NULL
40402 * Finish an asynchronous TLS handshake operation. See
40403 * g_tls_connection_handshake() for more information.
40405 * Returns: %TRUE on success, %FALSE on failure, in which
40406 * case @error will be set.
40412 * g_tls_connection_set_advertised_protocols:
40413 * @conn: a #GTlsConnection
40414 * @protocols: (array zero-terminated=1) (nullable): a %NULL-terminated
40415 * array of ALPN protocol names (eg, "http/1.1", "h2"), or %NULL
40417 * Sets the list of application-layer protocols to advertise that the
40418 * caller is willing to speak on this connection. The
40419 * Application-Layer Protocol Negotiation (ALPN) extension will be
40420 * used to negotiate a compatible protocol with the peer; use
40421 * g_tls_connection_get_negotiated_protocol() to find the negotiated
40422 * protocol after the handshake. Specifying %NULL for the the value
40423 * of @protocols will disable ALPN negotiation.
40425 * See [IANA TLS ALPN Protocol IDs](https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids)
40426 * for a list of registered protocol IDs.
40433 * g_tls_connection_set_certificate:
40434 * @conn: a #GTlsConnection
40435 * @certificate: the certificate to use for @conn
40437 * This sets the certificate that @conn will present to its peer
40438 * during the TLS handshake. For a #GTlsServerConnection, it is
40439 * mandatory to set this, and that will normally be done at construct
40442 * For a #GTlsClientConnection, this is optional. If a handshake fails
40443 * with %G_TLS_ERROR_CERTIFICATE_REQUIRED, that means that the server
40444 * requires a certificate, and if you try connecting again, you should
40445 * call this method first. You can call
40446 * g_tls_client_connection_get_accepted_cas() on the failed connection
40447 * to get a list of Certificate Authorities that the server will
40448 * accept certificates from.
40450 * (It is also possible that a server will allow the connection with
40451 * or without a certificate; in that case, if you don't provide a
40452 * certificate, you can tell that the server requested one by the fact
40453 * that g_tls_client_connection_get_accepted_cas() will return
40461 * g_tls_connection_set_database:
40462 * @conn: a #GTlsConnection
40463 * @database: (nullable): a #GTlsDatabase
40465 * Sets the certificate database that is used to verify peer certificates.
40466 * This is set to the default database by default. See
40467 * g_tls_backend_get_default_database(). If set to %NULL, then
40468 * peer certificate validation will always set the
40469 * %G_TLS_CERTIFICATE_UNKNOWN_CA error (meaning
40470 * #GTlsConnection::accept-certificate will always be emitted on
40471 * client-side connections, unless that bit is not set in
40472 * #GTlsClientConnection:validation-flags).
40479 * g_tls_connection_set_interaction:
40480 * @conn: a connection
40481 * @interaction: (nullable): an interaction object, or %NULL
40483 * Set the object that will be used to interact with the user. It will be used
40484 * for things like prompting the user for passwords.
40486 * The @interaction argument will normally be a derived subclass of
40487 * #GTlsInteraction. %NULL can also be provided if no user interaction
40488 * should occur for this connection.
40495 * g_tls_connection_set_rehandshake_mode:
40496 * @conn: a #GTlsConnection
40497 * @mode: the rehandshaking mode
40499 * Since GLib 2.64, changing the rehandshake mode is no longer supported
40500 * and will have no effect. With TLS 1.3, rehandshaking has been removed from
40501 * the TLS protocol, replaced by separate post-handshake authentication and
40502 * rekey operations.
40505 * Deprecated: 2.60.: Changing the rehandshake mode is no longer
40506 * required for compatibility. Also, rehandshaking has been removed
40507 * from the TLS protocol in TLS 1.3.
40512 * g_tls_connection_set_require_close_notify:
40513 * @conn: a #GTlsConnection
40514 * @require_close_notify: whether or not to require close notification
40516 * Sets whether or not @conn expects a proper TLS close notification
40517 * before the connection is closed. If this is %TRUE (the default),
40518 * then @conn will expect to receive a TLS close notification from its
40519 * peer before the connection is closed, and will return a
40520 * %G_TLS_ERROR_EOF error if the connection is closed without proper
40521 * notification (since this may indicate a network error, or
40522 * man-in-the-middle attack).
40524 * In some protocols, the application will know whether or not the
40525 * connection was closed cleanly based on application-level data
40526 * (because the application-level data includes a length field, or is
40527 * somehow self-delimiting); in this case, the close notify is
40528 * redundant and sometimes omitted. (TLS 1.1 explicitly allows this;
40529 * in TLS 1.0 it is technically an error, but often done anyway.) You
40530 * can use g_tls_connection_set_require_close_notify() to tell @conn
40531 * to allow an "unannounced" connection close, in which case the close
40532 * will show up as a 0-length read, as in a non-TLS
40533 * #GSocketConnection, and it is up to the application to check that
40534 * the data has been fully received.
40536 * Note that this only affects the behavior when the peer closes the
40537 * connection; when the application calls g_io_stream_close() itself
40538 * on @conn, this will send a close notification regardless of the
40539 * setting of this property. If you explicitly want to do an unclean
40540 * close, you can close @conn's #GTlsConnection:base-io-stream rather
40541 * than closing @conn itself, but note that this may only be done when no other
40542 * operations are pending on @conn or the base I/O stream.
40549 * g_tls_connection_set_use_system_certdb:
40550 * @conn: a #GTlsConnection
40551 * @use_system_certdb: whether to use the system certificate database
40553 * Sets whether @conn uses the system certificate database to verify
40554 * peer certificates. This is %TRUE by default. If set to %FALSE, then
40555 * peer certificate validation will always set the
40556 * %G_TLS_CERTIFICATE_UNKNOWN_CA error (meaning
40557 * #GTlsConnection::accept-certificate will always be emitted on
40558 * client-side connections, unless that bit is not set in
40559 * #GTlsClientConnection:validation-flags).
40561 * Deprecated: 2.30: Use g_tls_connection_set_database() instead
40566 * g_tls_database_create_certificate_handle:
40567 * @self: a #GTlsDatabase
40568 * @certificate: certificate for which to create a handle.
40570 * Create a handle string for the certificate. The database will only be able
40571 * to create a handle for certificates that originate from the database. In
40572 * cases where the database cannot create a handle for a certificate, %NULL
40573 * will be returned.
40575 * This handle should be stable across various instances of the application,
40576 * and between applications. If a certificate is modified in the database,
40577 * then it is not guaranteed that this handle will continue to point to it.
40579 * Returns: (nullable): a newly allocated string containing the
40586 * g_tls_database_lookup_certificate_for_handle:
40587 * @self: a #GTlsDatabase
40588 * @handle: a certificate handle
40589 * @interaction: (nullable): used to interact with the user if necessary
40590 * @flags: Flags which affect the lookup.
40591 * @cancellable: (nullable): a #GCancellable, or %NULL
40592 * @error: (nullable): a #GError, or %NULL
40594 * Look up a certificate by its handle.
40596 * The handle should have been created by calling
40597 * g_tls_database_create_certificate_handle() on a #GTlsDatabase object of
40598 * the same TLS backend. The handle is designed to remain valid across
40599 * instantiations of the database.
40601 * If the handle is no longer valid, or does not point to a certificate in
40602 * this database, then %NULL will be returned.
40604 * This function can block, use g_tls_database_lookup_certificate_for_handle_async() to perform
40605 * the lookup operation asynchronously.
40607 * Returns: (transfer full) (nullable): a newly allocated
40608 * #GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate.
40614 * g_tls_database_lookup_certificate_for_handle_async:
40615 * @self: a #GTlsDatabase
40616 * @handle: a certificate handle
40617 * @interaction: (nullable): used to interact with the user if necessary
40618 * @flags: Flags which affect the lookup.
40619 * @cancellable: (nullable): a #GCancellable, or %NULL
40620 * @callback: callback to call when the operation completes
40621 * @user_data: the data to pass to the callback function
40623 * Asynchronously look up a certificate by its handle in the database. See
40624 * g_tls_database_lookup_certificate_for_handle() for more information.
40631 * g_tls_database_lookup_certificate_for_handle_finish:
40632 * @self: a #GTlsDatabase
40633 * @result: a #GAsyncResult.
40634 * @error: a #GError pointer, or %NULL
40636 * Finish an asynchronous lookup of a certificate by its handle. See
40637 * g_tls_database_lookup_certificate_for_handle() for more information.
40639 * If the handle is no longer valid, or does not point to a certificate in
40640 * this database, then %NULL will be returned.
40642 * Returns: (transfer full): a newly allocated #GTlsCertificate object.
40643 * Use g_object_unref() to release the certificate.
40649 * g_tls_database_lookup_certificate_issuer:
40650 * @self: a #GTlsDatabase
40651 * @certificate: a #GTlsCertificate
40652 * @interaction: (nullable): used to interact with the user if necessary
40653 * @flags: flags which affect the lookup operation
40654 * @cancellable: (nullable): a #GCancellable, or %NULL
40655 * @error: (nullable): a #GError, or %NULL
40657 * Look up the issuer of @certificate in the database. The
40658 * #GTlsCertificate:issuer property of @certificate is not modified, and
40659 * the two certificates are not hooked into a chain.
40661 * This function can block. Use g_tls_database_lookup_certificate_issuer_async()
40662 * to perform the lookup operation asynchronously.
40664 * Beware this function cannot be used to build certification paths. The
40665 * issuer certificate returned by this function may not be the same as
40666 * the certificate that would actually be used to construct a valid
40667 * certification path during certificate verification.
40668 * [RFC 4158](https://datatracker.ietf.org/doc/html/rfc4158) explains
40669 * why an issuer certificate cannot be naively assumed to be part of the
40670 * the certification path (though GLib's TLS backends may not follow the
40671 * path building strategies outlined in this RFC). Due to the complexity
40672 * of certification path building, GLib does not provide any way to know
40673 * which certification path will actually be used when verifying a TLS
40674 * certificate. Accordingly, this function cannot be used to make
40675 * security-related decisions. Only GLib itself should make security
40676 * decisions about TLS certificates.
40678 * Returns: (transfer full): a newly allocated issuer #GTlsCertificate,
40679 * or %NULL. Use g_object_unref() to release the certificate.
40685 * g_tls_database_lookup_certificate_issuer_async:
40686 * @self: a #GTlsDatabase
40687 * @certificate: a #GTlsCertificate
40688 * @interaction: (nullable): used to interact with the user if necessary
40689 * @flags: flags which affect the lookup operation
40690 * @cancellable: (nullable): a #GCancellable, or %NULL
40691 * @callback: callback to call when the operation completes
40692 * @user_data: the data to pass to the callback function
40694 * Asynchronously look up the issuer of @certificate in the database. See
40695 * g_tls_database_lookup_certificate_issuer() for more information.
40702 * g_tls_database_lookup_certificate_issuer_finish:
40703 * @self: a #GTlsDatabase
40704 * @result: a #GAsyncResult.
40705 * @error: a #GError pointer, or %NULL
40707 * Finish an asynchronous lookup issuer operation. See
40708 * g_tls_database_lookup_certificate_issuer() for more information.
40710 * Returns: (transfer full): a newly allocated issuer #GTlsCertificate,
40711 * or %NULL. Use g_object_unref() to release the certificate.
40717 * g_tls_database_lookup_certificates_issued_by:
40718 * @self: a #GTlsDatabase
40719 * @issuer_raw_dn: a #GByteArray which holds the DER encoded issuer DN.
40720 * @interaction: (nullable): used to interact with the user if necessary
40721 * @flags: Flags which affect the lookup operation.
40722 * @cancellable: (nullable): a #GCancellable, or %NULL
40723 * @error: (nullable): a #GError, or %NULL
40725 * Look up certificates issued by this issuer in the database.
40727 * This function can block, use g_tls_database_lookup_certificates_issued_by_async() to perform
40728 * the lookup operation asynchronously.
40730 * Returns: (transfer full) (element-type GTlsCertificate): a newly allocated list of #GTlsCertificate
40731 * objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list.
40737 * g_tls_database_lookup_certificates_issued_by_async:
40738 * @self: a #GTlsDatabase
40739 * @issuer_raw_dn: a #GByteArray which holds the DER encoded issuer DN.
40740 * @interaction: (nullable): used to interact with the user if necessary
40741 * @flags: Flags which affect the lookup operation.
40742 * @cancellable: (nullable): a #GCancellable, or %NULL
40743 * @callback: callback to call when the operation completes
40744 * @user_data: the data to pass to the callback function
40746 * Asynchronously look up certificates issued by this issuer in the database. See
40747 * g_tls_database_lookup_certificates_issued_by() for more information.
40749 * The database may choose to hold a reference to the issuer byte array for the duration
40750 * of of this asynchronous operation. The byte array should not be modified during
40758 * g_tls_database_lookup_certificates_issued_by_finish:
40759 * @self: a #GTlsDatabase
40760 * @result: a #GAsyncResult.
40761 * @error: a #GError pointer, or %NULL
40763 * Finish an asynchronous lookup of certificates. See
40764 * g_tls_database_lookup_certificates_issued_by() for more information.
40766 * Returns: (transfer full) (element-type GTlsCertificate): a newly allocated list of #GTlsCertificate
40767 * objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list.
40773 * g_tls_database_verify_chain:
40774 * @self: a #GTlsDatabase
40775 * @chain: a #GTlsCertificate chain
40776 * @purpose: the purpose that this certificate chain will be used for.
40777 * @identity: (nullable): the expected peer identity
40778 * @interaction: (nullable): used to interact with the user if necessary
40779 * @flags: additional verify flags
40780 * @cancellable: (nullable): a #GCancellable, or %NULL
40781 * @error: (nullable): a #GError, or %NULL
40783 * Determines the validity of a certificate chain, outside the context
40784 * of a TLS session.
40786 * @chain is a chain of #GTlsCertificate objects each pointing to the next
40787 * certificate in the chain by its #GTlsCertificate:issuer property.
40789 * @purpose describes the purpose (or usage) for which the certificate
40790 * is being used. Typically @purpose will be set to #G_TLS_DATABASE_PURPOSE_AUTHENTICATE_SERVER
40791 * which means that the certificate is being used to authenticate a server
40792 * (and we are acting as the client).
40794 * The @identity is used to ensure the server certificate is valid for
40795 * the expected peer identity. If the identity does not match the
40796 * certificate, %G_TLS_CERTIFICATE_BAD_IDENTITY will be set in the
40797 * return value. If @identity is %NULL, that bit will never be set in
40798 * the return value. The peer identity may also be used to check for
40799 * pinned certificates (trust exceptions) in the database. These may
40800 * override the normal verification process on a host-by-host basis.
40802 * Currently there are no @flags, and %G_TLS_DATABASE_VERIFY_NONE should be
40805 * If @chain is found to be valid, then the return value will be 0. If
40806 * @chain is found to be invalid, then the return value will indicate
40807 * the problems found. If the function is unable to determine whether
40808 * @chain is valid or not (eg, because @cancellable is triggered
40809 * before it completes) then the return value will be
40810 * %G_TLS_CERTIFICATE_GENERIC_ERROR and @error will be set
40811 * accordingly. @error is not set when @chain is successfully analyzed
40812 * but found to be invalid.
40814 * Prior to GLib 2.48, GLib's default TLS backend modified @chain to
40815 * represent the certification path built by #GTlsDatabase during
40816 * certificate verification by adjusting the #GTlsCertificate:issuer
40817 * property of each certificate in @chain. Since GLib 2.48, this no
40818 * longer occurs, so you cannot rely on #GTlsCertificate:issuer to
40819 * represent the actual certification path used during certificate
40822 * Because TLS session context is not used, #GTlsDatabase may not
40823 * perform as many checks on the certificates as #GTlsConnection would.
40824 * For example, certificate constraints cannot be honored, and some
40825 * revocation checks cannot be performed. The best way to verify TLS
40826 * certificates used by a TLS connection is to let #GTlsConnection
40827 * handle the verification.
40829 * The TLS backend may attempt to look up and add missing certificates
40830 * to the chain. Since GLib 2.70, this may involve HTTP requests to
40831 * download missing certificates.
40833 * This function can block. Use g_tls_database_verify_chain_async() to
40834 * perform the verification operation asynchronously.
40836 * Returns: the appropriate #GTlsCertificateFlags which represents the
40837 * result of verification.
40843 * g_tls_database_verify_chain_async:
40844 * @self: a #GTlsDatabase
40845 * @chain: a #GTlsCertificate chain
40846 * @purpose: the purpose that this certificate chain will be used for.
40847 * @identity: (nullable): the expected peer identity
40848 * @interaction: (nullable): used to interact with the user if necessary
40849 * @flags: additional verify flags
40850 * @cancellable: (nullable): a #GCancellable, or %NULL
40851 * @callback: callback to call when the operation completes
40852 * @user_data: the data to pass to the callback function
40854 * Asynchronously determines the validity of a certificate chain after
40855 * looking up and adding any missing certificates to the chain. See
40856 * g_tls_database_verify_chain() for more information.
40863 * g_tls_database_verify_chain_finish:
40864 * @self: a #GTlsDatabase
40865 * @result: a #GAsyncResult.
40866 * @error: a #GError pointer, or %NULL
40868 * Finish an asynchronous verify chain operation. See
40869 * g_tls_database_verify_chain() for more information.
40871 * If @chain is found to be valid, then the return value will be 0. If
40872 * @chain is found to be invalid, then the return value will indicate
40873 * the problems found. If the function is unable to determine whether
40874 * @chain is valid or not (eg, because @cancellable is triggered
40875 * before it completes) then the return value will be
40876 * %G_TLS_CERTIFICATE_GENERIC_ERROR and @error will be set
40877 * accordingly. @error is not set when @chain is successfully analyzed
40878 * but found to be invalid.
40880 * Returns: the appropriate #GTlsCertificateFlags which represents the
40881 * result of verification.
40887 * g_tls_error_quark:
40889 * Gets the TLS error quark.
40891 * Returns: a #GQuark.
40897 * g_tls_file_database_new:
40898 * @anchors: (type filename): filename of anchor certificate authorities.
40899 * @error: #GError for error reporting, or %NULL to ignore.
40901 * Creates a new #GTlsFileDatabase which uses anchor certificate authorities
40902 * in @anchors to verify certificate chains.
40904 * The certificates in @anchors must be PEM encoded.
40906 * Returns: (transfer full) (type GTlsFileDatabase): the new
40907 * #GTlsFileDatabase, or %NULL on error
40913 * g_tls_interaction_ask_password:
40914 * @interaction: a #GTlsInteraction object
40915 * @password: a #GTlsPassword object
40916 * @cancellable: an optional #GCancellable cancellation object
40917 * @error: an optional location to place an error on failure
40919 * Run synchronous interaction to ask the user for a password. In general,
40920 * g_tls_interaction_invoke_ask_password() should be used instead of this
40923 * Derived subclasses usually implement a password prompt, although they may
40924 * also choose to provide a password from elsewhere. The @password value will
40925 * be filled in and then @callback will be called. Alternatively the user may
40926 * abort this password request, which will usually abort the TLS connection.
40928 * If the interaction is cancelled by the cancellation object, or by the
40929 * user then %G_TLS_INTERACTION_FAILED will be returned with an error that
40930 * contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may
40931 * not support immediate cancellation.
40933 * Returns: The status of the ask password interaction.
40939 * g_tls_interaction_ask_password_async:
40940 * @interaction: a #GTlsInteraction object
40941 * @password: a #GTlsPassword object
40942 * @cancellable: an optional #GCancellable cancellation object
40943 * @callback: (nullable): will be called when the interaction completes
40944 * @user_data: (nullable): data to pass to the @callback
40946 * Run asynchronous interaction to ask the user for a password. In general,
40947 * g_tls_interaction_invoke_ask_password() should be used instead of this
40950 * Derived subclasses usually implement a password prompt, although they may
40951 * also choose to provide a password from elsewhere. The @password value will
40952 * be filled in and then @callback will be called. Alternatively the user may
40953 * abort this password request, which will usually abort the TLS connection.
40955 * If the interaction is cancelled by the cancellation object, or by the
40956 * user then %G_TLS_INTERACTION_FAILED will be returned with an error that
40957 * contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may
40958 * not support immediate cancellation.
40960 * Certain implementations may not support immediate cancellation.
40967 * g_tls_interaction_ask_password_finish:
40968 * @interaction: a #GTlsInteraction object
40969 * @result: the result passed to the callback
40970 * @error: an optional location to place an error on failure
40972 * Complete an ask password user interaction request. This should be once
40973 * the g_tls_interaction_ask_password_async() completion callback is called.
40975 * If %G_TLS_INTERACTION_HANDLED is returned, then the #GTlsPassword passed
40976 * to g_tls_interaction_ask_password() will have its password filled in.
40978 * If the interaction is cancelled by the cancellation object, or by the
40979 * user then %G_TLS_INTERACTION_FAILED will be returned with an error that
40980 * contains a %G_IO_ERROR_CANCELLED error code.
40982 * Returns: The status of the ask password interaction.
40988 * g_tls_interaction_invoke_ask_password:
40989 * @interaction: a #GTlsInteraction object
40990 * @password: a #GTlsPassword object
40991 * @cancellable: an optional #GCancellable cancellation object
40992 * @error: an optional location to place an error on failure
40994 * Invoke the interaction to ask the user for a password. It invokes this
40995 * interaction in the main loop, specifically the #GMainContext returned by
40996 * g_main_context_get_thread_default() when the interaction is created. This
40997 * is called by called by #GTlsConnection or #GTlsDatabase to ask the user
41000 * Derived subclasses usually implement a password prompt, although they may
41001 * also choose to provide a password from elsewhere. The @password value will
41002 * be filled in and then @callback will be called. Alternatively the user may
41003 * abort this password request, which will usually abort the TLS connection.
41005 * The implementation can either be a synchronous (eg: modal dialog) or an
41006 * asynchronous one (eg: modeless dialog). This function will take care of
41007 * calling which ever one correctly.
41009 * If the interaction is cancelled by the cancellation object, or by the
41010 * user then %G_TLS_INTERACTION_FAILED will be returned with an error that
41011 * contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may
41012 * not support immediate cancellation.
41014 * Returns: The status of the ask password interaction.
41020 * g_tls_interaction_invoke_request_certificate:
41021 * @interaction: a #GTlsInteraction object
41022 * @connection: a #GTlsConnection object
41023 * @flags: flags providing more information about the request
41024 * @cancellable: an optional #GCancellable cancellation object
41025 * @error: an optional location to place an error on failure
41027 * Invoke the interaction to ask the user to choose a certificate to
41028 * use with the connection. It invokes this interaction in the main
41029 * loop, specifically the #GMainContext returned by
41030 * g_main_context_get_thread_default() when the interaction is
41031 * created. This is called by called by #GTlsConnection when the peer
41032 * requests a certificate during the handshake.
41034 * Derived subclasses usually implement a certificate selector,
41035 * although they may also choose to provide a certificate from
41036 * elsewhere. Alternatively the user may abort this certificate
41037 * request, which may or may not abort the TLS connection.
41039 * The implementation can either be a synchronous (eg: modal dialog) or an
41040 * asynchronous one (eg: modeless dialog). This function will take care of
41041 * calling which ever one correctly.
41043 * If the interaction is cancelled by the cancellation object, or by the
41044 * user then %G_TLS_INTERACTION_FAILED will be returned with an error that
41045 * contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may
41046 * not support immediate cancellation.
41048 * Returns: The status of the certificate request interaction.
41054 * g_tls_interaction_request_certificate:
41055 * @interaction: a #GTlsInteraction object
41056 * @connection: a #GTlsConnection object
41057 * @flags: flags providing more information about the request
41058 * @cancellable: an optional #GCancellable cancellation object
41059 * @error: an optional location to place an error on failure
41061 * Run synchronous interaction to ask the user to choose a certificate to use
41062 * with the connection. In general, g_tls_interaction_invoke_request_certificate()
41063 * should be used instead of this function.
41065 * Derived subclasses usually implement a certificate selector, although they may
41066 * also choose to provide a certificate from elsewhere. Alternatively the user may
41067 * abort this certificate request, which will usually abort the TLS connection.
41069 * If %G_TLS_INTERACTION_HANDLED is returned, then the #GTlsConnection
41070 * passed to g_tls_interaction_request_certificate() will have had its
41071 * #GTlsConnection:certificate filled in.
41073 * If the interaction is cancelled by the cancellation object, or by the
41074 * user then %G_TLS_INTERACTION_FAILED will be returned with an error that
41075 * contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may
41076 * not support immediate cancellation.
41078 * Returns: The status of the request certificate interaction.
41084 * g_tls_interaction_request_certificate_async:
41085 * @interaction: a #GTlsInteraction object
41086 * @connection: a #GTlsConnection object
41087 * @flags: flags providing more information about the request
41088 * @cancellable: an optional #GCancellable cancellation object
41089 * @callback: (nullable): will be called when the interaction completes
41090 * @user_data: (nullable): data to pass to the @callback
41092 * Run asynchronous interaction to ask the user for a certificate to use with
41093 * the connection. In general, g_tls_interaction_invoke_request_certificate() should
41094 * be used instead of this function.
41096 * Derived subclasses usually implement a certificate selector, although they may
41097 * also choose to provide a certificate from elsewhere. @callback will be called
41098 * when the operation completes. Alternatively the user may abort this certificate
41099 * request, which will usually abort the TLS connection.
41106 * g_tls_interaction_request_certificate_finish:
41107 * @interaction: a #GTlsInteraction object
41108 * @result: the result passed to the callback
41109 * @error: an optional location to place an error on failure
41111 * Complete a request certificate user interaction request. This should be once
41112 * the g_tls_interaction_request_certificate_async() completion callback is called.
41114 * If %G_TLS_INTERACTION_HANDLED is returned, then the #GTlsConnection
41115 * passed to g_tls_interaction_request_certificate_async() will have had its
41116 * #GTlsConnection:certificate filled in.
41118 * If the interaction is cancelled by the cancellation object, or by the
41119 * user then %G_TLS_INTERACTION_FAILED will be returned with an error that
41120 * contains a %G_IO_ERROR_CANCELLED error code.
41122 * Returns: The status of the request certificate interaction.
41128 * g_tls_password_get_description:
41129 * @password: a #GTlsPassword object
41131 * Get a description string about what the password will be used for.
41133 * Returns: The description of the password.
41139 * g_tls_password_get_flags:
41140 * @password: a #GTlsPassword object
41142 * Get flags about the password.
41144 * Returns: The flags about the password.
41150 * g_tls_password_get_value: (virtual get_value)
41151 * @password: a #GTlsPassword object
41152 * @length: (optional): location to place the length of the password.
41154 * Get the password value. If @length is not %NULL then it will be
41155 * filled in with the length of the password value. (Note that the
41156 * password value is not nul-terminated, so you can only pass %NULL
41157 * for @length in contexts where you know the password will have a
41158 * certain fixed length.)
41160 * Returns: (array length=length): The password value (owned by the password object).
41166 * g_tls_password_get_warning:
41167 * @password: a #GTlsPassword object
41169 * Get a user readable translated warning. Usually this warning is a
41170 * representation of the password flags returned from
41171 * g_tls_password_get_flags().
41173 * Returns: The warning.
41179 * g_tls_password_new:
41180 * @flags: the password flags
41181 * @description: description of what the password is for
41183 * Create a new #GTlsPassword object.
41185 * Returns: (transfer full): The newly allocated password object
41190 * g_tls_password_set_description:
41191 * @password: a #GTlsPassword object
41192 * @description: The description of the password
41194 * Set a description string about what the password will be used for.
41201 * g_tls_password_set_flags:
41202 * @password: a #GTlsPassword object
41203 * @flags: The flags about the password
41205 * Set flags about the password.
41212 * g_tls_password_set_value:
41213 * @password: a #GTlsPassword object
41214 * @value: (array length=length): the new password value
41215 * @length: the length of the password, or -1
41217 * Set the value for this password. The @value will be copied by the password
41220 * Specify the @length, for a non-nul-terminated password. Pass -1 as
41221 * @length if using a nul-terminated password, and @length will be
41222 * calculated automatically. (Note that the terminating nul is not
41223 * considered part of the password in this case.)
41230 * g_tls_password_set_value_full: (virtual set_value)
41231 * @password: a #GTlsPassword object
41232 * @value: (array length=length): the value for the password
41233 * @length: the length of the password, or -1
41234 * @destroy: (nullable): a function to use to free the password.
41236 * Provide the value for this password.
41238 * The @value will be owned by the password object, and later freed using
41239 * the @destroy function callback.
41241 * Specify the @length, for a non-nul-terminated password. Pass -1 as
41242 * @length if using a nul-terminated password, and @length will be
41243 * calculated automatically. (Note that the terminating nul is not
41244 * considered part of the password in this case.)
41251 * g_tls_password_set_warning:
41252 * @password: a #GTlsPassword object
41253 * @warning: The user readable warning
41255 * Set a user readable translated warning. Usually this warning is a
41256 * representation of the password flags returned from
41257 * g_tls_password_get_flags().
41264 * g_tls_server_connection_new:
41265 * @base_io_stream: the #GIOStream to wrap
41266 * @certificate: (nullable): the default server certificate, or %NULL
41267 * @error: #GError for error reporting, or %NULL to ignore.
41269 * Creates a new #GTlsServerConnection wrapping @base_io_stream (which
41270 * must have pollable input and output streams).
41272 * See the documentation for #GTlsConnection:base-io-stream for restrictions
41273 * on when application code can run operations on the @base_io_stream after
41274 * this function has returned.
41276 * Returns: (transfer full) (type GTlsServerConnection): the new
41277 * #GTlsServerConnection, or %NULL on error
41283 * g_unix_connection_receive_credentials:
41284 * @connection: A #GUnixConnection.
41285 * @cancellable: (nullable): A #GCancellable or %NULL.
41286 * @error: Return location for error or %NULL.
41288 * Receives credentials from the sending end of the connection. The
41289 * sending end has to call g_unix_connection_send_credentials() (or
41290 * similar) for this to work.
41292 * As well as reading the credentials this also reads (and discards) a
41293 * single byte from the stream, as this is required for credentials
41294 * passing to work on some implementations.
41296 * This method can be expected to be available on the following platforms:
41298 * - Linux since GLib 2.26
41299 * - FreeBSD since GLib 2.26
41300 * - GNU/kFreeBSD since GLib 2.36
41301 * - Solaris, Illumos and OpenSolaris since GLib 2.40
41302 * - GNU/Hurd since GLib 2.40
41304 * Other ways to exchange credentials with a foreign peer includes the
41305 * #GUnixCredentialsMessage type and g_socket_get_credentials() function.
41307 * Returns: (transfer full): Received credentials on success (free with
41308 * g_object_unref()), %NULL if @error is set.
41314 * g_unix_connection_receive_credentials_async:
41315 * @connection: A #GUnixConnection.
41316 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
41317 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
41318 * @user_data: (closure): the data to pass to callback function
41320 * Asynchronously receive credentials.
41322 * For more details, see g_unix_connection_receive_credentials() which is
41323 * the synchronous version of this call.
41325 * When the operation is finished, @callback will be called. You can then call
41326 * g_unix_connection_receive_credentials_finish() to get the result of the operation.
41333 * g_unix_connection_receive_credentials_finish:
41334 * @connection: A #GUnixConnection.
41335 * @result: a #GAsyncResult.
41336 * @error: a #GError, or %NULL
41338 * Finishes an asynchronous receive credentials operation started with
41339 * g_unix_connection_receive_credentials_async().
41341 * Returns: (transfer full): a #GCredentials, or %NULL on error.
41342 * Free the returned object with g_object_unref().
41348 * g_unix_connection_receive_fd:
41349 * @connection: a #GUnixConnection
41350 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore
41351 * @error: (nullable): #GError for error reporting, or %NULL to ignore
41353 * Receives a file descriptor from the sending end of the connection.
41354 * The sending end has to call g_unix_connection_send_fd() for this
41357 * As well as reading the fd this also reads a single byte from the
41358 * stream, as this is required for fd passing to work on some
41361 * Returns: a file descriptor on success, -1 on error.
41367 * g_unix_connection_send_credentials:
41368 * @connection: A #GUnixConnection.
41369 * @cancellable: (nullable): A #GCancellable or %NULL.
41370 * @error: Return location for error or %NULL.
41372 * Passes the credentials of the current user the receiving side
41373 * of the connection. The receiving end has to call
41374 * g_unix_connection_receive_credentials() (or similar) to accept the
41377 * As well as sending the credentials this also writes a single NUL
41378 * byte to the stream, as this is required for credentials passing to
41379 * work on some implementations.
41381 * This method can be expected to be available on the following platforms:
41383 * - Linux since GLib 2.26
41384 * - FreeBSD since GLib 2.26
41385 * - GNU/kFreeBSD since GLib 2.36
41386 * - Solaris, Illumos and OpenSolaris since GLib 2.40
41387 * - GNU/Hurd since GLib 2.40
41389 * Other ways to exchange credentials with a foreign peer includes the
41390 * #GUnixCredentialsMessage type and g_socket_get_credentials() function.
41392 * Returns: %TRUE on success, %FALSE if @error is set.
41398 * g_unix_connection_send_credentials_async:
41399 * @connection: A #GUnixConnection.
41400 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
41401 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
41402 * @user_data: (closure): the data to pass to callback function
41404 * Asynchronously send credentials.
41406 * For more details, see g_unix_connection_send_credentials() which is
41407 * the synchronous version of this call.
41409 * When the operation is finished, @callback will be called. You can then call
41410 * g_unix_connection_send_credentials_finish() to get the result of the operation.
41417 * g_unix_connection_send_credentials_finish:
41418 * @connection: A #GUnixConnection.
41419 * @result: a #GAsyncResult.
41420 * @error: a #GError, or %NULL
41422 * Finishes an asynchronous send credentials operation started with
41423 * g_unix_connection_send_credentials_async().
41425 * Returns: %TRUE if the operation was successful, otherwise %FALSE.
41431 * g_unix_connection_send_fd:
41432 * @connection: a #GUnixConnection
41433 * @fd: a file descriptor
41434 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
41435 * @error: (nullable): #GError for error reporting, or %NULL to ignore.
41437 * Passes a file descriptor to the receiving side of the
41438 * connection. The receiving end has to call g_unix_connection_receive_fd()
41439 * to accept the file descriptor.
41441 * As well as sending the fd this also writes a single byte to the
41442 * stream, as this is required for fd passing to work on some
41445 * Returns: a %TRUE on success, %NULL on error.
41451 * g_unix_credentials_message_get_credentials:
41452 * @message: A #GUnixCredentialsMessage.
41454 * Gets the credentials stored in @message.
41456 * Returns: (transfer none): A #GCredentials instance. Do not free, it is owned by @message.
41462 * g_unix_credentials_message_is_supported:
41464 * Checks if passing #GCredentials on a #GSocket is supported on this platform.
41466 * Returns: %TRUE if supported, %FALSE otherwise
41472 * g_unix_credentials_message_new:
41474 * Creates a new #GUnixCredentialsMessage with credentials matching the current processes.
41476 * Returns: a new #GUnixCredentialsMessage
41482 * g_unix_credentials_message_new_with_credentials:
41483 * @credentials: A #GCredentials object.
41485 * Creates a new #GUnixCredentialsMessage holding @credentials.
41487 * Returns: a new #GUnixCredentialsMessage
41493 * g_unix_fd_list_append:
41494 * @list: a #GUnixFDList
41495 * @fd: a valid open file descriptor
41496 * @error: a #GError pointer
41498 * Adds a file descriptor to @list.
41500 * The file descriptor is duplicated using dup(). You keep your copy
41501 * of the descriptor and the copy contained in @list will be closed
41502 * when @list is finalized.
41504 * A possible cause of failure is exceeding the per-process or
41505 * system-wide file descriptor limit.
41507 * The index of the file descriptor in the list is returned. If you use
41508 * this index with g_unix_fd_list_get() then you will receive back a
41509 * duplicated copy of the same file descriptor.
41511 * Returns: the index of the appended fd in case of success, else -1
41512 * (and @error is set)
41518 * g_unix_fd_list_get:
41519 * @list: a #GUnixFDList
41520 * @index_: the index into the list
41521 * @error: a #GError pointer
41523 * Gets a file descriptor out of @list.
41525 * @index_ specifies the index of the file descriptor to get. It is a
41526 * programmer error for @index_ to be out of range; see
41527 * g_unix_fd_list_get_length().
41529 * The file descriptor is duplicated using dup() and set as
41530 * close-on-exec before being returned. You must call close() on it
41531 * when you are done.
41533 * A possible cause of failure is exceeding the per-process or
41534 * system-wide file descriptor limit.
41536 * Returns: the file descriptor, or -1 in case of error
41542 * g_unix_fd_list_get_length:
41543 * @list: a #GUnixFDList
41545 * Gets the length of @list (ie: the number of file descriptors
41546 * contained within).
41548 * Returns: the length of @list
41554 * g_unix_fd_list_new:
41556 * Creates a new #GUnixFDList containing no file descriptors.
41558 * Returns: a new #GUnixFDList
41564 * g_unix_fd_list_new_from_array:
41565 * @fds: (array length=n_fds): the initial list of file descriptors
41566 * @n_fds: the length of #fds, or -1
41568 * Creates a new #GUnixFDList containing the file descriptors given in
41569 * @fds. The file descriptors become the property of the new list and
41570 * may no longer be used by the caller. The array itself is owned by
41573 * Each file descriptor in the array should be set to close-on-exec.
41575 * If @n_fds is -1 then @fds must be terminated with -1.
41577 * Returns: a new #GUnixFDList
41583 * g_unix_fd_list_peek_fds:
41584 * @list: a #GUnixFDList
41585 * @length: (out) (optional): pointer to the length of the returned
41588 * Returns the array of file descriptors that is contained in this
41591 * After this call, the descriptors remain the property of @list. The
41592 * caller must not close them and must not free the array. The array is
41593 * valid only until @list is changed in any way.
41595 * If @length is non-%NULL then it is set to the number of file
41596 * descriptors in the returned array. The returned array is also
41597 * terminated with -1.
41599 * This function never returns %NULL. In case there are no file
41600 * descriptors contained in @list, an empty array is returned.
41602 * Returns: (array length=length) (transfer none): an array of file
41609 * g_unix_fd_list_steal_fds:
41610 * @list: a #GUnixFDList
41611 * @length: (out) (optional): pointer to the length of the returned
41614 * Returns the array of file descriptors that is contained in this
41617 * After this call, the descriptors are no longer contained in
41618 * @list. Further calls will return an empty list (unless more
41619 * descriptors have been added).
41621 * The return result of this function must be freed with g_free().
41622 * The caller is also responsible for closing all of the file
41623 * descriptors. The file descriptors in the array are set to
41626 * If @length is non-%NULL then it is set to the number of file
41627 * descriptors in the returned array. The returned array is also
41628 * terminated with -1.
41630 * This function never returns %NULL. In case there are no file
41631 * descriptors contained in @list, an empty array is returned.
41633 * Returns: (array length=length) (transfer full): an array of file
41640 * g_unix_fd_message_append_fd:
41641 * @message: a #GUnixFDMessage
41642 * @fd: a valid open file descriptor
41643 * @error: a #GError pointer
41645 * Adds a file descriptor to @message.
41647 * The file descriptor is duplicated using dup(). You keep your copy
41648 * of the descriptor and the copy contained in @message will be closed
41649 * when @message is finalized.
41651 * A possible cause of failure is exceeding the per-process or
41652 * system-wide file descriptor limit.
41654 * Returns: %TRUE in case of success, else %FALSE (and @error is set)
41660 * g_unix_fd_message_get_fd_list:
41661 * @message: a #GUnixFDMessage
41663 * Gets the #GUnixFDList contained in @message. This function does not
41664 * return a reference to the caller, but the returned list is valid for
41665 * the lifetime of @message.
41667 * Returns: (transfer none): the #GUnixFDList from @message
41673 * g_unix_fd_message_new:
41675 * Creates a new #GUnixFDMessage containing an empty file descriptor
41678 * Returns: a new #GUnixFDMessage
41684 * g_unix_fd_message_new_with_fd_list:
41685 * @fd_list: a #GUnixFDList
41687 * Creates a new #GUnixFDMessage containing @list.
41689 * Returns: a new #GUnixFDMessage
41695 * g_unix_fd_message_steal_fds:
41696 * @message: a #GUnixFDMessage
41697 * @length: (out) (optional): pointer to the length of the returned
41700 * Returns the array of file descriptors that is contained in this
41703 * After this call, the descriptors are no longer contained in
41704 * @message. Further calls will return an empty list (unless more
41705 * descriptors have been added).
41707 * The return result of this function must be freed with g_free().
41708 * The caller is also responsible for closing all of the file
41711 * If @length is non-%NULL then it is set to the number of file
41712 * descriptors in the returned array. The returned array is also
41713 * terminated with -1.
41715 * This function never returns %NULL. In case there are no file
41716 * descriptors contained in @message, an empty array is returned.
41718 * Returns: (array length=length) (transfer full): an array of file
41725 * g_unix_input_stream_get_close_fd:
41726 * @stream: a #GUnixInputStream
41728 * Returns whether the file descriptor of @stream will be
41729 * closed when the stream is closed.
41731 * Returns: %TRUE if the file descriptor is closed when done
41737 * g_unix_input_stream_get_fd:
41738 * @stream: a #GUnixInputStream
41740 * Return the UNIX file descriptor that the stream reads from.
41742 * Returns: The file descriptor of @stream
41748 * g_unix_input_stream_new:
41749 * @fd: a UNIX file descriptor
41750 * @close_fd: %TRUE to close the file descriptor when done
41752 * Creates a new #GUnixInputStream for the given @fd.
41754 * If @close_fd is %TRUE, the file descriptor will be closed
41755 * when the stream is closed.
41757 * Returns: a new #GUnixInputStream
41762 * g_unix_input_stream_set_close_fd:
41763 * @stream: a #GUnixInputStream
41764 * @close_fd: %TRUE to close the file descriptor when done
41766 * Sets whether the file descriptor of @stream shall be closed
41767 * when the stream is closed.
41774 * g_unix_is_mount_path_system_internal:
41775 * @mount_path: (type filename): a mount path, e.g. `/media/disk` or `/usr`
41777 * Determines if @mount_path is considered an implementation of the
41778 * OS. This is primarily used for hiding mountable and mounted volumes
41779 * that only are used in the OS and has little to no relevance to the
41782 * Returns: %TRUE if @mount_path is considered an implementation detail
41788 * g_unix_is_system_device_path:
41789 * @device_path: a device path, e.g. `/dev/loop0` or `nfsd`
41791 * Determines if @device_path is considered a block device path which is only
41792 * used in implementation of the OS. This is primarily used for hiding
41793 * mounted volumes that are intended as APIs for programs to read, and system
41794 * administrators at a shell; rather than something that should, for example,
41795 * appear in a GUI. For example, the Linux `/proc` filesystem.
41797 * The list of device paths considered ‘system’ ones may change over time.
41799 * Returns: %TRUE if @device_path is considered an implementation detail of
41806 * g_unix_is_system_fs_type:
41807 * @fs_type: a file system type, e.g. `procfs` or `tmpfs`
41809 * Determines if @fs_type is considered a type of file system which is only
41810 * used in implementation of the OS. This is primarily used for hiding
41811 * mounted volumes that are intended as APIs for programs to read, and system
41812 * administrators at a shell; rather than something that should, for example,
41813 * appear in a GUI. For example, the Linux `/proc` filesystem.
41815 * The list of file system types considered ‘system’ ones may change over time.
41817 * Returns: %TRUE if @fs_type is considered an implementation detail of the OS.
41824 * @mount_path: (type filename): path for a possible unix mount.
41825 * @time_read: (out) (optional): guint64 to contain a timestamp.
41827 * Gets a #GUnixMountEntry for a given mount path. If @time_read
41828 * is set, it will be filled with a unix timestamp for checking
41829 * if the mounts have changed since with g_unix_mounts_changed_since().
41831 * If more mounts have the same mount path, the last matching mount
41834 * This will return %NULL if there is no mount point at @mount_path.
41836 * Returns: (transfer full) (nullable): a #GUnixMountEntry.
41841 * g_unix_mount_compare:
41842 * @mount1: first #GUnixMountEntry to compare.
41843 * @mount2: second #GUnixMountEntry to compare.
41845 * Compares two unix mounts.
41847 * Returns: 1, 0 or -1 if @mount1 is greater than, equal to,
41848 * or less than @mount2, respectively.
41853 * g_unix_mount_copy:
41854 * @mount_entry: a #GUnixMountEntry.
41856 * Makes a copy of @mount_entry.
41858 * Returns: (transfer full): a new #GUnixMountEntry
41864 * g_unix_mount_for:
41865 * @file_path: (type filename): file path on some unix mount.
41866 * @time_read: (out) (optional): guint64 to contain a timestamp.
41868 * Gets a #GUnixMountEntry for a given file path. If @time_read
41869 * is set, it will be filled with a unix timestamp for checking
41870 * if the mounts have changed since with g_unix_mounts_changed_since().
41872 * If more mounts have the same mount path, the last matching mount
41875 * This will return %NULL if looking up the mount entry fails, if
41876 * @file_path doesn’t exist or there is an I/O error.
41878 * Returns: (transfer full) (nullable): a #GUnixMountEntry.
41884 * g_unix_mount_free:
41885 * @mount_entry: a #GUnixMountEntry.
41887 * Frees a unix mount.
41892 * g_unix_mount_get_device_path:
41893 * @mount_entry: a #GUnixMount.
41895 * Gets the device path for a unix mount.
41897 * Returns: (type filename): a string containing the device path.
41902 * g_unix_mount_get_fs_type:
41903 * @mount_entry: a #GUnixMount.
41905 * Gets the filesystem type for the unix mount.
41907 * Returns: a string containing the file system type.
41912 * g_unix_mount_get_mount_path:
41913 * @mount_entry: input #GUnixMountEntry to get the mount path for.
41915 * Gets the mount path for a unix mount.
41917 * Returns: (type filename): the mount path for @mount_entry.
41922 * g_unix_mount_get_options:
41923 * @mount_entry: a #GUnixMountEntry.
41925 * Gets a comma-separated list of mount options for the unix mount. For example,
41926 * `rw,relatime,seclabel,data=ordered`.
41928 * This is similar to g_unix_mount_point_get_options(), but it takes
41929 * a #GUnixMountEntry as an argument.
41931 * Returns: (nullable): a string containing the options, or %NULL if not
41938 * g_unix_mount_get_root_path:
41939 * @mount_entry: a #GUnixMountEntry.
41941 * Gets the root of the mount within the filesystem. This is useful e.g. for
41942 * mounts created by bind operation, or btrfs subvolumes.
41944 * For example, the root path is equal to "/" for mount created by
41945 * "mount /dev/sda1 /mnt/foo" and "/bar" for
41946 * "mount --bind /mnt/foo/bar /mnt/bar".
41948 * Returns: (nullable): a string containing the root, or %NULL if not supported.
41954 * g_unix_mount_guess_can_eject:
41955 * @mount_entry: a #GUnixMountEntry
41957 * Guesses whether a Unix mount can be ejected.
41959 * Returns: %TRUE if @mount_entry is deemed to be ejectable.
41964 * g_unix_mount_guess_icon:
41965 * @mount_entry: a #GUnixMountEntry
41967 * Guesses the icon of a Unix mount.
41969 * Returns: (transfer full): a #GIcon
41974 * g_unix_mount_guess_name:
41975 * @mount_entry: a #GUnixMountEntry
41977 * Guesses the name of a Unix mount.
41978 * The result is a translated string.
41980 * Returns: A newly allocated string that must
41981 * be freed with g_free()
41986 * g_unix_mount_guess_should_display:
41987 * @mount_entry: a #GUnixMountEntry
41989 * Guesses whether a Unix mount should be displayed in the UI.
41991 * Returns: %TRUE if @mount_entry is deemed to be displayable.
41996 * g_unix_mount_guess_symbolic_icon:
41997 * @mount_entry: a #GUnixMountEntry
41999 * Guesses the symbolic icon of a Unix mount.
42001 * Returns: (transfer full): a #GIcon
42007 * g_unix_mount_guess_type:
42008 * @mount_entry: a #GUnixMount.
42010 * Guesses the type of a unix mount. If the mount type cannot be
42011 * determined, returns %G_UNIX_MOUNT_TYPE_UNKNOWN.
42013 * Returns: a #GUnixMountType.
42018 * g_unix_mount_is_readonly:
42019 * @mount_entry: a #GUnixMount.
42021 * Checks if a unix mount is mounted read only.
42023 * Returns: %TRUE if @mount_entry is read only.
42028 * g_unix_mount_is_system_internal:
42029 * @mount_entry: a #GUnixMount.
42031 * Checks if a Unix mount is a system mount. This is the Boolean OR of
42032 * g_unix_is_system_fs_type(), g_unix_is_system_device_path() and
42033 * g_unix_is_mount_path_system_internal() on @mount_entry’s properties.
42035 * The definition of what a ‘system’ mount entry is may change over time as new
42036 * file system types and device paths are ignored.
42038 * Returns: %TRUE if the unix mount is for a system path.
42043 * g_unix_mount_monitor_get:
42045 * Gets the #GUnixMountMonitor for the current thread-default main
42048 * The mount monitor can be used to monitor for changes to the list of
42049 * mounted filesystems as well as the list of mount points (ie: fstab
42052 * You must only call g_object_unref() on the return value from under
42053 * the same main context as you called this function.
42055 * Returns: (transfer full): the #GUnixMountMonitor.
42061 * g_unix_mount_monitor_new:
42063 * Deprecated alias for g_unix_mount_monitor_get().
42065 * This function was never a true constructor, which is why it was
42068 * Returns: a #GUnixMountMonitor.
42069 * Deprecated: 2.44: Use g_unix_mount_monitor_get() instead.
42074 * g_unix_mount_monitor_set_rate_limit:
42075 * @mount_monitor: a #GUnixMountMonitor
42076 * @limit_msec: a integer with the limit in milliseconds to
42077 * poll for changes.
42079 * This function does nothing.
42081 * Before 2.44, this was a partially-effective way of controlling the
42082 * rate at which events would be reported under some uncommon
42083 * circumstances. Since @mount_monitor is a singleton, it also meant
42084 * that calling this function would have side effects for other users of
42088 * Deprecated: 2.44: This function does nothing. Don't call it.
42093 * g_unix_mount_point_at:
42094 * @mount_path: (type filename): path for a possible unix mount point.
42095 * @time_read: (out) (optional): guint64 to contain a timestamp.
42097 * Gets a #GUnixMountPoint for a given mount path. If @time_read is set, it
42098 * will be filled with a unix timestamp for checking if the mount points have
42099 * changed since with g_unix_mount_points_changed_since().
42101 * If more mount points have the same mount path, the last matching mount point
42104 * Returns: (transfer full) (nullable): a #GUnixMountPoint, or %NULL if no match
42111 * g_unix_mount_point_compare:
42112 * @mount1: a #GUnixMount.
42113 * @mount2: a #GUnixMount.
42115 * Compares two unix mount points.
42117 * Returns: 1, 0 or -1 if @mount1 is greater than, equal to,
42118 * or less than @mount2, respectively.
42123 * g_unix_mount_point_copy:
42124 * @mount_point: a #GUnixMountPoint.
42126 * Makes a copy of @mount_point.
42128 * Returns: (transfer full): a new #GUnixMountPoint
42134 * g_unix_mount_point_free:
42135 * @mount_point: unix mount point to free.
42137 * Frees a unix mount point.
42142 * g_unix_mount_point_get_device_path:
42143 * @mount_point: a #GUnixMountPoint.
42145 * Gets the device path for a unix mount point.
42147 * Returns: (type filename): a string containing the device path.
42152 * g_unix_mount_point_get_fs_type:
42153 * @mount_point: a #GUnixMountPoint.
42155 * Gets the file system type for the mount point.
42157 * Returns: a string containing the file system type.
42162 * g_unix_mount_point_get_mount_path:
42163 * @mount_point: a #GUnixMountPoint.
42165 * Gets the mount path for a unix mount point.
42167 * Returns: (type filename): a string containing the mount path.
42172 * g_unix_mount_point_get_options:
42173 * @mount_point: a #GUnixMountPoint.
42175 * Gets the options for the mount point.
42177 * Returns: (nullable): a string containing the options.
42183 * g_unix_mount_point_guess_can_eject:
42184 * @mount_point: a #GUnixMountPoint
42186 * Guesses whether a Unix mount point can be ejected.
42188 * Returns: %TRUE if @mount_point is deemed to be ejectable.
42193 * g_unix_mount_point_guess_icon:
42194 * @mount_point: a #GUnixMountPoint
42196 * Guesses the icon of a Unix mount point.
42198 * Returns: (transfer full): a #GIcon
42203 * g_unix_mount_point_guess_name:
42204 * @mount_point: a #GUnixMountPoint
42206 * Guesses the name of a Unix mount point.
42207 * The result is a translated string.
42209 * Returns: A newly allocated string that must
42210 * be freed with g_free()
42215 * g_unix_mount_point_guess_symbolic_icon:
42216 * @mount_point: a #GUnixMountPoint
42218 * Guesses the symbolic icon of a Unix mount point.
42220 * Returns: (transfer full): a #GIcon
42226 * g_unix_mount_point_guess_type:
42227 * @mount_point: a #GUnixMountPoint.
42229 * Guesses the type of a unix mount point.
42230 * If the mount type cannot be determined,
42231 * returns %G_UNIX_MOUNT_TYPE_UNKNOWN.
42233 * Returns: a #GUnixMountType.
42238 * g_unix_mount_point_is_loopback:
42239 * @mount_point: a #GUnixMountPoint.
42241 * Checks if a unix mount point is a loopback device.
42243 * Returns: %TRUE if the mount point is a loopback. %FALSE otherwise.
42248 * g_unix_mount_point_is_readonly:
42249 * @mount_point: a #GUnixMountPoint.
42251 * Checks if a unix mount point is read only.
42253 * Returns: %TRUE if a mount point is read only.
42258 * g_unix_mount_point_is_user_mountable:
42259 * @mount_point: a #GUnixMountPoint.
42261 * Checks if a unix mount point is mountable by the user.
42263 * Returns: %TRUE if the mount point is user mountable.
42268 * g_unix_mount_points_changed_since:
42269 * @time: guint64 to contain a timestamp.
42271 * Checks if the unix mount points have changed since a given unix time.
42273 * Returns: %TRUE if the mount points have changed since @time.
42278 * g_unix_mount_points_get:
42279 * @time_read: (out) (optional): guint64 to contain a timestamp.
42281 * Gets a #GList of #GUnixMountPoint containing the unix mount points.
42282 * If @time_read is set, it will be filled with the mount timestamp,
42283 * allowing for checking if the mounts have changed with
42284 * g_unix_mount_points_changed_since().
42286 * Returns: (element-type GUnixMountPoint) (transfer full):
42287 * a #GList of the UNIX mountpoints.
42292 * g_unix_mounts_changed_since:
42293 * @time: guint64 to contain a timestamp.
42295 * Checks if the unix mounts have changed since a given unix time.
42297 * Returns: %TRUE if the mounts have changed since @time.
42302 * g_unix_mounts_get:
42303 * @time_read: (out) (optional): guint64 to contain a timestamp, or %NULL
42305 * Gets a #GList of #GUnixMountEntry containing the unix mounts.
42306 * If @time_read is set, it will be filled with the mount
42307 * timestamp, allowing for checking if the mounts have changed
42308 * with g_unix_mounts_changed_since().
42310 * Returns: (element-type GUnixMountEntry) (transfer full):
42311 * a #GList of the UNIX mounts.
42316 * g_unix_output_stream_get_close_fd:
42317 * @stream: a #GUnixOutputStream
42319 * Returns whether the file descriptor of @stream will be
42320 * closed when the stream is closed.
42322 * Returns: %TRUE if the file descriptor is closed when done
42328 * g_unix_output_stream_get_fd:
42329 * @stream: a #GUnixOutputStream
42331 * Return the UNIX file descriptor that the stream writes to.
42333 * Returns: The file descriptor of @stream
42339 * g_unix_output_stream_new:
42340 * @fd: a UNIX file descriptor
42341 * @close_fd: %TRUE to close the file descriptor when done
42343 * Creates a new #GUnixOutputStream for the given @fd.
42345 * If @close_fd, is %TRUE, the file descriptor will be closed when
42346 * the output stream is destroyed.
42348 * Returns: a new #GOutputStream
42353 * g_unix_output_stream_set_close_fd:
42354 * @stream: a #GUnixOutputStream
42355 * @close_fd: %TRUE to close the file descriptor when done
42357 * Sets whether the file descriptor of @stream shall be closed
42358 * when the stream is closed.
42365 * g_unix_socket_address_abstract_names_supported:
42367 * Checks if abstract UNIX domain socket names are supported.
42369 * Returns: %TRUE if supported, %FALSE otherwise
42375 * g_unix_socket_address_get_address_type:
42376 * @address: a #GInetSocketAddress
42378 * Gets @address's type.
42380 * Returns: a #GUnixSocketAddressType
42386 * g_unix_socket_address_get_is_abstract:
42387 * @address: a #GInetSocketAddress
42389 * Tests if @address is abstract.
42391 * Returns: %TRUE if the address is abstract, %FALSE otherwise
42393 * Deprecated: Use g_unix_socket_address_get_address_type()
42398 * g_unix_socket_address_get_path:
42399 * @address: a #GInetSocketAddress
42401 * Gets @address's path, or for abstract sockets the "name".
42403 * Guaranteed to be zero-terminated, but an abstract socket
42404 * may contain embedded zeros, and thus you should use
42405 * g_unix_socket_address_get_path_len() to get the true length
42408 * Returns: the path for @address
42414 * g_unix_socket_address_get_path_len:
42415 * @address: a #GInetSocketAddress
42417 * Gets the length of @address's path.
42419 * For details, see g_unix_socket_address_get_path().
42421 * Returns: the length of the path
42427 * g_unix_socket_address_new:
42428 * @path: the socket path
42430 * Creates a new #GUnixSocketAddress for @path.
42432 * To create abstract socket addresses, on systems that support that,
42433 * use g_unix_socket_address_new_abstract().
42435 * Returns: a new #GUnixSocketAddress
42441 * g_unix_socket_address_new_abstract:
42442 * @path: (array length=path_len) (element-type gchar): the abstract name
42443 * @path_len: the length of @path, or -1
42445 * Creates a new %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED
42446 * #GUnixSocketAddress for @path.
42448 * Returns: a new #GUnixSocketAddress
42449 * Deprecated: Use g_unix_socket_address_new_with_type().
42454 * g_unix_socket_address_new_with_type:
42455 * @path: (array length=path_len) (element-type gchar): the name
42456 * @path_len: the length of @path, or -1
42457 * @type: a #GUnixSocketAddressType
42459 * Creates a new #GUnixSocketAddress of type @type with name @path.
42461 * If @type is %G_UNIX_SOCKET_ADDRESS_PATH, this is equivalent to
42462 * calling g_unix_socket_address_new().
42464 * If @type is %G_UNIX_SOCKET_ADDRESS_ANONYMOUS, @path and @path_len will be
42467 * If @path_type is %G_UNIX_SOCKET_ADDRESS_ABSTRACT, then @path_len
42468 * bytes of @path will be copied to the socket's path, and only those
42469 * bytes will be considered part of the name. (If @path_len is -1,
42470 * then @path is assumed to be NUL-terminated.) For example, if @path
42471 * was "test", then calling g_socket_address_get_native_size() on the
42472 * returned socket would return 7 (2 bytes of overhead, 1 byte for the
42473 * abstract-socket indicator byte, and 4 bytes for the name "test").
42475 * If @path_type is %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED, then
42476 * @path_len bytes of @path will be copied to the socket's path, the
42477 * rest of the path will be padded with 0 bytes, and the entire
42478 * zero-padded buffer will be considered the name. (As above, if
42479 * @path_len is -1, then @path is assumed to be NUL-terminated.) In
42480 * this case, g_socket_address_get_native_size() will always return
42481 * the full size of a `struct sockaddr_un`, although
42482 * g_unix_socket_address_get_path_len() will still return just the
42485 * %G_UNIX_SOCKET_ADDRESS_ABSTRACT is preferred over
42486 * %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED for new programs. Of course,
42487 * when connecting to a server created by another process, you must
42488 * use the appropriate type corresponding to how that process created
42489 * its listening socket.
42491 * Returns: a new #GUnixSocketAddress
42497 * g_vfs_get_default:
42499 * Gets the default #GVfs for the system.
42501 * Returns: (not nullable) (transfer none): a #GVfs, which will be the local
42502 * file system #GVfs if no other implementation is available.
42507 * g_vfs_get_file_for_path:
42509 * @path: a string containing a VFS path.
42511 * Gets a #GFile for @path.
42513 * Returns: (transfer full): a #GFile.
42514 * Free the returned object with g_object_unref().
42519 * g_vfs_get_file_for_uri:
42521 * @uri: a string containing a URI
42523 * Gets a #GFile for @uri.
42525 * This operation never fails, but the returned object
42526 * might not support any I/O operation if the URI
42527 * is malformed or if the URI scheme is not supported.
42529 * Returns: (transfer full): a #GFile.
42530 * Free the returned object with g_object_unref().
42537 * Gets the local #GVfs for the system.
42539 * Returns: (transfer none): a #GVfs.
42544 * g_vfs_get_supported_uri_schemes:
42547 * Gets a list of URI schemes supported by @vfs.
42549 * Returns: (transfer none): a %NULL-terminated array of strings.
42550 * The returned array belongs to GIO and must
42551 * not be freed or modified.
42559 * Checks if the VFS is active.
42561 * Returns: %TRUE if construction of the @vfs was successful
42562 * and it is now active.
42567 * g_vfs_parse_name:
42569 * @parse_name: a string to be parsed by the VFS module.
42571 * This operation never fails, but the returned object might
42572 * not support any I/O operations if the @parse_name cannot
42573 * be parsed by the #GVfs module.
42575 * Returns: (transfer full): a #GFile for the given @parse_name.
42576 * Free the returned object with g_object_unref().
42581 * g_vfs_register_uri_scheme:
42583 * @scheme: an URI scheme, e.g. "http"
42584 * @uri_func: (scope notified) (nullable): a #GVfsFileLookupFunc
42585 * @uri_data: (nullable): custom data passed to be passed to @uri_func, or %NULL
42586 * @uri_destroy: (nullable): function to be called when unregistering the
42587 * URI scheme, or when @vfs is disposed, to free the resources used
42588 * by the URI lookup function
42589 * @parse_name_func: (scope notified) (nullable): a #GVfsFileLookupFunc
42590 * @parse_name_data: (nullable): custom data passed to be passed to
42591 * @parse_name_func, or %NULL
42592 * @parse_name_destroy: (nullable): function to be called when unregistering the
42593 * URI scheme, or when @vfs is disposed, to free the resources used
42594 * by the parse name lookup function
42596 * Registers @uri_func and @parse_name_func as the #GFile URI and parse name
42597 * lookup functions for URIs with a scheme matching @scheme.
42598 * Note that @scheme is registered only within the running application, as
42599 * opposed to desktop-wide as it happens with GVfs backends.
42601 * When a #GFile is requested with an URI containing @scheme (e.g. through
42602 * g_file_new_for_uri()), @uri_func will be called to allow a custom
42603 * constructor. The implementation of @uri_func should not be blocking, and
42604 * must not call g_vfs_register_uri_scheme() or g_vfs_unregister_uri_scheme().
42606 * When g_file_parse_name() is called with a parse name obtained from such file,
42607 * @parse_name_func will be called to allow the #GFile to be created again. In
42608 * that case, it's responsibility of @parse_name_func to make sure the parse
42609 * name matches what the custom #GFile implementation returned when
42610 * g_file_get_parse_name() was previously called. The implementation of
42611 * @parse_name_func should not be blocking, and must not call
42612 * g_vfs_register_uri_scheme() or g_vfs_unregister_uri_scheme().
42614 * It's an error to call this function twice with the same scheme. To unregister
42615 * a custom URI scheme, use g_vfs_unregister_uri_scheme().
42617 * Returns: %TRUE if @scheme was successfully registered, or %FALSE if a handler
42618 * for @scheme already exists.
42624 * g_vfs_unregister_uri_scheme:
42626 * @scheme: an URI scheme, e.g. "http"
42628 * Unregisters the URI handler for @scheme previously registered with
42629 * g_vfs_register_uri_scheme().
42631 * Returns: %TRUE if @scheme was successfully unregistered, or %FALSE if a
42632 * handler for @scheme does not exist.
42638 * g_volume_can_eject:
42639 * @volume: a #GVolume
42641 * Checks if a volume can be ejected.
42643 * Returns: %TRUE if the @volume can be ejected. %FALSE otherwise
42648 * g_volume_can_mount:
42649 * @volume: a #GVolume
42651 * Checks if a volume can be mounted.
42653 * Returns: %TRUE if the @volume can be mounted. %FALSE otherwise
42659 * @volume: a #GVolume
42660 * @flags: flags affecting the unmount if required for eject
42661 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore
42662 * @callback: (nullable): a #GAsyncReadyCallback, or %NULL
42663 * @user_data: user data that gets passed to @callback
42665 * Ejects a volume. This is an asynchronous operation, and is
42666 * finished by calling g_volume_eject_finish() with the @volume
42667 * and #GAsyncResult returned in the @callback.
42669 * Deprecated: 2.22: Use g_volume_eject_with_operation() instead.
42674 * g_volume_eject_finish:
42675 * @volume: pointer to a #GVolume
42676 * @result: a #GAsyncResult
42677 * @error: a #GError location to store an error, or %NULL to ignore
42679 * Finishes ejecting a volume. If any errors occurred during the operation,
42680 * @error will be set to contain the errors and %FALSE will be returned.
42682 * Returns: %TRUE, %FALSE if operation failed
42683 * Deprecated: 2.22: Use g_volume_eject_with_operation_finish() instead.
42688 * g_volume_eject_with_operation:
42689 * @volume: a #GVolume
42690 * @flags: flags affecting the unmount if required for eject
42691 * @mount_operation: (nullable): a #GMountOperation or %NULL to
42692 * avoid user interaction
42693 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore
42694 * @callback: (nullable): a #GAsyncReadyCallback, or %NULL
42695 * @user_data: user data passed to @callback
42697 * Ejects a volume. This is an asynchronous operation, and is
42698 * finished by calling g_volume_eject_with_operation_finish() with the @volume
42699 * and #GAsyncResult data returned in the @callback.
42706 * g_volume_eject_with_operation_finish:
42707 * @volume: a #GVolume
42708 * @result: a #GAsyncResult
42709 * @error: a #GError location to store the error occurring, or %NULL
42711 * Finishes ejecting a volume. If any errors occurred during the operation,
42712 * @error will be set to contain the errors and %FALSE will be returned.
42714 * Returns: %TRUE if the volume was successfully ejected. %FALSE otherwise
42720 * g_volume_enumerate_identifiers:
42721 * @volume: a #GVolume
42723 * Gets the kinds of [identifiers][volume-identifier] that @volume has.
42724 * Use g_volume_get_identifier() to obtain the identifiers themselves.
42726 * Returns: (array zero-terminated=1) (transfer full): a %NULL-terminated array
42727 * of strings containing kinds of identifiers. Use g_strfreev() to free.
42732 * g_volume_get_activation_root:
42733 * @volume: a #GVolume
42735 * Gets the activation root for a #GVolume if it is known ahead of
42736 * mount time. Returns %NULL otherwise. If not %NULL and if @volume
42737 * is mounted, then the result of g_mount_get_root() on the
42738 * #GMount object obtained from g_volume_get_mount() will always
42739 * either be equal or a prefix of what this function returns. In
42740 * other words, in code
42742 * |[<!-- language="C" -->
42744 * GFile *mount_root
42745 * GFile *volume_activation_root;
42747 * mount = g_volume_get_mount (volume); // mounted, so never NULL
42748 * mount_root = g_mount_get_root (mount);
42749 * volume_activation_root = g_volume_get_activation_root (volume); // assume not NULL
42751 * then the expression
42752 * |[<!-- language="C" -->
42753 * (g_file_has_prefix (volume_activation_root, mount_root) ||
42754 * g_file_equal (volume_activation_root, mount_root))
42756 * will always be %TRUE.
42758 * Activation roots are typically used in #GVolumeMonitor
42759 * implementations to find the underlying mount to shadow, see
42760 * g_mount_is_shadowed() for more details.
42762 * Returns: (nullable) (transfer full): the activation root of @volume
42763 * or %NULL. Use g_object_unref() to free.
42769 * g_volume_get_drive:
42770 * @volume: a #GVolume
42772 * Gets the drive for the @volume.
42774 * Returns: (transfer full) (nullable): a #GDrive or %NULL if @volume is not
42775 * associated with a drive. The returned object should be unreffed
42776 * with g_object_unref() when no longer needed.
42781 * g_volume_get_icon:
42782 * @volume: a #GVolume
42784 * Gets the icon for @volume.
42786 * Returns: (transfer full): a #GIcon.
42787 * The returned object should be unreffed with g_object_unref()
42788 * when no longer needed.
42793 * g_volume_get_identifier:
42794 * @volume: a #GVolume
42795 * @kind: the kind of identifier to return
42797 * Gets the identifier of the given kind for @volume.
42798 * See the [introduction][volume-identifier] for more
42799 * information about volume identifiers.
42801 * Returns: (nullable) (transfer full): a newly allocated string containing the
42802 * requested identifier, or %NULL if the #GVolume
42803 * doesn't have this kind of identifier
42808 * g_volume_get_mount:
42809 * @volume: a #GVolume
42811 * Gets the mount for the @volume.
42813 * Returns: (transfer full) (nullable): a #GMount or %NULL if @volume isn't mounted.
42814 * The returned object should be unreffed with g_object_unref()
42815 * when no longer needed.
42820 * g_volume_get_name:
42821 * @volume: a #GVolume
42823 * Gets the name of @volume.
42825 * Returns: the name for the given @volume. The returned string should
42826 * be freed with g_free() when no longer needed.
42831 * g_volume_get_sort_key:
42832 * @volume: a #GVolume
42834 * Gets the sort key for @volume, if any.
42836 * Returns: (nullable): Sorting key for @volume or %NULL if no such key is available
42842 * g_volume_get_symbolic_icon:
42843 * @volume: a #GVolume
42845 * Gets the symbolic icon for @volume.
42847 * Returns: (transfer full): a #GIcon.
42848 * The returned object should be unreffed with g_object_unref()
42849 * when no longer needed.
42855 * g_volume_get_uuid:
42856 * @volume: a #GVolume
42858 * Gets the UUID for the @volume. The reference is typically based on
42859 * the file system UUID for the volume in question and should be
42860 * considered an opaque string. Returns %NULL if there is no UUID
42863 * Returns: (nullable) (transfer full): the UUID for @volume or %NULL if no UUID
42865 * The returned string should be freed with g_free()
42866 * when no longer needed.
42871 * g_volume_monitor_adopt_orphan_mount:
42872 * @mount: a #GMount object to find a parent for
42874 * This function should be called by any #GVolumeMonitor
42875 * implementation when a new #GMount object is created that is not
42876 * associated with a #GVolume object. It must be called just before
42877 * emitting the @mount_added signal.
42879 * If the return value is not %NULL, the caller must associate the
42880 * returned #GVolume object with the #GMount. This involves returning
42881 * it in its g_mount_get_volume() implementation. The caller must
42882 * also listen for the "removed" signal on the returned object
42883 * and give up its reference when handling that signal
42885 * Similarly, if implementing g_volume_monitor_adopt_orphan_mount(),
42886 * the implementor must take a reference to @mount and return it in
42887 * its g_volume_get_mount() implemented. Also, the implementor must
42888 * listen for the "unmounted" signal on @mount and give up its
42889 * reference upon handling that signal.
42891 * There are two main use cases for this function.
42893 * One is when implementing a user space file system driver that reads
42894 * blocks of a block device that is already represented by the native
42895 * volume monitor (for example a CD Audio file system driver). Such
42896 * a driver will generate its own #GMount object that needs to be
42897 * associated with the #GVolume object that represents the volume.
42899 * The other is for implementing a #GVolumeMonitor whose sole purpose
42900 * is to return #GVolume objects representing entries in the users
42901 * "favorite servers" list or similar.
42903 * Returns: (transfer full): the #GVolume object that is the parent for @mount or %NULL
42904 * if no wants to adopt the #GMount.
42905 * Deprecated: 2.20: Instead of using this function, #GVolumeMonitor
42906 * implementations should instead create shadow mounts with the URI of
42907 * the mount they intend to adopt. See the proxy volume monitor in
42908 * gvfs for an example of this. Also see g_mount_is_shadowed(),
42909 * g_mount_shadow() and g_mount_unshadow() functions.
42914 * g_volume_monitor_get:
42916 * Gets the volume monitor used by gio.
42918 * Returns: (transfer full): a reference to the #GVolumeMonitor used by gio. Call
42919 * g_object_unref() when done with it.
42924 * g_volume_monitor_get_connected_drives:
42925 * @volume_monitor: a #GVolumeMonitor.
42927 * Gets a list of drives connected to the system.
42929 * The returned list should be freed with g_list_free(), after
42930 * its elements have been unreffed with g_object_unref().
42932 * Returns: (element-type GDrive) (transfer full): a #GList of connected #GDrive objects.
42937 * g_volume_monitor_get_mount_for_uuid:
42938 * @volume_monitor: a #GVolumeMonitor.
42939 * @uuid: the UUID to look for
42941 * Finds a #GMount object by its UUID (see g_mount_get_uuid())
42943 * Returns: (nullable) (transfer full): a #GMount or %NULL if no such mount is available.
42944 * Free the returned object with g_object_unref().
42949 * g_volume_monitor_get_mounts:
42950 * @volume_monitor: a #GVolumeMonitor.
42952 * Gets a list of the mounts on the system.
42954 * The returned list should be freed with g_list_free(), after
42955 * its elements have been unreffed with g_object_unref().
42957 * Returns: (element-type GMount) (transfer full): a #GList of #GMount objects.
42962 * g_volume_monitor_get_volume_for_uuid:
42963 * @volume_monitor: a #GVolumeMonitor.
42964 * @uuid: the UUID to look for
42966 * Finds a #GVolume object by its UUID (see g_volume_get_uuid())
42968 * Returns: (nullable) (transfer full): a #GVolume or %NULL if no such volume is available.
42969 * Free the returned object with g_object_unref().
42974 * g_volume_monitor_get_volumes:
42975 * @volume_monitor: a #GVolumeMonitor.
42977 * Gets a list of the volumes on the system.
42979 * The returned list should be freed with g_list_free(), after
42980 * its elements have been unreffed with g_object_unref().
42982 * Returns: (element-type GVolume) (transfer full): a #GList of #GVolume objects.
42987 * g_volume_mount: (virtual mount_fn)
42988 * @volume: a #GVolume
42989 * @flags: flags affecting the operation
42990 * @mount_operation: (nullable): a #GMountOperation or %NULL to avoid user interaction
42991 * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore
42992 * @callback: (nullable): a #GAsyncReadyCallback, or %NULL
42993 * @user_data: user data that gets passed to @callback
42995 * Mounts a volume. This is an asynchronous operation, and is
42996 * finished by calling g_volume_mount_finish() with the @volume
42997 * and #GAsyncResult returned in the @callback.
43002 * g_volume_mount_finish:
43003 * @volume: a #GVolume
43004 * @result: a #GAsyncResult
43005 * @error: a #GError location to store an error, or %NULL to ignore
43007 * Finishes mounting a volume. If any errors occurred during the operation,
43008 * @error will be set to contain the errors and %FALSE will be returned.
43010 * If the mount operation succeeded, g_volume_get_mount() on @volume
43011 * is guaranteed to return the mount right after calling this
43012 * function; there's no need to listen for the 'mount-added' signal on
43015 * Returns: %TRUE, %FALSE if operation failed
43020 * g_volume_should_automount:
43021 * @volume: a #GVolume
43023 * Returns whether the volume should be automatically mounted.
43025 * Returns: %TRUE if the volume should be automatically mounted
43030 * g_win32_file_sync_stream_new:
43031 * @handle: a Win32 HANDLE for a file.
43032 * @owns_handle: %TRUE if newly-created stream owns the handle
43033 * (and closes it when destroyed)
43034 * @stgm_mode: a combination of [STGM constants](https://docs.microsoft.com/en-us/windows/win32/stg/stgm-constants)
43035 * that specify the mode with which the stream
43037 * @output_hresult: (out) (optional): a HRESULT from the internal COM calls.
43038 * Will be `S_OK` on success.
43040 * Creates an IStream object backed by a HANDLE.
43042 * @stgm_mode should match the mode of the @handle, otherwise the stream might
43043 * attempt to perform operations that the @handle does not allow. The implementation
43044 * itself ignores these flags completely, they are only used to report
43045 * the mode of the stream to third parties.
43047 * The stream only does synchronous access and will never return `E_PENDING` on I/O.
43049 * The returned stream object should be treated just like any other
43050 * COM object, and released via `IUnknown_Release()`.
43051 * its elements have been unreffed with g_object_unref().
43053 * Returns: (nullable) (transfer full): a new IStream object on success, %NULL on failure.
43058 * g_win32_input_stream_get_close_handle:
43059 * @stream: a #GWin32InputStream
43061 * Returns whether the handle of @stream will be
43062 * closed when the stream is closed.
43064 * Returns: %TRUE if the handle is closed when done
43070 * g_win32_input_stream_get_handle:
43071 * @stream: a #GWin32InputStream
43073 * Return the Windows file handle that the stream reads from.
43075 * Returns: The file handle of @stream
43081 * g_win32_input_stream_new:
43082 * @handle: a Win32 file handle
43083 * @close_handle: %TRUE to close the handle when done
43085 * Creates a new #GWin32InputStream for the given @handle.
43087 * If @close_handle is %TRUE, the handle will be closed
43088 * when the stream is closed.
43090 * Note that "handle" here means a Win32 HANDLE, not a "file descriptor"
43091 * as used in the Windows C libraries.
43093 * Returns: a new #GWin32InputStream
43098 * g_win32_input_stream_set_close_handle:
43099 * @stream: a #GWin32InputStream
43100 * @close_handle: %TRUE to close the handle when done
43102 * Sets whether the handle of @stream shall be closed
43103 * when the stream is closed.
43110 * g_win32_output_stream_get_close_handle:
43111 * @stream: a #GWin32OutputStream
43113 * Returns whether the handle of @stream will be closed when the
43114 * stream is closed.
43116 * Returns: %TRUE if the handle is closed when done
43122 * g_win32_output_stream_get_handle:
43123 * @stream: a #GWin32OutputStream
43125 * Return the Windows handle that the stream writes to.
43127 * Returns: The handle descriptor of @stream
43133 * g_win32_output_stream_new:
43134 * @handle: a Win32 file handle
43135 * @close_handle: %TRUE to close the handle when done
43137 * Creates a new #GWin32OutputStream for the given @handle.
43139 * If @close_handle, is %TRUE, the handle will be closed when the
43140 * output stream is destroyed.
43142 * Returns: a new #GOutputStream
43148 * g_win32_output_stream_set_close_handle:
43149 * @stream: a #GWin32OutputStream
43150 * @close_handle: %TRUE to close the handle when done
43152 * Sets whether the handle of @stream shall be closed when the stream
43160 * g_win32_registry_get_os_dirs:
43162 * Returns a list of directories for DLL lookups.
43163 * Can be used with g_win32_registry_key_get_value().
43165 * Returns: (array zero-terminated=1) (transfer none): a %NULL-terminated array of UTF-8 strings.
43171 * g_win32_registry_get_os_dirs_w:
43173 * Returns a list of directories for DLL lookups.
43174 * Can be used with g_win32_registry_key_get_value_w().
43176 * Returns: (array zero-terminated=1) (transfer none): a %NULL-terminated array of UTF-16 strings.
43182 * g_win32_registry_key_erase_change_indicator:
43183 * @key: (in) (transfer none): a #GWin32RegistryKey
43185 * Erases change indicator of the @key.
43187 * Subsequent calls to g_win32_registry_key_has_changed() will return %FALSE
43188 * until the key is put on watch again by calling
43189 * g_win32_registry_key_watch() again.
43196 * g_win32_registry_key_get_child:
43197 * @key: (in) (transfer none): a parent #GWin32RegistryKey
43198 * @subkey: (in) (transfer none): name of a child key to open (in UTF-8), relative to @key
43199 * @error: (inout) (optional) (nullable): a pointer to a %NULL #GError, or %NULL
43201 * Opens a @subkey of the @key.
43203 * Returns: (nullable): a #GWin32RegistryKey or %NULL if can't be opened. Free
43204 * with g_object_unref().
43209 * g_win32_registry_key_get_child_w:
43210 * @key: (in) (transfer none): a parent #GWin32RegistryKey
43211 * @subkey: (in) (transfer none): name of a child key to open (in UTF-8), relative to @key
43212 * @error: (inout) (optional) (nullable): a pointer to a %NULL #GError, or %NULL
43214 * Opens a @subkey of the @key.
43216 * Returns: (nullable): a #GWin32RegistryKey or %NULL if can't be opened. Free
43217 * with g_object_unref().
43222 * g_win32_registry_key_get_path:
43223 * @key: (in) (transfer none): a #GWin32RegistryKey
43225 * Get full path to the key
43227 * Returns: (transfer none): a full path to the key (in UTF-8),
43228 * or %NULL if it can't be converted to UTF-8.
43234 * g_win32_registry_key_get_path_w:
43235 * @key: (in) (transfer none): a #GWin32RegistryKey
43237 * Get full path to the key
43239 * Returns: (transfer none): a full path to the key (in UTF-16)
43245 * g_win32_registry_key_get_value:
43246 * @key: (in) (transfer none): a #GWin32RegistryKey
43247 * @mui_dll_dirs: (in) (transfer none) (array zero-terminated=1) (optional): a %NULL-terminated
43248 * array of directory names where the OS
43249 * should look for a DLL indicated in a MUI string, if the
43250 * DLL path in the string is not absolute
43251 * @auto_expand: (in): %TRUE to automatically expand G_WIN32_REGISTRY_VALUE_EXPAND_STR
43252 * to G_WIN32_REGISTRY_VALUE_STR.
43253 * @value_name: (in) (transfer none): name of the value to get (in UTF-8).
43254 * Empty string means the '(Default)' value.
43255 * @value_type: (out) (optional): type of the value retrieved.
43256 * @value_data: (out callee-allocates) (optional): contents of the value.
43257 * @value_data_size: (out) (optional): size of the buffer pointed
43259 * @error: (nullable): a pointer to %NULL #GError, or %NULL
43261 * Get data from a value of a key. String data is guaranteed to be
43262 * appropriately terminated and will be in UTF-8.
43264 * When not %NULL, @mui_dll_dirs indicates that `RegLoadMUIStringW()` API
43265 * should be used instead of the usual `RegQueryValueExW()`. This implies
43266 * that the value being queried is of type `REG_SZ` or `REG_EXPAND_SZ` (if it is not, the function
43267 * falls back to `RegQueryValueExW()`), and that this string must undergo special processing
43268 * (see [`SHLoadIndirectString()` documentation](https://docs.microsoft.com/en-us/windows/win32/api/shlwapi/nf-shlwapi-shloadindirectstring) for an explanation on what
43269 * kinds of strings are processed) to get the result.
43271 * If no specific MUI DLL directories need to be used, pass
43272 * the return value of g_win32_registry_get_os_dirs() as @mui_dll_dirs
43273 * (as an bonus, the value from g_win32_registry_get_os_dirs()
43274 * does not add any extra UTF8->UTF16 conversion overhead).
43276 * @auto_expand works with @mui_dll_dirs, but only affects the processed
43277 * string, making it somewhat useless. The unprocessed string is always expanded
43278 * internally, if its type is `REG_EXPAND_SZ` - there is no need to enable
43279 * @auto_expand for this to work.
43281 * The API for this function changed in GLib 2.66 to add the @mui_dll_dirs argument.
43283 * Returns: %TRUE on success, %FALSE on failure.
43289 * g_win32_registry_key_get_value_w:
43290 * @key: (in) (transfer none): a #GWin32RegistryKey
43291 * @mui_dll_dirs: (in) (transfer none) (array zero-terminated=1) (optional): a %NULL-terminated
43292 * array of directory names where the OS
43293 * should look for a DLL indicated in a MUI string, if the
43294 * DLL path in the string is not absolute
43295 * @auto_expand: (in): %TRUE to automatically expand G_WIN32_REGISTRY_VALUE_EXPAND_STR
43296 * to G_WIN32_REGISTRY_VALUE_STR.
43297 * @value_name: (in) (transfer none): name of the value to get (in UTF-16).
43298 * Empty string means the '(Default)' value.
43299 * @value_type: (out) (optional): type of the value retrieved.
43300 * @value_data: (out callee-allocates) (optional): contents of the value.
43301 * @value_data_size: (out) (optional): size of the buffer pointed
43303 * @error: (nullable): a pointer to %NULL #GError, or %NULL
43305 * Get data from a value of a key. String data is guaranteed to be
43306 * appropriately terminated and will be in UTF-16.
43308 * When calling with value_data == NULL (to get data size without getting
43309 * the data itself) remember that returned size corresponds to possibly
43310 * unterminated string data (if value is some kind of string), because
43311 * termination cannot be checked and fixed unless the data is retrieved
43314 * When not %NULL, @mui_dll_dirs indicates that `RegLoadMUIStringW()` API
43315 * should be used instead of the usual `RegQueryValueExW()`. This implies
43316 * that the value being queried is of type `REG_SZ` or `REG_EXPAND_SZ` (if it is not, the function
43317 * falls back to `RegQueryValueExW()`), and that this string must undergo special processing
43318 * (see [`SHLoadIndirectString()` documentation](https://docs.microsoft.com/en-us/windows/win32/api/shlwapi/nf-shlwapi-shloadindirectstring) for an explanation on what
43319 * kinds of strings are processed) to get the result.
43321 * If no specific MUI DLL directories need to be used, pass
43322 * the return value of g_win32_registry_get_os_dirs_w() as @mui_dll_dirs.
43324 * @auto_expand works with @mui_dll_dirs, but only affects the processed
43325 * string, making it somewhat useless. The unprocessed string is always expanded
43326 * internally, if its type is `REG_EXPAND_SZ` - there is no need to enable
43327 * @auto_expand for this to work.
43329 * The API for this function changed in GLib 2.66 to add the @mui_dll_dirs argument.
43331 * Returns: %TRUE on success, %FALSE on failure.
43337 * g_win32_registry_key_has_changed:
43338 * @key: (in) (transfer none): a #GWin32RegistryKey
43340 * Check the @key's status indicator.
43342 * Returns: %TRUE if the @key was put under watch at some point and has changed
43343 * since then, %FALSE if it either wasn't changed or wasn't watched at all.
43349 * g_win32_registry_key_new:
43350 * @path: absolute full name of a key to open (in UTF-8)
43351 * @error: (nullable): a pointer to a %NULL #GError, or %NULL
43353 * Creates an object that represents a registry key specified by @path.
43354 * @path must start with one of the following pre-defined names:
43355 * - HKEY_CLASSES_ROOT
43356 * - HKEY_CURRENT_CONFIG
43357 * - HKEY_CURRENT_USER
43358 * - HKEY_CURRENT_USER_LOCAL_SETTINGS
43359 * - HKEY_LOCAL_MACHINE
43360 * - HKEY_PERFORMANCE_DATA
43361 * - HKEY_PERFORMANCE_NLSTEXT
43362 * - HKEY_PERFORMANCE_TEXT
43364 * @path must not end with '\\'.
43366 * Returns: (nullable) (transfer full): a #GWin32RegistryKey or %NULL if can't
43367 * be opened. Free with g_object_unref().
43372 * g_win32_registry_key_new_w:
43373 * @path: (in) (transfer none): absolute full name of a key to open (in UTF-16)
43374 * @error: (inout) (optional) (nullable): a pointer to a %NULL #GError, or %NULL
43376 * Creates an object that represents a registry key specified by @path.
43377 * @path must start with one of the following pre-defined names:
43378 * - HKEY_CLASSES_ROOT
43379 * - HKEY_CURRENT_CONFIG
43380 * - HKEY_CURRENT_USER
43381 * - HKEY_CURRENT_USER_LOCAL_SETTINGS
43382 * - HKEY_LOCAL_MACHINE
43383 * - HKEY_PERFORMANCE_DATA
43384 * - HKEY_PERFORMANCE_NLSTEXT
43385 * - HKEY_PERFORMANCE_TEXT
43387 * @path must not end with L'\\'.
43389 * Returns: (nullable) (transfer full): a #GWin32RegistryKey or %NULL if can't
43390 * be opened. Free with g_object_unref().
43395 * g_win32_registry_key_watch:
43396 * @key: (in) (transfer none): a #GWin32RegistryKey
43397 * @watch_children: (in): %TRUE also watch the children of the @key, %FALSE
43398 * to watch the key only.
43399 * @watch_flags: (in): specifies the types of changes to watch for.
43400 * @callback: (in) (nullable): a function to invoke when a change occurs.
43401 * @user_data: (in) (nullable): a pointer to pass to @callback on invocation.
43402 * @error: (nullable): a pointer to %NULL #GError, or %NULL
43404 * Puts @key under a watch.
43406 * When the key changes, an APC will be queued in the current thread. The APC
43407 * will run when the current thread enters alertable state (GLib main loop
43408 * should do that; if you are not using it, see MSDN documentation for W32API
43409 * calls that put thread into alertable state). When it runs, it will
43410 * atomically switch an indicator in the @key. If a callback was specified,
43411 * it is invoked at that point. Subsequent calls to
43412 * g_win32_registry_key_has_changed() will return %TRUE, and the callback (if
43413 * it was specified) will not be invoked anymore.
43414 * Calling g_win32_registry_key_erase_change_indicator() will reset the indicator,
43415 * and g_win32_registry_key_has_changed() will start returning %FALSE.
43416 * To resume the watch, call g_win32_registry_key_watch_for_changes() again.
43418 * Calling g_win32_registry_key_watch_for_changes() for a key that is already
43419 * being watched is allowed and affects nothing.
43421 * The fact that the key is being watched will be used internally to update
43422 * key path (if it changes).
43424 * Returns: %TRUE on success, %FALSE on failure.
43430 * g_win32_registry_subkey_iter_assign:
43431 * @iter: a #GWin32RegistrySubkeyIter
43432 * @other: another #GWin32RegistrySubkeyIter
43434 * Assigns the value of @other to @iter. This function
43435 * is not useful in applications, because iterators can be assigned
43436 * with `GWin32RegistrySubkeyIter i = j;`. The
43437 * function is used by language bindings.
43444 * g_win32_registry_subkey_iter_clear:
43445 * @iter: (in) (transfer none): a #GWin32RegistrySubkeyIter
43447 * Frees internal buffers of a #GWin32RegistrySubkeyIter.
43454 * g_win32_registry_subkey_iter_copy:
43455 * @iter: an iterator
43457 * Creates a dynamically-allocated copy of an iterator. Dynamically-allocated
43458 * state of the iterator is duplicated too.
43460 * Returns: (transfer full): a copy of the @iter,
43461 * free with g_win32_registry_subkey_iter_free ()
43467 * g_win32_registry_subkey_iter_free:
43468 * @iter: a dynamically-allocated iterator
43470 * Free an iterator allocated on the heap. For iterators that are allocated
43471 * on the stack use g_win32_registry_subkey_iter_clear () instead.
43478 * g_win32_registry_subkey_iter_get_name:
43479 * @iter: (in) (transfer none): a #GWin32RegistrySubkeyIter
43480 * @subkey_name: (out callee-allocates) (transfer none): Pointer to a location
43481 * to store the name of a subkey (in UTF-8). Free with g_free().
43482 * @subkey_name_len: (out) (optional): Pointer to a location to store the
43483 * length of @subkey_name, in gchars, excluding NUL-terminator.
43484 * %NULL if length is not needed.
43485 * @error: (nullable): a pointer to %NULL #GError, or %NULL
43487 * Gets the name of the subkey at the @iter potision.
43489 * Returns: %TRUE if the name was retrieved, %FALSE otherwise.
43495 * g_win32_registry_subkey_iter_get_name_w:
43496 * @iter: (in) (transfer none): a #GWin32RegistrySubkeyIter
43497 * @subkey_name: (out callee-allocates) (transfer none): Pointer to a location
43498 * to store the name of a subkey (in UTF-16).
43499 * @subkey_name_len: (out) (optional) (transfer none): Pointer to a location
43500 * to store the length of @subkey_name, in gunichar2s, excluding
43502 * %NULL if length is not needed.
43503 * @error: (nullable): a pointer to %NULL #GError, or %NULL
43505 * Same as g_win32_registry_subkey_iter_get_next(), but outputs UTF-16-encoded
43506 * data, without converting it to UTF-8 first.
43508 * Returns: %TRUE if the name was retrieved, %FALSE otherwise.
43514 * g_win32_registry_subkey_iter_init:
43515 * @iter: (in) (transfer none): a pointer to a #GWin32RegistrySubkeyIter
43516 * @key: (in) (transfer none): a #GWin32RegistryKey to iterate over
43517 * @error: (inout) (optional) (nullable): a pointer to %NULL #GError, or %NULL
43519 * Initialises (without allocating) a #GWin32RegistrySubkeyIter. @iter may be
43520 * completely uninitialised prior to this call; its old value is
43523 * The iterator remains valid for as long as @key exists.
43524 * Clean up its internal buffers with a call to
43525 * g_win32_registry_subkey_iter_clear() when done.
43527 * Returns: %TRUE if iterator was initialized successfully, %FALSE on error.
43533 * g_win32_registry_subkey_iter_n_subkeys:
43534 * @iter: (in) (transfer none): a #GWin32RegistrySubkeyIter
43536 * Queries the number of subkeys items in the key that we are
43537 * iterating over. This is the total number of subkeys -- not the number
43538 * of items remaining.
43540 * This information is accurate at the point of iterator initialization,
43541 * and may go out of sync with reality even while subkeys are enumerated.
43543 * Returns: the number of subkeys in the key
43549 * g_win32_registry_subkey_iter_next:
43550 * @iter: (in) (transfer none): a #GWin32RegistrySubkeyIter
43551 * @skip_errors: (in): %TRUE if iterator should silently ignore errors (such as
43552 * the actual number of subkeys being less than expected) and
43554 * @error: (nullable): a pointer to %NULL #GError, or %NULL
43556 * Moves iterator to the next subkey.
43557 * Enumeration errors can be ignored if @skip_errors is %TRUE
43559 * Here is an example for iterating with g_win32_registry_subkey_iter_next():
43560 * |[<!-- language="C" -->
43561 * // recursively iterate a key
43563 * iterate_key_recursive (GWin32RegistryKey *key)
43565 * GWin32RegistrySubkeyIter iter;
43567 * GWin32RegistryKey *child;
43569 * if (!g_win32_registry_subkey_iter_init (&iter, key, NULL))
43572 * while (g_win32_registry_subkey_iter_next (&iter, TRUE, NULL))
43574 * if (!g_win32_registry_subkey_iter_get_name (&iter, &name, NULL, NULL))
43577 * g_print ("subkey '%s'\n", name);
43578 * child = g_win32_registry_key_get_child (key, name, NULL);
43581 * iterate_key_recursive (child);
43584 * g_win32_registry_subkey_iter_clear (&iter);
43588 * Returns: %TRUE if next subkey info was retrieved, %FALSE otherwise.
43594 * g_win32_registry_value_iter_assign:
43595 * @iter: a #GWin32RegistryValueIter
43596 * @other: another #GWin32RegistryValueIter
43598 * Assigns the value of @other to @iter. This function
43599 * is not useful in applications, because iterators can be assigned
43600 * with `GWin32RegistryValueIter i = j;`. The
43601 * function is used by language bindings.
43608 * g_win32_registry_value_iter_clear:
43609 * @iter: (in) (transfer none): a #GWin32RegistryValueIter
43611 * Frees internal buffers of a #GWin32RegistryValueIter.
43618 * g_win32_registry_value_iter_copy:
43619 * @iter: an iterator
43621 * Creates a dynamically-allocated copy of an iterator. Dynamically-allocated
43622 * state of the iterator is duplicated too.
43624 * Returns: (transfer full): a copy of the @iter,
43625 * free with g_win32_registry_value_iter_free ().
43631 * g_win32_registry_value_iter_free:
43632 * @iter: a dynamically-allocated iterator
43634 * Free an iterator allocated on the heap. For iterators that are allocated
43635 * on the stack use g_win32_registry_value_iter_clear () instead.
43642 * g_win32_registry_value_iter_get_data:
43643 * @iter: (in) (transfer none): a #GWin32RegistryValueIter
43644 * @auto_expand: (in): %TRUE to automatically expand G_WIN32_REGISTRY_VALUE_EXPAND_STR to
43645 * G_WIN32_REGISTRY_VALUE_STR
43646 * @value_data: (out callee-allocates) (optional) (transfer none): Pointer to a
43647 * location to store the data of the value (in UTF-8, if it's a string)
43648 * @value_data_size: (out) (optional): Pointer to a location to store the length
43649 * of @value_data, in bytes (including any NUL-terminators, if it's a string).
43650 * %NULL if length is not needed
43651 * @error: (nullable): a pointer to %NULL #GError, or %NULL
43653 * Stores the data of the value currently being iterated over in @value_data,
43654 * and its length - in @value_data_len (if not %NULL).
43656 * Returns: %TRUE if value data was retrieved, %FALSE otherwise.
43662 * g_win32_registry_value_iter_get_data_w:
43663 * @iter: (in) (transfer none): a #GWin32RegistryValueIter
43664 * @auto_expand: (in): %TRUE to automatically expand G_WIN32_REGISTRY_VALUE_EXPAND_STR to
43665 * G_WIN32_REGISTRY_VALUE_STR
43666 * @value_data: (out callee-allocates) (optional) (transfer none): Pointer to a
43667 * location to store the data of the value (in UTF-16, if it's a string)
43668 * @value_data_size: (out) (optional): Pointer to a location to store the size
43669 * of @value_data, in bytes (including any NUL-terminators, if it's a string).
43670 * %NULL if length is not needed.
43671 * @error: (nullable): a pointer to %NULL #GError, or %NULL
43673 * Stores the data of the value currently being iterated over in @value_data,
43674 * and its length - in @value_data_len (if not %NULL).
43676 * Returns: %TRUE if value data was retrieved, %FALSE otherwise.
43682 * g_win32_registry_value_iter_get_name:
43683 * @iter: (in) (transfer none): a #GWin32RegistryValueIter
43684 * @value_name: (out callee-allocates) (transfer none): Pointer to a location
43685 * to store the name of a value (in UTF-8).
43686 * @value_name_len: (out) (optional): Pointer to a location to store the length
43687 * of @value_name, in gchars, excluding NUL-terminator.
43688 * %NULL if length is not needed.
43689 * @error: (nullable): a pointer to %NULL #GError, or %NULL
43691 * Stores the name of the value currently being iterated over in @value_name,
43692 * and its length - in @value_name_len (if not %NULL).
43694 * Returns: %TRUE if value name was retrieved, %FALSE otherwise.
43700 * g_win32_registry_value_iter_get_name_w:
43701 * @iter: (in) (transfer none): a #GWin32RegistryValueIter
43702 * @value_name: (out callee-allocates) (transfer none): Pointer to a location
43703 * to store the name of a value (in UTF-16).
43704 * @value_name_len: (out) (optional): Pointer to a location to store the length
43705 * of @value_name, in gunichar2s, excluding NUL-terminator.
43706 * %NULL if length is not needed.
43707 * @error: (nullable): a pointer to %NULL #GError, or %NULL
43709 * Stores the name of the value currently being iterated over in @value_name,
43710 * and its length - in @value_name (if not %NULL).
43712 * Returns: %TRUE if value name was retrieved, %FALSE otherwise.
43718 * g_win32_registry_value_iter_get_value_type:
43719 * @iter: (in) (transfer none): a #GWin32RegistryValueIter
43720 * @value_type: (out): Pointer to a location to store the type of
43722 * @error: (nullable): a pointer to %NULL #GError, or %NULL
43724 * Stores the type of the value currently being iterated over in @value_type.
43726 * Returns: %TRUE if value type was retrieved, %FALSE otherwise.
43732 * g_win32_registry_value_iter_init:
43733 * @iter: (in) (transfer none): a pointer to a #GWin32RegistryValueIter
43734 * @key: (in) (transfer none): a #GWin32RegistryKey to iterate over
43735 * @error: (nullable): a pointer to %NULL #GError, or %NULL
43737 * Initialises (without allocating) a #GWin32RegistryValueIter. @iter may be
43738 * completely uninitialised prior to this call; its old value is
43741 * The iterator remains valid for as long as @key exists.
43742 * Clean up its internal buffers with a call to
43743 * g_win32_registry_value_iter_clear() when done.
43745 * Returns: %TRUE if iterator was initialized successfully, %FALSE on error.
43751 * g_win32_registry_value_iter_n_values:
43752 * @iter: (in) (transfer none): a #GWin32RegistryValueIter
43754 * Queries the number of values items in the key that we are
43755 * iterating over. This is the total number of values -- not the number
43756 * of items remaining.
43758 * This information is accurate at the point of iterator initialization,
43759 * and may go out of sync with reality even while values are enumerated.
43761 * Returns: the number of values in the key
43767 * g_win32_registry_value_iter_next:
43768 * @iter: (in) (transfer none): a #GWin32RegistryValueIter
43769 * @skip_errors: (in): %TRUE if iterator should silently ignore errors (such as
43770 * the actual number of values being less than expected) and
43772 * @error: (nullable): a pointer to %NULL #GError, or %NULL
43774 * Advances iterator to the next value in the key. If no more values remain then
43775 * FALSE is returned.
43776 * Enumeration errors can be ignored if @skip_errors is %TRUE
43778 * Here is an example for iterating with g_win32_registry_value_iter_next():
43779 * |[<!-- language="C" -->
43780 * // iterate values of a key
43782 * iterate_values_recursive (GWin32RegistryKey *key)
43784 * GWin32RegistryValueIter iter;
43786 * GWin32RegistryValueType val_type;
43789 * if (!g_win32_registry_value_iter_init (&iter, key, NULL))
43792 * while (g_win32_registry_value_iter_next (&iter, TRUE, NULL))
43794 * if ((!g_win32_registry_value_iter_get_value_type (&iter, &value)) ||
43795 * ((val_type != G_WIN32_REGISTRY_VALUE_STR) &&
43796 * (val_type != G_WIN32_REGISTRY_VALUE_EXPAND_STR)))
43799 * if (g_win32_registry_value_iter_get_value (&iter, TRUE, &name, NULL,
43800 * &val_data, NULL, NULL))
43801 * g_print ("value '%s' = '%s'\n", name, val_data);
43804 * g_win32_registry_value_iter_clear (&iter);
43808 * Returns: %TRUE if next value info was retrieved, %FALSE otherwise.
43814 * g_zlib_compressor_get_file_info:
43815 * @compressor: a #GZlibCompressor
43817 * Returns the #GZlibCompressor:file-info property.
43819 * Returns: (nullable) (transfer none): a #GFileInfo, or %NULL
43825 * g_zlib_compressor_new:
43826 * @format: The format to use for the compressed data
43827 * @level: compression level (0-9), -1 for default
43829 * Creates a new #GZlibCompressor.
43831 * Returns: a new #GZlibCompressor
43837 * g_zlib_compressor_set_file_info:
43838 * @compressor: a #GZlibCompressor
43839 * @file_info: (nullable): a #GFileInfo
43841 * Sets @file_info in @compressor. If non-%NULL, and @compressor's
43842 * #GZlibCompressor:format property is %G_ZLIB_COMPRESSOR_FORMAT_GZIP,
43843 * it will be used to set the file name and modification time in
43844 * the GZIP header of the compressed data.
43846 * Note: it is an error to call this function while a compression is in
43847 * progress; it may only be called immediately after creation of @compressor,
43848 * or after resetting it with g_converter_reset().
43855 * g_zlib_decompressor_get_file_info:
43856 * @decompressor: a #GZlibDecompressor
43858 * Retrieves the #GFileInfo constructed from the GZIP header data
43859 * of compressed data processed by @compressor, or %NULL if @decompressor's
43860 * #GZlibDecompressor:format property is not %G_ZLIB_COMPRESSOR_FORMAT_GZIP,
43861 * or the header data was not fully processed yet, or it not present in the
43862 * data stream at all.
43864 * Returns: (nullable) (transfer none): a #GFileInfo, or %NULL
43870 * g_zlib_decompressor_new:
43871 * @format: The format to use for the compressed data
43873 * Creates a new #GZlibDecompressor.
43875 * Returns: a new #GZlibDecompressor
43881 * get_viewable_logical_drives:
43883 * Returns the list of logical and viewable drives as defined by
43884 * GetLogicalDrives() and the registry keys
43885 * Software\Microsoft\Windows\CurrentVersion\Policies\Explorer under
43886 * HKLM or HKCU. If neither key exists the result of
43887 * GetLogicalDrives() is returned.
43889 * Returns: bitmask with same meaning as returned by GetLogicalDrives()
43894 /************************************************************/
43895 /* THIS FILE IS GENERATED DO NOT EDIT */
43896 /************************************************************/